ci(release): fix release-notes generation breaking jq publish step

The release-notes echo lines used unescaped backticks, which the shell ran as command substitution; their output leaked control characters into release_notes.md, so jq failed with 'Invalid string: control characters ... must be escaped' when building the release payload. - Escape the backticks so they are literal markdown. - Remove emoji from the release-notes content (plain ASCII headings). - Handle an already-existing release (HTTP 409) by reusing its id for asset upload instead of failing.
fix(connectivity): drive reachability from real repository traffic
2026-06-23 20:38:09 +02:00 · 2026-06-21 21:56:14 +02:00 · 2026-06-21 21:55:30 +02:00 · 2026-06-21 20:44:23 +02:00 · 2026-06-21 17:38:06 +02:00 · 2026-06-21 10:48:26 +02:00
26 changed files with 1380 additions and 11161 deletions
@@ -31,9 +31,9 @@ jobs:
            ~/.cargo/registry
            ~/.cargo/git
            src-tauri/target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-host-
      - name: Cache Node dependencies
        uses: actions/cache@v3
@@ -82,9 +82,9 @@ jobs:
            ~/.cargo/registry
            ~/.cargo/git
            src-tauri/target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-android-
      - name: Cache Node dependencies
        uses: actions/cache@v3
@@ -122,7 +122,7 @@ jobs:
        id: build
        run: |
          mkdir -p artifacts
-          bun run tauri android build --apk true
+          bun run tauri android build --apk true --target aarch64
          # Find the generated APK file
          ARTIFACT=$(find src-tauri/gen/android/app/build/outputs/apk -name "*.apk" -type f -print -quit)
@@ -18,37 +18,40 @@ jobs:
  test:
    name: Run Tests
    runs-on: linux/amd64
    container:
      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
      - name: Cache Rust dependencies
        uses: actions/cache@v3
        with:
          path: |
-            ~/.cargo/bin/
+            ~/.cargo/registry
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
-            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
            target/
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-host-
      - name: Cache Node dependencies
        uses: actions/cache@v3
        with:
          path: |
            ~/.bun/install/cache
            node_modules
          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
          restore-keys: |
            ${{ runner.os }}-bun-
      - name: Install dependencies
        run: bun install
      - name: Run frontend tests
-        run: bun run test --run
+        run: |
          bunx svelte-kit sync
          bun run test --run
        continue-on-error: false
      - name: Run Rust tests
@@ -63,45 +66,32 @@ jobs:
    name: Build Linux
    runs-on: linux/amd64
    needs: test
    container:
      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libwebkit2gtk-4.1-dev \
            build-essential \
            curl \
            wget \
            file \
            libssl-dev \
            libgtk-3-dev \
            libayatana-appindicator3-dev \
            librsvg2-dev
      - name: Cache Rust dependencies
        uses: actions/cache@v3
        with:
          path: |
-            ~/.cargo/bin/
+            ~/.cargo/registry
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
-            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
            target/
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-host-
      - name: Cache Node dependencies
        uses: actions/cache@v3
        with:
          path: |
            ~/.bun/install/cache
            node_modules
          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
          restore-keys: |
            ${{ runner.os }}-bun-
      - name: Install dependencies
        run: bun install
@@ -135,59 +125,40 @@ jobs:
    name: Build Android
    runs-on: linux/amd64
    needs: test
    container:
      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
    env:
      ANDROID_HOME: /opt/android-sdk
      ANDROID_SDK_ROOT: /opt/android-sdk
      ANDROID_NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
      - name: Setup Java
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
      - name: Setup Android SDK
        uses: android-actions/setup-android@v2
        with:
          api-level: 33
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
      - name: Add Android targets
        run: |
          rustup target add aarch64-linux-android
          rustup target add armv7-linux-androideabi
          rustup target add x86_64-linux-android
      - name: Install Android NDK
        run: |
          sdkmanager "ndk;25.1.8937393"
      - name: Cache Rust dependencies
        uses: actions/cache@v3
        with:
          path: |
-            ~/.cargo/bin/
+            ~/.cargo/registry
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
            ~/.cargo/git/db/
            target/
          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-cargo-android-
      - name: Cache Node dependencies
        uses: actions/cache@v3
        with:
          path: |
            ~/.bun/install/cache
            node_modules
          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
          restore-keys: |
            ${{ runner.os }}-bun-
      - name: Install dependencies
        run: bun install
      - name: Resolve Android NDK path
        run: echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.1.8937393" >> "$GITHUB_ENV"
      - name: Set app version from tag
        run: |
          REF="${GITHUB_REF#refs/tags/v}"
@@ -201,8 +172,6 @@ jobs:
      - name: Initialize Android project
        run: bun run tauri android init
        env:
          ANDROID_NDK_HOME: ${{ env.ANDROID_NDK_HOME }}
      - name: Sync custom Android sources & gradle config
        run: ./scripts/sync-android-sources.sh
@@ -218,11 +187,7 @@ jobs:
          EOF
      - name: Build signed Android APK
-        run: bun run tauri android build --apk
+        run: bun run tauri android build --apk true --target aarch64
        env:
          ANDROID_NDK_HOME: ${{ env.ANDROID_NDK_HOME }}
          ANDROID_SDK_ROOT: ${{ env.ANDROID_SDK_ROOT }}
          ANDROID_HOME: ${{ env.ANDROID_SDK_ROOT }}
      - name: Collect & verify signed APK
        run: |
@@ -247,6 +212,8 @@ jobs:
    runs-on: linux/amd64
    needs: [build-linux, build-android]
    if: startsWith(github.ref, 'refs/tags/v')
    container:
      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
@@ -273,23 +240,23 @@ jobs:
        id: release_notes
        run: |
          VERSION="${{ steps.tag_name.outputs.VERSION }}"
-          echo "## 📱 JellyTau $VERSION Release" > release_notes.md
+          echo "## JellyTau $VERSION Release" > release_notes.md
          echo "" >> release_notes.md
-          echo "### 📦 Downloads" >> release_notes.md
+          echo "### Downloads" >> release_notes.md
          echo "" >> release_notes.md
          echo "#### Linux" >> release_notes.md
          echo "- **AppImage** - Run directly on most Linux distributions" >> release_notes.md
-          echo "- **DEB** - Install via `sudo dpkg -i jellytau_*.deb` (Ubuntu/Debian)" >> release_notes.md
+          echo "- **DEB** - Install via \`sudo dpkg -i jellytau_*.deb\` (Ubuntu/Debian)" >> release_notes.md
          echo "" >> release_notes.md
          echo "#### Android" >> release_notes.md
-          echo "- **APK** - Install via `adb install jellytau-release.apk` or sideload via file manager" >> release_notes.md
+          echo "- **APK** - Install via \`adb install jellytau-release.apk\` or sideload via file manager" >> release_notes.md
          echo "- **AAB** - Upload to Google Play Console or testing platforms" >> release_notes.md
          echo "" >> release_notes.md
-          echo "### ✨ What's New" >> release_notes.md
+          echo "### What's New" >> release_notes.md
          echo "" >> release_notes.md
          echo "See [CHANGELOG.md](CHANGELOG.md) for detailed changes." >> release_notes.md
          echo "" >> release_notes.md
-          echo "### 🔧 Installation" >> release_notes.md
+          echo "### Installation" >> release_notes.md
          echo "" >> release_notes.md
          echo "#### Linux (AppImage)" >> release_notes.md
          echo "\`\`\`bash" >> release_notes.md
@@ -307,11 +274,11 @@ jobs:
          echo "- Sideload: Download APK and install via file manager or ADB" >> release_notes.md
          echo "- Play Store: Coming soon" >> release_notes.md
          echo "" >> release_notes.md
-          echo "### 🐛 Known Issues" >> release_notes.md
+          echo "### Known Issues" >> release_notes.md
          echo "" >> release_notes.md
          echo "See [GitHub Issues](../../issues) for reported bugs." >> release_notes.md
          echo "" >> release_notes.md
-          echo "### 📝 Requirements" >> release_notes.md
+          echo "### Requirements" >> release_notes.md
          echo "" >> release_notes.md
          echo "**Linux:**" >> release_notes.md
          echo "- 64-bit Linux system" >> release_notes.md
@@ -322,7 +289,7 @@ jobs:
          echo "- 50MB free storage" >> release_notes.md
          echo "" >> release_notes.md
          echo "---" >> release_notes.md
-          echo "Built with Tauri, SvelteKit, and Rust 🦀" >> release_notes.md
+          echo "Built with Tauri, SvelteKit, and Rust" >> release_notes.md
      - name: Publish Gitea release & upload assets
        env:
@@ -346,11 +313,20 @@ jobs:
            '{tag_name:$tag, name:$name, body:$body, draft:false, prerelease:$pre}')
          echo "📦 Creating release $VERSION on $REPO"
-          RESP=$(curl -fsS -X POST "$API/repos/$REPO/releases" \
+          # -f drops on HTTP error; capture status so an existing release (409) is handled gracefully.
          HTTP=$(curl -sS -o resp.json -w '%{http_code}' -X POST "$API/repos/$REPO/releases" \
            -H "Authorization: token $TOKEN" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD")
-          RELEASE_ID=$(echo "$RESP" | jq -r '.id')
+          if [ "$HTTP" = "201" ]; then
            RELEASE_ID=$(jq -r '.id' resp.json)
          elif [ "$HTTP" = "409" ]; then
            echo "ℹ️  Release $VERSION already exists; fetching its id to upload assets"
            RELEASE_ID=$(curl -fsS "$API/repos/$REPO/releases/tags/$VERSION" \
              -H "Authorization: token $TOKEN" | jq -r '.id')
          else
            echo "❌ Failed to create release (HTTP $HTTP):"; cat resp.json; exit 1
          fi
          echo "Release id=$RELEASE_ID"
          for f in artifacts/android/* artifacts/linux/*; do
@@ -9,6 +9,11 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 # Use bun (see packageManager in package.json); ignore other package managers' lockfiles
 package-lock.json
 yarn.lock
 pnpm-lock.yaml
 # Build output
 /build
 /dist
@@ -7,7 +7,8 @@ FROM ubuntu:24.04
 ENV DEBIAN_FRONTEND=noninteractive \
    ANDROID_HOME=/opt/android-sdk \
    NDK_VERSION=27.0.11902837 \
-    SDK_VERSION=34 \
+    SDK_VERSION=36 \
    BUILD_TOOLS_VERSION=35.0.0 \
    RUST_BACKTRACE=1 \
    PATH="/root/.bun/bin:/root/.cargo/bin:$PATH" \
    CARGO_HOME=/root/.cargo
@@ -68,10 +69,14 @@ RUN wget -q https://dl.google.com/android/repository/commandlinetools-linux-1107
    mkdir -p $ANDROID_HOME/cmdline-tools/latest && \
    mv $ANDROID_HOME/cmdline-tools/* $ANDROID_HOME/cmdline-tools/latest/ 2>/dev/null || true
-# Install Android SDK components
+# Accept all SDK licenses up front so Gradle can install/use components non-interactively
 RUN yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --sdk_root=$ANDROID_HOME --licenses > /dev/null
 # Install Android SDK components (must match the compileSdk/targetSdk in the generated Gradle project)
 RUN $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --sdk_root=$ANDROID_HOME \
    "platform-tools" \
    "platforms;android-$SDK_VERSION" \
-    "build-tools;34.0.0" \
+    "build-tools;$BUILD_TOOLS_VERSION" \
    "ndk;$NDK_VERSION" \
    --channel=0 2>&1 | grep -v "Warning" || true
@@ -2,335 +2,25 @@
 A cross-platform Jellyfin client built with Tauri, SvelteKit, and TypeScript.
-## Recommended IDE Setup
+Business logic lives in a Rust backend; a UI-rich Svelte frontend handles
 presentation and talks to it over Tauri's IPC. Targets Linux (libmpv) and
 Android (ExoPlayer).
-[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
+## Getting Started
---
+This project uses [bun](https://bun.sh) as its package manager.
 # Requirements Specification
 ## 1. User Requirements
 | ID | Requirement | Priority | Status |
 |----|-------------|----------|--------|
 | UR-001 | Run the app on multiple platforms (Linux, Android) | High | In Progress |
 | UR-002 | Access media when online or offline | High | Done |
 | UR-003 | Play videos | High | Done |
 | UR-004 | Play audio uninterrupted | High | Done |
 | UR-005 | Control media playback (pause, play, skip, scrub) | High | Done |
 | UR-006 | Control media when device is on lock screen or via BLE headsets | Medium | Done |
 | UR-007 | Navigate media in library | High | Done |
 | UR-008 | Search media across libraries | High | Done |
 | UR-009 | Connect to Jellyfin to access media | High | Done |
 | UR-010 | Control playback of Jellyfin remote sessions | Low | Done |
 | UR-011 | Download media on demand | Medium | Done |
 | UR-012 | Login info shall be stored securely and persistently | High | Done |
 | UR-013 | View and manage downloaded media | Medium | Done |
 | UR-014 | Make and edit playlists of music that sync back to Jellyfin | Medium | Done |
 | UR-015 | View and manage current audio queue (add, reorder tracks) | Medium | Done |
 | UR-016 | Change system settings while playing (brightness, volume) | Low | Planned |
 | UR-017 | Like or unlike audio, albums, movies, etc. | Medium | Done |
 | UR-018 | Choose to download series, albums, songs, artist discography | Medium | Done |
 | UR-019 | Resume playback from where you left off (movies, shows, albums) | High | Done |
 | UR-020 | Select subtitles for video content | High | Done |
 | UR-021 | Select audio track for video content | High | Done |
 | UR-022 | Control streaming quality and transcoding settings | Medium | Planned |
 | UR-023 | View "Next Up" / Continue Watching on home screen; auto-play next episode with countdown popup and configurable episode limit | Medium | Done |
 | UR-024 | View recently added content on server | Medium | Done |
 | UR-025 | Sync watch history and progress back to Jellyfin | High | Done |
 | UR-026 | Sleep timer for audio and video playback (roller UI, time/track/episode modes) | Low | Done |
 | UR-027 | Audio equalizer for sound customization | Low | Planned |
 | UR-028 | Navigate to artist/album by tapping names in now playing view | High | Done |
 | UR-029 | Toggle between grid and list view in library | Medium | Done |
 | UR-030 | Quick genre browsing and filtering | Medium | Done |
 | UR-031 | Crossfade between audio tracks | Low | Done (Linux only) |
 | UR-032 | Gapless playback for seamless album listening | Medium | Done (Linux only) |
 | UR-033 | Volume normalization to prevent volume jumps between tracks | Low | Done (Linux only) |
 | UR-034 | Rich home screen with hero banners, carousels, and personalized sections | High | Done |
 | UR-035 | View cast/crew (actors, directors) on movie/show detail pages | High | Done |
 | UR-036 | Navigate to actor/person page showing their filmography | Medium | Done |
 | UR-037 | Visually appealing video library with poster grids and metadata | High | Done |
 | UR-038 | Movie/show detail page with backdrop, ratings, and rich metadata | High | Done |
 | UR-039 | Navigate between main sections via bottom navigation bar | High | Done |
 ---
 ## 2. Software Requirements
 ### 2.1 Integration Requirements
 External system integrations and platform-specific implementations.
 | ID | Requirement | Category | Traces To | Status |
 |----|-------------|----------|-----------|--------|
 | IR-001 | Build system supporting multiple targets (Linux, Android) | Build | UR-001 | Done |
 | IR-002 | Build scripts for Android and Linux | Build | UR-001 | Done |
 | IR-003 | Integration of libmpv for Linux playback | Playback | UR-003, UR-004 | Done |
 | IR-004 | Integration of ExoPlayer for Android playback | Playback | UR-003, UR-004 | In Progress (basic playback works, audio settings missing) |
 | IR-005 | MPRIS D-Bus integration for Linux lockscreen/media controls | Platform | UR-006 | Planned |
 | IR-006 | Android MediaSession integration for lockscreen controls | Platform | UR-006 | Done |
 | IR-007 | Bluetooth AVRCP integration via system media session | Platform | UR-006 | Planned |
 | IR-008 | Android audio focus handling (pause on call) | Platform | UR-004, UR-006 | Done |
 | IR-009 | Jellyfin API client for authentication | API | UR-009, UR-012 | Done |
 | IR-010 | Jellyfin API client for library browsing | API | UR-007, UR-008 | Done |
 | IR-011 | Jellyfin API client for playback streaming | API | UR-003, UR-004 | Done |
 | IR-012 | Jellyfin Sessions API for remote playback control | API | UR-010 | Done |
 | IR-021 | Android MediaRouter integration for remote volume in system panel | Platform | UR-010, UR-016 | Planned |
 | IR-013 | SQLite integration for local database | Storage | UR-002, UR-011 | Done |
 | IR-014 | Secure credential storage (keyring/keychain) | Security | UR-012 | Done |
 | IR-015 | Jellyfin API client for playback progress reporting | API | UR-019, UR-025 | Done |
 | IR-016 | Jellyfin API client for subtitle/audio track info | API | UR-020, UR-021 | Done |
 | IR-017 | Jellyfin API client for transcoding parameters | API | UR-022 | Planned |
 | IR-018 | libmpv subtitle rendering and selection | Playback | UR-020 | Planned |
 | IR-019 | libmpv audio track selection | Playback | UR-021 | Planned |
 | IR-020 | libmpv/ExoPlayer equalizer integration | Playback | UR-027 | Planned |
 | IR-022 | Jellyfin API client for person/cast data | API | UR-035, UR-036 | Done |
 | IR-023 | Database schema for person/cast caching | Storage | UR-035, UR-036 | Done |
 | IR-024 | Jellyfin API client for home screen data (featured, continue watching) | API | UR-034 | Done |
 ### 2.2 Jellyfin API Requirements
 API endpoints and data contracts required for Jellyfin integration.
 | ID | Requirement | Endpoint Category | Traces To | Status |
 |----|-------------|-------------------|-----------|--------|
 | JA-001 | Server connection and discovery | System | UR-009 | Done |
 | JA-002 | User authentication (username/password) | Users | UR-009, UR-012 | Done |
 | JA-003 | Get user library views | UserViews | UR-007 | Done |
 | JA-004 | Get library items (paginated) | Items | UR-007 | Done |
 | JA-005 | Get item details and metadata | Items | UR-007 | Done |
 | JA-006 | Search across libraries | Items | UR-008 | Done |
 | JA-007 | Get playback info and stream URL | MediaInfo | UR-003, UR-004 | Done |
 | JA-008 | Get available subtitles for item | MediaInfo | UR-020 | Done |
 | JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Done |
 | JA-010 | Report playback start | Sessions | UR-025 | Done |
 | JA-011 | Report playback progress (periodic) | Sessions | UR-025 | Done |
 | JA-012 | Report playback stopped | Sessions | UR-025 | Done |
 | JA-013 | Get resume position for item | UserData | UR-019 | Done |
 | JA-014 | Get "Next Up" items | Shows | UR-023 | Done |
 | JA-015 | Get "Continue Watching" items | Items | UR-023 | Done |
 | JA-016 | Get recently added items | Items | UR-024 | Done |
 | JA-017 | Mark item as favorite | UserData | UR-017 | Done |
 | JA-018 | Remove item from favorites | UserData | UR-017 | Done |
 | JA-019 | Get/create/update playlists | Playlists | UR-014 | Done |
 | JA-020 | Add/remove items from playlist | Playlists | UR-014 | Done |
 | JA-021 | Get active sessions list | Sessions | UR-010 | Done |
 | JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Done |
 | JA-023 | Send seek command to remote session | Sessions | UR-010 | Done |
 | JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Done |
 | JA-025 | Play specific item on remote session | Sessions | UR-010 | Done |
 | JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Done |
 | JA-027 | Get transcoding options | MediaInfo | UR-022 | Planned |
 | JA-028 | Get image/artwork URLs | Images | UR-007 | Done |
 | JA-029 | Get cast/crew for item (actors, directors) | Items | UR-035 | Done |
 | JA-030 | Get person details and filmography | Persons | UR-036 | Done |
 | JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
 ### 2.3 Development Requirements
 Internal architecture, components, and application logic.
 | ID | Requirement | Category | Traces To | Status |
 |----|-------------|----------|-----------|--------|
 | DR-001 | Player state machine (idle, loading, playing, paused, seeking, error) | Player | UR-005 | Done |
 | DR-002 | MediaItem struct tracking source, location, duration, metadata | Player | UR-003, UR-004 | Done |
 | DR-003 | Source-agnostic media abstraction (Remote, Local, DirectUrl) | Player | UR-002, UR-011 | Done |
 | DR-004 | PlayerBackend trait for platform-agnostic playback | Player | UR-003, UR-004 | Done |
 | DR-005 | Queue manager with shuffle, repeat, history | Player | UR-005, UR-015 | Done |
 | DR-006 | Audio pre-caching for seamless track transitions | Player | UR-004 | Planned |
 | DR-007 | Library browsing screens (grid view, search, filters) | UI | UR-007, UR-008 | Done |
 | DR-008 | Album/Series detail view with track listing | UI | UR-007 | Done |
 | DR-009 | Audio player UI (mini player, full screen) | UI | UR-005 | Done |
 | DR-010 | Video player UI (fullscreen, controls overlay) | UI | UR-003, UR-005 | Done |
 | DR-011 | Search bar with cross-library search | UI | UR-008 | Done |
 | DR-012 | Local database for media metadata cache | Storage | UR-002 | Done |
 | DR-013 | Repository pattern for online/offline data access | Storage | UR-002 | Done |
 | DR-014 | Offline mutation queue for sync-back operations | Storage | UR-002, UR-014, UR-017 | Done |
 | DR-015 | Download manager with queue and progress tracking | Storage | UR-011, UR-018 | Done |
 | DR-016 | Thumbnail caching and sync with server | Storage | UR-007 | Done |
 | DR-017 | "Manage Downloads" screen for local media management | UI | UR-013 | Done |
 | DR-018 | Download buttons on library/album/player screens | UI | UR-011, UR-018 | Done |
 | DR-019 | Playlist creation and editing UI | UI | UR-014 | Done |
 | DR-020 | Queue management UI (add, remove, reorder) | UI | UR-015 | Done |
 | DR-021 | Like/favorite functionality on media items | UI | UR-017 | Done |
 | DR-022 | Resume position tracking and restoration on play | Player | UR-019 | Done |
 | DR-023 | Subtitle selection UI in video player | UI | UR-020 | Done |
 | DR-024 | Audio track selection UI in video player | UI | UR-021 | Done |
 | DR-025 | Quality/transcoding settings UI | UI | UR-022 | Planned |
 | DR-026 | "Continue Watching" / "Next Up" home section | UI | UR-023 | Done |
 | DR-027 | "Recently Added" home section | UI | UR-024 | Done |
 | DR-028 | Playback progress sync service (periodic reporting) | Player | UR-025 | Done |
 | DR-029 | Sleep timer with roller UI, time/track/episode modes, and auto-stop (audio + video players) | Player | UR-026 | Done |
 | DR-049 | Auto-play episode limit (configurable max episodes per session) | Player | UR-023 | Done |
 | DR-050 | Reusable scroll picker (roller) component | UI | UR-026 | Done |
 | DR-030 | Equalizer UI with presets and custom bands | UI | UR-027 | Planned |
 | DR-031 | Clickable artist/album links in now playing view | UI | UR-028 | Done |
 | DR-032 | List view option for library browsing (albums, artists) | UI | UR-029 | Done |
 | DR-033 | Genre browsing screen with quick filters | UI | UR-030 | Done |
 | DR-034 | Crossfade engine with configurable duration (0-12s) | Player | UR-031 | Done (Linux only) |
 | DR-035 | Gapless playback between sequential tracks | Player | UR-032 | Done (Linux only) |
 | DR-036 | Volume normalization with preset levels (Loud/Normal/Quiet) | Player | UR-033 | Done (Linux only) |
 | DR-037 | Remote session browser and control UI | UI | UR-010 | Done |
 | DR-038 | Home screen with hero banner carousel (featured/continue watching) | UI | UR-034 | Done |
 | DR-039 | Home screen horizontal carousels (recently added, recommendations) | UI | UR-034, UR-024 | Done |
 | DR-040 | Cast/crew section on movie/show detail pages | UI | UR-035 | Done |
 | DR-041 | Person/actor detail page with filmography grid | UI | UR-036 | Done |
 | DR-042 | Video library grid with poster cards, year, and rating badges | UI | UR-037 | Done |
 | DR-043 | Movie/show detail page with backdrop hero, synopsis, and metadata | UI | UR-038 | Done |
 | DR-044 | Horizontal scrolling actor/cast row with profile images | UI | UR-035 | Done |
 | DR-045 | Bottom navigation bar with Home, Library, Search buttons | UI | UR-039 | Done |
 | DR-046 | Dedicated search page with input and results | UI | UR-039 | Done |
 | DR-047 | Next episode auto-play popup with configurable countdown and episode limit | Player | UR-023 | Done |
 | DR-048 | Video settings (auto-play toggle, countdown duration, episode limit) | Settings | UR-023, UR-026 | Done |
 ---
 ## 3. Traceability Matrix
 ### User Requirements to Software Requirements
 | User Req | Integration Requirements | Development Requirements |
 |----------|-------------------------|-------------------------|
 | 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-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 |
 | UR-008 | IR-010 | DR-007, DR-011 |
 | UR-009 | IR-009, IR-010, IR-011 | - |
 | UR-010 | IR-012, IR-021 | DR-037 |
 | UR-011 | IR-013 | DR-003, DR-015, DR-018 |
 | UR-012 | IR-009, IR-014 | - |
 | UR-013 | IR-013 | DR-017 |
 | UR-014 | IR-010 | DR-014, DR-019 |
 | UR-015 | - | DR-005, DR-020 |
 | UR-016 | - | - |
 | UR-017 | - | DR-014, DR-021 |
 | UR-018 | IR-013 | DR-015, DR-018 |
 | UR-019 | IR-015 | DR-022 |
 | UR-020 | IR-016, IR-018 | DR-023 |
 | UR-021 | IR-016, IR-019 | DR-024 |
 | 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-026 | - | DR-029, DR-048, DR-050 |
 | UR-027 | IR-020 | DR-030 |
 | UR-028 | - | DR-031 |
 | UR-029 | - | DR-032 |
 | UR-030 | IR-010 | DR-033 |
 | UR-031 | - | DR-034 |
 | UR-032 | - | DR-035 |
 | UR-033 | - | DR-036 |
 | UR-034 | IR-010, IR-024 | DR-038, DR-039 |
 | UR-035 | IR-022, IR-023 | DR-040, DR-044 |
 | UR-036 | IR-022, IR-023 | DR-041 |
 | UR-037 | IR-010 | DR-042 |
 | UR-038 | IR-010 | DR-043 |
 | UR-039 | - | DR-045, DR-046 |
 ---
 ## 4. Test Traceability
 ### Unit Tests to Software Requirements
 | Test ID | Test Description | Traces To | Status |
 |---------|-----------------|-----------|--------|
 | UT-001 | Player state transitions | DR-001 | Pending |
 | UT-002 | MediaItem source URL resolution | DR-002, DR-003 | Pending |
 | UT-003 | Queue next/previous navigation | DR-005 | Pending |
 | UT-004 | Queue shuffle order generation | DR-005 | Pending |
 | UT-005 | Queue repeat mode behavior | DR-005 | Pending |
 | UT-006 | Jellyfin authentication flow | IR-009 | Pending |
 | UT-007 | Jellyfin library items parsing | IR-010 | Pending |
 | UT-008 | Repository pattern online/offline switching | DR-013 | Pending |
 | UT-009 | Offline mutation queue persistence | DR-014 | Pending |
 | UT-010 | Download queue management | DR-015 | Done |
 | UT-011 | Resume position storage and retrieval | DR-022 | Pending |
 | UT-012 | Sleep timer countdown logic | DR-029 | Pending |
 | UT-013 | Playback progress reporting throttling | DR-028 | Pending |
 | UT-014 | Database open and in-memory mode | IR-013, DR-012 | Done |
 | UT-015 | Database migrations run successfully | IR-013, DR-012 | Done |
 | UT-016 | All database tables created | IR-013, DR-012 | Done |
 | UT-017 | FTS5 search table created | IR-013, DR-012 | Done |
 | UT-018 | Server CRUD operations | IR-013, DR-012 | Done |
 | UT-019 | User CRUD operations | IR-013, DR-012 | Done |
 | UT-020 | Cascade delete server removes users | IR-013, DR-012 | Done |
 | UT-021 | Item insert and FTS search | IR-013, DR-012 | Done |
 | UT-022 | User data playback position storage | IR-013, DR-012, DR-022 | Done |
 | UT-023 | Sync queue operations | IR-013, DR-014 | Done |
 | UT-024 | Downloads table operations | IR-013, DR-015 | Done |
 | UT-025 | Migrations are idempotent | IR-013, DR-012 | Done |
 | UT-026 | NullBackend volume default value | DR-004 | Done |
 | UT-027 | NullBackend set volume | DR-004 | Done |
 | UT-028 | NullBackend volume clamping (high/low) | DR-004 | Done |
 | UT-029 | NullBackend volume boundary values | DR-004 | Done |
 | UT-030 | PlayerController volume default | DR-004, DR-009 | Done |
 | UT-031 | PlayerController set volume | DR-004, DR-009 | Done |
 | UT-032 | PlayerController muted default | DR-004, DR-009 | Done |
 | UT-033 | PlayerController volume delegates to backend | DR-004, DR-009 | Done |
 | UT-034 | Download event serialization roundtrip | DR-015 | Done |
 | UT-035 | Download event completed serialization | DR-015 | Done |
 | UT-036 | Download event failed serialization | DR-015 | Done |
 | UT-037 | Download worker exponential backoff | DR-015 | Done |
 | UT-038 | Download worker error retryable check | DR-015 | Done |
 | UT-039 | Download manager creation | DR-015 | Done |
 | UT-040 | Download manager set max concurrent | DR-015 | Done |
 | UT-041 | Download info serialization | DR-015 | Done |
 | UT-042 | Download command filename sanitization | DR-015, DR-018 | Done |
 | UT-043 | Download command filename extension preservation | DR-015, DR-018 | Done |
 | UT-044 | Offline item serialization | DR-017 | Done |
 | UT-045 | Smart cache default config | DR-015 | Done |
 | UT-046 | Smart cache album affinity tracking | DR-015 | Done |
 | UT-047 | Smart cache queue precache config | DR-015 | Done |
 | UT-048 | Smart cache storage limit check | DR-015 | Done |
 | UT-049 | Playlist create (offline) | DR-019, JA-019 | Done |
 | UT-050 | Playlist delete (offline) | DR-019, JA-019 | Done |
 | UT-051 | Playlist rename (offline) | DR-019, JA-019 | Done |
 | UT-052 | Playlist get items (offline) | DR-019, JA-019 | Done |
 | UT-053 | Playlist add items (offline) | DR-019, JA-020 | Done |
 | UT-054 | Playlist remove items (offline) | DR-019, JA-020 | Done |
 | UT-055 | Playlist reorder items (offline) | DR-019, JA-020 | Done |
 | UT-056 | Playlist entry serialization | DR-019, JA-019 | Done |
 | UT-057 | Playlist Tauri command param naming (camelCase) | DR-019, JA-019, JA-020 | Done |
 | UT-058 | Playlist repository client methods | DR-019, JA-019, JA-020 | Done |
 ### Integration Tests
 | Test ID | Test Description | Traces To | Status |
 |---------|-----------------|-----------|--------|
 | IT-001 | End-to-end authentication with Jellyfin server | IR-009, UR-009 | Pending |
 | IT-002 | Library browsing and item loading | IR-010, UR-007 | Pending |
 | IT-003 | Audio playback via libmpv | IR-003, UR-004 | Pending |
 | IT-004 | Video playback via libmpv | IR-003, UR-003 | Pending |
 | IT-005 | MPRIS lockscreen controls on Linux | IR-005, UR-006 | Pending |
 | IT-006 | Offline mode with local database | IR-013, UR-002 | Pending |
 | IT-007 | Media download and local playback | DR-015, UR-011 | Pending |
 | IT-008 | Subtitle track selection via libmpv | IR-018, UR-020 | Pending |
 | IT-009 | Audio track selection via libmpv | IR-019, UR-021 | Pending |
 | IT-010 | Playback progress sync to Jellyfin | IR-015, UR-025 | Pending |
 | IT-011 | Resume playback from server position | IR-015, UR-019 | Pending |
 | IT-012 | Equalizer bands via libmpv | IR-020, UR-027 | Pending |
 ---
 ## 5. Development Commands
 ```bash
-# Activate Rust environment (fish shell)
+# Activate the Rust environment (fish shell)
 source "$HOME/.cargo/env.fish"
 # Install dependencies
 bun install
-# Development
+# Run in development
 bun run tauri dev
-# Type checking
+# Type-check the frontend
 bun run check
 # Build for Linux
@@ -340,168 +30,28 @@ bun run tauri build
 bun run tauri android build
 ```
---
+For the full set of build, test, and Android helper scripts, see
 [scripts/README.md](scripts/README.md).
-## 6. Architecture Overview
+## Documentation
-```
+| Topic | Location |
-jellytau/
+|-------|----------|
-├── src/                          # Svelte frontend
+| Architecture overview & subsystem docs | [docs/architecture/](docs/architecture/) |
-│   ├── lib/
+| Requirements, traceability & technical debt | [docs/requirements.md](docs/requirements.md) |
-│   │   ├── api/                  # Jellyfin API client (repository pattern)
+| Build & release process | [docs/build-release.md](docs/build-release.md) |
-│   │   ├── components/           # UI components (player, library)
+| Docker builds | [docs/build/docker.md](docs/build/docker.md) |
-│   │   └── stores/               # Svelte stores (auth, library, player, queue)
+| Traceability tooling & CI | [docs/traceability.md](docs/traceability.md), [docs/traceability-ci.md](docs/traceability-ci.md) |
-│   └── routes/                   # SvelteKit pages
+| Release checklist | [docs/release-checklist.md](docs/release-checklist.md) |
-├── src-tauri/                    # Rust backend
+| UX flows | [docs/ux-flows.md](docs/ux-flows.md) |
 │   ├── src/
 │   │   ├── commands/             # Tauri commands
 │   │   └── player/               # Player architecture
 │   │       ├── state.rs          # State machine
 │   │       ├── media.rs          # MediaItem, MediaSource
 │   │       ├── queue.rs          # Queue management
 │   │       └── backend.rs        # PlayerBackend trait
 │   └── gen/android/              # Android project
 └── README.md
 ```
---
+## Recommended IDE Setup
-## 7. Technical Debt
+[VS Code](https://code.visualstudio.com/) +
 [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) +
 [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) +
 [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
-### Linux Keyring Integration Workaround
+## License
-**Issue**: The `keyring-rs` crate (v3.x) has issues with retrieving credentials from the Linux Secret Service API, despite successfully saving them.
+MIT
 **Symptoms**:
 - Credentials are saved to the system keyring successfully (verified with `secret-tool search`)
 - Retrieval via the `keyring-rs` library fails with `NoEntry` error
 - Session restoration fails on app restart even though credentials exist
 **Root Cause**:
 The `keyring-rs` library's Linux backend doesn't correctly retrieve entries from the Secret Service that it previously stored. This appears to be a bug in how the library interfaces with the Secret Service D-Bus API.
 **Current Workaround**:
 We bypass the `keyring-rs` library on Linux and use direct system calls to `secret-tool`:
 - **Save**: `secret-tool store --label <label> service <service> username <username>`
 - **Retrieve**: `secret-tool lookup service <service> username <username>`
 - **Delete**: `secret-tool clear service <service> username <username>`
 **Implementation**:
 See [src-tauri/src/credentials.rs](src-tauri/src/credentials.rs):
 - Lines 165-209: `save_to_keyring()` - Uses `secret-tool store` on Linux
 - Lines 214-248: `get_from_keyring()` - Uses `secret-tool lookup` on Linux
 - Lines 254-286: `delete_from_keyring()` - Uses `secret-tool clear` on Linux
 **Future Fix**:
 - Monitor `keyring-rs` for bug fixes in future versions
 - Consider alternative secure storage libraries
 - Test if newer versions of `keyring-rs` (v4.x+) resolve the issue
 - Once fixed, remove the Linux-specific workaround and use the cross-platform `keyring-rs` API
 **Impact**:
 - Low - The workaround is functionally equivalent to proper keyring integration
 - Credentials are stored securely in the system keyring
 - Session restoration works correctly
 - Only affects Linux; macOS and Windows use the standard `keyring-rs` implementation
 **Dependencies**:
 - Requires `secret-tool` to be installed on Linux systems (part of `libsecret-tools` package)
 - Already available on most Linux distributions by default
 ---
 ### Platform Playback Backend Parity (Linux vs Android)
 **Issue**: The Linux (MPV) and Android (ExoPlayer) playback backends have diverged in feature implementation and architecture patterns.
 **Symptoms**:
 - Audio settings (crossfade, gapless playback, volume normalization) work on Linux but not on Android
 - Position update frequency differs between platforms (Linux: 250ms polling, Android: on-demand callbacks)
 - Thread safety models differ (Linux: `Arc<Mutex<>>`, Android: global `OnceLock` statics)
 **Root Cause**:
 The `PlayerBackend` trait defines optional audio settings methods with default empty implementations. The Linux `MpvBackend` overrides these with full MPV property commands, but `ExoPlayerBackend` uses the defaults.
 **Affected Files**:
 - [src-tauri/src/player/backend.rs:95-103](src-tauri/src/player/backend.rs) - Trait with default empty implementations
 - [src-tauri/src/player/mpv/mod.rs](src-tauri/src/player/mpv/mod.rs) - Full audio settings support
 - [src-tauri/src/player/android/mod.rs](src-tauri/src/player/android/mod.rs) - Missing audio settings implementation
 **Feature Parity Matrix**:
 | Feature | Linux (MPV) | Android (ExoPlayer) | Status |
 |---------|-------------|---------------------|--------|
 | Basic playback | ✅ | ✅ | Parity |
 | Volume control | ✅ | ✅ | Parity |
 | Seek | ✅ | ✅ | Parity |
 | Crossfade | ✅ | ❌ | Gap |
 | Gapless playback | ✅ | ❌ | Gap |
 | Volume normalization | ✅ | ❌ | Gap |
 | Position updates | 250ms | On-demand | Inconsistent |
 **Future Fix**:
 1. Implement `set_audio_settings()` in `ExoPlayerBackend`
 2. Add Kotlin-side ExoPlayer configuration for crossfade (using `ConcatenatingMediaSource` or `DefaultMediaSourceFactory`)
 3. Implement gapless via ExoPlayer's built-in gapless support
 4. Add volume normalization via ExoPlayer's `LoudnessEnhancer` or audio processor
 5. Standardize position update frequency across platforms
 **Impact**:
 - Medium - Android users lack audio enhancement features advertised in requirements
 - User experience differs between platforms
 - UR-031 (Crossfade), UR-032 (Gapless), UR-033 (Normalization) only work on Linux
 **Traces To**: IR-004, UR-031, UR-032, UR-033, DR-034, DR-035, DR-036
 ---
 ### Frontend Playback Code Duplication
 **Issue**: Playback control handlers and state derivations are duplicated between `AudioPlayer.svelte` and `MiniPlayer.svelte`.
 **Symptoms**:
 - Identical try-catch wrapped handler functions in both components (~44 lines duplicated)
 - Same `$derived` state merging logic for local/remote playback in both components
 - Position conversion (ticks ↔ seconds) scattered across multiple files
 **Affected Files**:
 - [src/lib/components/player/AudioPlayer.svelte:69-140](src/lib/components/player/AudioPlayer.svelte) - Duplicate handlers
 - [src/lib/components/player/MiniPlayer.svelte:74-122](src/lib/components/player/MiniPlayer.svelte) - Duplicate handlers
 - [src/lib/services/playbackControl.ts:88](src/lib/services/playbackControl.ts) - Position conversion
 - [src/lib/stores/playbackMode.ts](src/lib/stores/playbackMode.ts) - Position conversion
 - [src/lib/services/playbackReporting.ts](src/lib/services/playbackReporting.ts) - Position conversion
 **Duplicated Code**:
 ```typescript
 // These handlers are identical in both AudioPlayer and MiniPlayer:
 handlePlayPause(), handleNext(), handlePrevious(),
 handleToggleShuffle(), handleCycleRepeat(), handleVolumeChange()
 // These derived states use identical logic:
 displayMedia, displayIsPlaying, displayPosition, displayDuration
 ```
 **Future Fix**:
 1. Create `src/lib/utils/playbackUnits.ts`:
   ```typescript
   export const TICKS_PER_SECOND = 10_000_000;
   export const secondsToTicks = (s: number) => Math.floor(s * TICKS_PER_SECOND);
   export const ticksToSeconds = (t: number) => t / TICKS_PER_SECOND;
   ```
 2. Create `src/lib/composables/useMergedPlaybackState.svelte.ts`:
   - Export `displayMedia`, `displayIsPlaying`, `displayPosition`, `displayDuration`
   - Single source of truth for merged local/remote state
 3. Simplify handler wrappers using a utility:
   ```typescript
   export const withErrorHandler = (fn: () => Promise<void>, context: string) =>
     async () => { try { await fn(); } catch (e) { console.error(`${context}:`, e); } };
   ```
 **Impact**:
 - Low - Code works correctly but violates DRY principle
 - Maintenance burden when logic needs to change
 - Risk of handlers diverging over time
 **Traces To**: DR-009
@@ -176,7 +176,10 @@ classDiagram
        -server_url: String
        -user_id: String
        -access_token: String
        -connectivity: Option~Arc~ConnectivityMonitor~~
        +new()
        +with_connectivity()
        -report_outcome()
    }
    class OfflineRepository {
@@ -192,10 +195,9 @@ classDiagram
    class HybridRepository {
        -online: Arc~OnlineRepository~
        -offline: Arc~OfflineRepository~
        -connectivity: Arc~ConnectivityMonitor~
        +new()
-        -parallel_query()
+        -parallel_race()
-        -has_meaningful_content()
+        -cache_with_timeout()
    }
    MediaRepository <|.. OnlineRepository
@@ -214,6 +216,7 @@ classDiagram
   - Returns cache result if it has meaningful content
   - Falls back to server result otherwise
   - Background cache updates planned
   - **Connectivity feedback**: `OnlineRepository` reports the outcome of every server request to the `ConnectivityMonitor` (classified via `RepoError`). This is the source of truth for the offline/online banner — see [07-connectivity.md](07-connectivity.md). The frontend `connectivity` store is a pure reflection of the resulting events; `navigator.onLine` is only an advisory hint that triggers an immediate recheck.
 2. **Handle-Based Resource Management** (`repository.rs` commands):
   ```rust
@@ -10,6 +10,7 @@ sequenceDiagram
    participant Hybrid as HybridRepository
    participant Cache as OfflineRepository (SQLite)
    participant Server as OnlineRepository (HTTP)
    participant Conn as ConnectivityMonitor
    UI->>Client: getItems(parentId)
    Client->>Rust: invoke("repository_get_items", {handle, parentId})
@@ -20,6 +21,13 @@ sequenceDiagram
        Hybrid->>Server: get_items() (no timeout)
    end
    Note over Server,Conn: Every server request reports its outcome
    alt Server succeeds (or answers with 4xx/5xx)
        Server->>Conn: mark_reachable() (server is up)
    else Network failure / timeout
        Server->>Conn: mark_unreachable() (debounced)
    end
    alt Cache returns with content
        Cache-->>Hybrid: Result with items
        Hybrid-->>Rust: Return cache result
@@ -39,6 +47,7 @@ sequenceDiagram
 - Cache wins if it has meaningful content
 - Automatic fallback to server if cache is empty/stale
 - Background cache updates (planned)
 - **Connectivity side-effect**: each server request feeds the `ConnectivityMonitor`, which is the source of truth for the offline/online banner (see [07-connectivity.md](07-connectivity.md)). A server-answered error (401/404/5xx) still counts as *reachable* — only network failures, sustained past a debounce window, flip the app to offline.
 ## Playback Initiation Flow
@@ -13,12 +13,13 @@ pub struct HttpClient {
 }
 pub struct HttpConfig {
-    pub base_url: String,
+    pub timeout: Duration,        // Default: 30s (large library queries can be slow)
    pub timeout: Duration,        // Default: 10s
    pub max_retries: u32,         // Default: 3
 }
 ```
 > Note: ordinary requests use the 30s timeout above. The connectivity recovery probe (`ping`) uses a shorter, dedicated 5s timeout so an unreachable server is detected quickly while offline.
 **Retry Strategy:**
 - Retry delays: 1s, 2s, 4s (exponential backoff)
 - Retries on: Network errors, 5xx server errors
@@ -38,39 +39,71 @@ pub enum ErrorKind {
 **Location**: `src-tauri/src/connectivity/mod.rs`
-The connectivity monitor tracks server reachability with adaptive polling:
+The connectivity monitor is the **single source of truth** for server reachability. Its primary signal is the outcome of *real repository traffic* — every server request the user actually makes. A standalone `/System/Info/Public` probe is kept only as an offline recovery detector.
 ### Source of truth: repository traffic
 `OnlineRepository` reports the result of each server request to the monitor, classified via `RepoError`:
 | Repository outcome | Meaning | Effect on reachability |
 |--------------------|---------|------------------------|
 | `Ok(_)` | Server answered successfully | Mark **reachable** (instant recovery) |
 | `Err(Authentication)` | Server answered with 401/403 | Mark **reachable** (server is up; request was rejected) |
 | `Err(NotFound)` | Server answered with 404 | Mark **reachable** (server is up) |
 | `Err(Server)` | Server answered with 5xx / bad body | Mark **reachable** (server is up) |
 | `Err(Network)` | Connection failure / timeout / DNS | **Candidate for offline** (see debounce) |
 | `Err(Database)` | Local cache error only | No effect (not a server signal) |
 This classification fixes the previous bug where a successful `/System/Info/Public` ping reported "online" even while the user's authenticated data calls were failing — and vice versa.
 ### Time-window debounce (offline) + instant recovery (online)
 To stop the banner from flapping on a single dropped request, the transition to **offline** is debounced over a time window:
 - On the **first** `Network` failure, the monitor records `first_failure_at`.
 - It flips `is_server_reachable = false` only once `Network` failures have persisted continuously for `OFFLINE_CONFIRM_WINDOW` (5s) with no intervening success.
 - **Any** success (or server-answered error) clears `first_failure_at` and immediately marks reachable.
 Recovery is therefore instant and asymmetric: one good response brings the app back online, but a brief blip never trips the banner.
 ### Offline-only recovery probe
 ```mermaid
 flowchart TB
-    Monitor["ConnectivityMonitor"] --> Poller["Background Task"]
+    Repo["OnlineRepository"] -->|"success / RepoError"| Monitor["ConnectivityMonitor"]
-    Poller --> Check{"Server<br/>Reachable?"}
+    Monitor --> State{"is_server_reachable?"}
-    Check -->|"Yes"| Online["30s Interval"]
+    State -->|"Online"| NoProbe["No background polling<br/>(real traffic is the signal)"]
-    Check -->|"No"| Offline["5s Interval"]
+    State -->|"Offline"| Probe["5s /System/Info/Public probe<br/>(recovery detector)"]
-    Online --> Emit["Emit Events"]
+    Probe -->|"reachable again"| Monitor
-    Offline --> Emit
+    Monitor -->|"on change"| Emit["Emit connectivity:changed<br/>+ connectivity:reconnected"]
-    Emit --> Frontend["Frontend Store"]
+    Emit --> Frontend["Frontend Store → banner"]
 ```
 While **online**, there is no background polling — real requests keep the state fresh. While **offline**, the fast 5s probe runs so an idle app still detects the server returning even when no user traffic is flowing.
 **Features:**
- **Adaptive Polling**: 30s when online, 5s when offline (for quick reconnection detection)
+- **Traffic-driven**: Reachability follows the requests the user actually makes.
- **Event Emission**: Emits `connectivity:changed` and `connectivity:reconnected` events
+- **Time-window debounce**: Offline declared only after `OFFLINE_CONFIRM_WINDOW` (5s) of sustained network failure; recovery is instant.
- **Manual Marking**: Can mark reachable/unreachable based on API call results
+- **Offline-only probe**: 5s `/System/Info/Public` probe runs only while offline.
- **Thread-Safe**: Uses Arc<RwLock<>> for shared state
+- **Event Emission**: Emits `connectivity:changed` and `connectivity:reconnected` events.
 - **Thread-Safe**: Uses `Arc<RwLock<>>` for shared state.
 **Tauri Commands:**
 | Command | Description |
 |---------|-------------|
-| `connectivity_check_server` | Manual reachability check |
+| `connectivity_check_server` | Manual reachability check (also used by the frontend's advisory `navigator.onLine` hint) |
 | `connectivity_set_server_url` | Update monitored server URL |
 | `connectivity_get_status` | Get current connectivity status |
-| `connectivity_start_monitoring` | Start background monitoring |
+| `connectivity_start_monitoring` | Start the offline recovery probe |
-| `connectivity_stop_monitoring` | Stop monitoring |
+| `connectivity_stop_monitoring` | Stop the probe |
-| `connectivity_mark_reachable` | Mark server as reachable (after successful API call) |
+| `connectivity_mark_reachable` | Mark reachable — driven by `OnlineRepository` on every server success |
-| `connectivity_mark_unreachable` | Mark server as unreachable (after failed API call) |
+| `connectivity_mark_unreachable` | Mark unreachable — driven by `OnlineRepository` on `RepoError::Network` (subject to debounce) |
 **Frontend Integration:**
 ```typescript
-// TypeScript store listens to Rust events
+// The store is a pure reflection of backend events — it no longer decides
 // reachability itself. navigator.onLine is advisory: it triggers an immediate
 // recheck rather than forcing the offline state.
 listen<{ isReachable: boolean }>("connectivity:changed", (event) => {
  updateConnectivityState(event.payload.isReachable);
 });
@@ -81,12 +114,14 @@ listen<{ isReachable: boolean }>("connectivity:changed", (event) => {
 The connectivity system provides resilience through multiple layers:
 1. **HTTP Client Layer**: Automatic retry with exponential backoff
-2. **Connectivity Monitoring**: Background reachability checks
+2. **Connectivity Monitoring**: Reachability derived from real repository traffic, with an offline-only recovery probe
-3. **Frontend Integration**: Offline mode detection and UI updates
+3. **Frontend Integration**: Offline mode detection and UI updates (a pure reflection of backend events)
 4. **Sync Queue**: Offline mutations queued for later (see [06-downloads-and-offline.md](06-downloads-and-offline.md))
 **Design Principles:**
- **Fail Fast**: Don't retry 4xx errors (client errors, authentication)
+- **Single source of truth**: Reachability follows the outcome of real requests, classified via `RepoError`; the frontend store and the probe never compete to decide it.
- **Fail Slow**: Retry network and 5xx errors with increasing delays
+- **Fail Fast**: Don't retry 4xx errors (client errors, authentication).
- **Adaptive Polling**: Reduce polling frequency when online, increase when offline
+- **Fail Slow**: Retry network and 5xx errors with increasing delays.
- **Event-Driven**: Frontend reacts to connectivity changes via events
+- **Debounced offline, instant online**: Declare offline only after a sustained failure window; recover on the first success.
 - **Probe only when needed**: Background polling runs only while offline, as a recovery detector.
 - **Event-Driven**: Frontend reacts to connectivity changes via events.
@@ -15,6 +15,7 @@ JellyTau uses a client-server architecture: business logic lives in a comprehens
 - **Events + Polling hybrid**: Rust emits events the frontend listens to, and the UI also polls status on short intervals in a few hot spots (e.g. queue status in `library/+layout.svelte`, playback progress in `VideoPlayer.svelte`).
 - **Handle-Based Resources**: UUID handles for stateful Rust objects.
 - **Cache-First**: Parallel queries with intelligent fallback.
 - **Single source of truth for reachability**: Server reachability is derived from the outcome of *real repository traffic*, not a side-channel poller. The `OnlineRepository` reports each server result to the `ConnectivityMonitor` (classified via `RepoError`), which applies a time-window debounce before declaring the server offline and recovers instantly on the first success. The standalone `/System/Info/Public` probe runs *only while offline*, as a recovery detector for idle sessions.
 - **Poison-tolerant locking**: Shared `std::sync` state is accessed via the `MutexSafe`/`RwLockSafe` helpers in `utils/lock.rs`, which recover a poisoned lock instead of cascading a panic across the player.
 - **Graceful backend init**: If a native player backend (MPV/ExoPlayer) fails to initialize, the app falls back to a no-op backend and emits a `backend-init-failed` event rather than crashing.
@@ -79,26 +80,29 @@ flowchart TB
        Core --> Storage
        Repository --> HttpClient
        Repository --> DatabaseService
        Repository -->|"reports server outcome<br/>(success / RepoError)"| ConnectivityMonitor
    end
 ```
 > The `Repository --> ConnectivityMonitor` edge is the source of truth for the offline/online banner: every server request the user actually makes updates reachability. The monitor's own polling is now an offline-only recovery probe (see [07-connectivity.md](07-connectivity.md)).
 ---
 ## Detailed Documentation
-Each major subsystem is documented in its own file under [docs/architecture/](docs/architecture/):
+Each major subsystem is documented in its own file in this directory:
 | Document | Contents |
 |----------|----------|
-| [01 - Rust Backend](docs/architecture/01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
+| [01 - Rust Backend](01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
-| [02 - Svelte Frontend](docs/architecture/02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
+| [02 - Svelte Frontend](02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
-| [03 - Data Flow](docs/architecture/03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
+| [03 - Data Flow](03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
-| [04 - Type Sync & Threading](docs/architecture/04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
+| [04 - Type Sync & Threading](04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
-| [05 - Platform Backends](docs/architecture/05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
+| [05 - Platform Backends](05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
-| [06 - Downloads & Offline](docs/architecture/06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
+| [06 - Downloads & Offline](06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
-| [07 - Connectivity](docs/architecture/07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
+| [07 - Connectivity](07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
-| [08 - Database Design](docs/architecture/08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
+| [08 - Database Design](08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
-| [09 - Security](docs/architecture/09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
+| [09 - Security](09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
 ---
@@ -187,7 +191,7 @@ src/lib/
 **What moved to Rust (~3,500 lines of business logic):**
 1. **HTTP Client** (338 lines) - Retry logic with exponential backoff
-2. **Connectivity Monitor** (301 lines) - Adaptive polling, event emission
+2. **Connectivity Monitor** (301 lines) - Reachability derived from real repository traffic, time-window debounce, offline-only recovery probe, event emission
 3. **Repository Pattern** (1061 lines) - Cache-first hybrid with parallel racing
 4. **Database Service** - Async wrapper preventing UI freezing
 5. **Playback Mode** (303 lines) - Local/remote transfer coordination
@@ -0,0 +1,454 @@
 # Requirements Specification
 This document captures JellyTau's user requirements, software requirements,
 traceability matrix, test traceability, and known technical debt.
 For a narrative overview of the system design, see
 [docs/architecture/](architecture/). For development workflows, see the
 [README](../README.md) and [scripts/README.md](../scripts/README.md).
 ## 1. User Requirements
 | ID | Requirement | Priority | Status |
 |----|-------------|----------|--------|
 | UR-001 | Run the app on multiple platforms (Linux, Android) | High | In Progress |
 | UR-002 | Access media when online or offline | High | Done |
 | UR-003 | Play videos | High | Done |
 | UR-004 | Play audio uninterrupted | High | Done |
 | UR-005 | Control media playback (pause, play, skip, scrub) | High | Done |
 | UR-006 | Control media when device is on lock screen or via BLE headsets | Medium | Done |
 | UR-007 | Navigate media in library | High | Done |
 | UR-008 | Search media across libraries | High | Done |
 | UR-009 | Connect to Jellyfin to access media | High | Done |
 | UR-010 | Control playback of Jellyfin remote sessions | Low | Done |
 | UR-011 | Download media on demand | Medium | Done |
 | UR-012 | Login info shall be stored securely and persistently | High | Done |
 | UR-013 | View and manage downloaded media | Medium | Done |
 | UR-014 | Make and edit playlists of music that sync back to Jellyfin | Medium | Done |
 | UR-015 | View and manage current audio queue (add, reorder tracks) | Medium | Done |
 | UR-016 | Change system settings while playing (brightness, volume) | Low | Planned |
 | UR-017 | Like or unlike audio, albums, movies, etc. | Medium | Done |
 | UR-018 | Choose to download series, albums, songs, artist discography | Medium | Done |
 | UR-019 | Resume playback from where you left off (movies, shows, albums) | High | Done |
 | UR-020 | Select subtitles for video content | High | Done |
 | UR-021 | Select audio track for video content | High | Done |
 | UR-022 | Control streaming quality and transcoding settings | Medium | Planned |
 | UR-023 | View "Next Up" / Continue Watching on home screen; auto-play next episode with countdown popup and configurable episode limit | Medium | Done |
 | UR-024 | View recently added content on server | Medium | Done |
 | UR-025 | Sync watch history and progress back to Jellyfin | High | Done |
 | UR-026 | Sleep timer for audio and video playback (roller UI, time/track/episode modes) | Low | Done |
 | UR-027 | Audio equalizer for sound customization | Low | Planned |
 | UR-028 | Navigate to artist/album by tapping names in now playing view | High | Done |
 | UR-029 | Toggle between grid and list view in library | Medium | Done |
 | UR-030 | Quick genre browsing and filtering | Medium | Done |
 | UR-031 | Crossfade between audio tracks | Low | Done (Linux only) |
 | UR-032 | Gapless playback for seamless album listening | Medium | Done (Linux only) |
 | UR-033 | Volume normalization to prevent volume jumps between tracks | Low | Done (Linux only) |
 | UR-034 | Rich home screen with hero banners, carousels, and personalized sections | High | Done |
 | UR-035 | View cast/crew (actors, directors) on movie/show detail pages | High | Done |
 | UR-036 | Navigate to actor/person page showing their filmography | Medium | Done |
 | UR-037 | Visually appealing video library with poster grids and metadata | High | Done |
 | UR-038 | Movie/show detail page with backdrop, ratings, and rich metadata | High | Done |
 | UR-039 | Navigate between main sections via bottom navigation bar | High | Done |
 ---
 ## 2. Software Requirements
 ### 2.1 Integration Requirements
 External system integrations and platform-specific implementations.
 | ID | Requirement | Category | Traces To | Status |
 |----|-------------|----------|-----------|--------|
 | IR-001 | Build system supporting multiple targets (Linux, Android) | Build | UR-001 | Done |
 | IR-002 | Build scripts for Android and Linux | Build | UR-001 | Done |
 | IR-003 | Integration of libmpv for Linux playback | Playback | UR-003, UR-004 | Done |
 | IR-004 | Integration of ExoPlayer for Android playback | Playback | UR-003, UR-004 | In Progress (basic playback works, audio settings missing) |
 | IR-005 | MPRIS D-Bus integration for Linux lockscreen/media controls | Platform | UR-006 | Planned |
 | IR-006 | Android MediaSession integration for lockscreen controls | Platform | UR-006 | Done |
 | IR-007 | Bluetooth AVRCP integration via system media session | Platform | UR-006 | Planned |
 | IR-008 | Android audio focus handling (pause on call) | Platform | UR-004, UR-006 | Done |
 | IR-009 | Jellyfin API client for authentication | API | UR-009, UR-012 | Done |
 | IR-010 | Jellyfin API client for library browsing | API | UR-007, UR-008 | Done |
 | IR-011 | Jellyfin API client for playback streaming | API | UR-003, UR-004 | Done |
 | IR-012 | Jellyfin Sessions API for remote playback control | API | UR-010 | Done |
 | IR-021 | Android MediaRouter integration for remote volume in system panel | Platform | UR-010, UR-016 | Planned |
 | IR-013 | SQLite integration for local database | Storage | UR-002, UR-011 | Done |
 | IR-014 | Secure credential storage (keyring/keychain) | Security | UR-012 | Done |
 | IR-015 | Jellyfin API client for playback progress reporting | API | UR-019, UR-025 | Done |
 | IR-016 | Jellyfin API client for subtitle/audio track info | API | UR-020, UR-021 | Done |
 | IR-017 | Jellyfin API client for transcoding parameters | API | UR-022 | Planned |
 | IR-018 | libmpv subtitle rendering and selection | Playback | UR-020 | Planned |
 | IR-019 | libmpv audio track selection | Playback | UR-021 | Planned |
 | IR-020 | libmpv/ExoPlayer equalizer integration | Playback | UR-027 | Planned |
 | IR-022 | Jellyfin API client for person/cast data | API | UR-035, UR-036 | Done |
 | IR-023 | Database schema for person/cast caching | Storage | UR-035, UR-036 | Done |
 | IR-024 | Jellyfin API client for home screen data (featured, continue watching) | API | UR-034 | Done |
 ### 2.2 Jellyfin API Requirements
 API endpoints and data contracts required for Jellyfin integration.
 | ID | Requirement | Endpoint Category | Traces To | Status |
 |----|-------------|-------------------|-----------|--------|
 | JA-001 | Server connection and discovery | System | UR-009 | Done |
 | JA-002 | User authentication (username/password) | Users | UR-009, UR-012 | Done |
 | JA-003 | Get user library views | UserViews | UR-007 | Done |
 | JA-004 | Get library items (paginated) | Items | UR-007 | Done |
 | JA-005 | Get item details and metadata | Items | UR-007 | Done |
 | JA-006 | Search across libraries | Items | UR-008 | Done |
 | JA-007 | Get playback info and stream URL | MediaInfo | UR-003, UR-004 | Done |
 | JA-008 | Get available subtitles for item | MediaInfo | UR-020 | Done |
 | JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Done |
 | JA-010 | Report playback start | Sessions | UR-025 | Done |
 | JA-011 | Report playback progress (periodic) | Sessions | UR-025 | Done |
 | JA-012 | Report playback stopped | Sessions | UR-025 | Done |
 | JA-013 | Get resume position for item | UserData | UR-019 | Done |
 | JA-014 | Get "Next Up" items | Shows | UR-023 | Done |
 | JA-015 | Get "Continue Watching" items | Items | UR-023 | Done |
 | JA-016 | Get recently added items | Items | UR-024 | Done |
 | JA-017 | Mark item as favorite | UserData | UR-017 | Done |
 | JA-018 | Remove item from favorites | UserData | UR-017 | Done |
 | JA-019 | Get/create/update playlists | Playlists | UR-014 | Done |
 | JA-020 | Add/remove items from playlist | Playlists | UR-014 | Done |
 | JA-021 | Get active sessions list | Sessions | UR-010 | Done |
 | JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Done |
 | JA-023 | Send seek command to remote session | Sessions | UR-010 | Done |
 | JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Done |
 | JA-025 | Play specific item on remote session | Sessions | UR-010 | Done |
 | JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Done |
 | JA-027 | Get transcoding options | MediaInfo | UR-022 | Planned |
 | JA-028 | Get image/artwork URLs | Images | UR-007 | Done |
 | JA-029 | Get cast/crew for item (actors, directors) | Items | UR-035 | Done |
 | JA-030 | Get person details and filmography | Persons | UR-036 | Done |
 | JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
 ### 2.3 Development Requirements
 Internal architecture, components, and application logic.
 | ID | Requirement | Category | Traces To | Status |
 |----|-------------|----------|-----------|--------|
 | DR-001 | Player state machine (idle, loading, playing, paused, seeking, error) | Player | UR-005 | Done |
 | DR-002 | MediaItem struct tracking source, location, duration, metadata | Player | UR-003, UR-004 | Done |
 | DR-003 | Source-agnostic media abstraction (Remote, Local, DirectUrl) | Player | UR-002, UR-011 | Done |
 | DR-004 | PlayerBackend trait for platform-agnostic playback | Player | UR-003, UR-004 | Done |
 | DR-005 | Queue manager with shuffle, repeat, history | Player | UR-005, UR-015 | Done |
 | DR-006 | Audio pre-caching for seamless track transitions | Player | UR-004 | Planned |
 | DR-007 | Library browsing screens (grid view, search, filters) | UI | UR-007, UR-008 | Done |
 | DR-008 | Album/Series detail view with track listing | UI | UR-007 | Done |
 | DR-009 | Audio player UI (mini player, full screen) | UI | UR-005 | Done |
 | DR-010 | Video player UI (fullscreen, controls overlay) | UI | UR-003, UR-005 | Done |
 | DR-011 | Search bar with cross-library search | UI | UR-008 | Done |
 | DR-012 | Local database for media metadata cache | Storage | UR-002 | Done |
 | DR-013 | Repository pattern for online/offline data access | Storage | UR-002 | Done |
 | DR-014 | Offline mutation queue for sync-back operations | Storage | UR-002, UR-014, UR-017 | Done |
 | DR-015 | Download manager with queue and progress tracking | Storage | UR-011, UR-018 | Done |
 | DR-016 | Thumbnail caching and sync with server | Storage | UR-007 | Done |
 | DR-017 | "Manage Downloads" screen for local media management | UI | UR-013 | Done |
 | DR-018 | Download buttons on library/album/player screens | UI | UR-011, UR-018 | Done |
 | DR-019 | Playlist creation and editing UI | UI | UR-014 | Done |
 | DR-020 | Queue management UI (add, remove, reorder) | UI | UR-015 | Done |
 | DR-021 | Like/favorite functionality on media items | UI | UR-017 | Done |
 | DR-022 | Resume position tracking and restoration on play | Player | UR-019 | Done |
 | DR-023 | Subtitle selection UI in video player | UI | UR-020 | Done |
 | DR-024 | Audio track selection UI in video player | UI | UR-021 | Done |
 | DR-025 | Quality/transcoding settings UI | UI | UR-022 | Planned |
 | DR-026 | "Continue Watching" / "Next Up" home section | UI | UR-023 | Done |
 | DR-027 | "Recently Added" home section | UI | UR-024 | Done |
 | DR-028 | Playback progress sync service (periodic reporting) | Player | UR-025 | Done |
 | DR-029 | Sleep timer with roller UI, time/track/episode modes, and auto-stop (audio + video players) | Player | UR-026 | Done |
 | DR-049 | Auto-play episode limit (configurable max episodes per session) | Player | UR-023 | Done |
 | DR-050 | Reusable scroll picker (roller) component | UI | UR-026 | Done |
 | DR-030 | Equalizer UI with presets and custom bands | UI | UR-027 | Planned |
 | DR-031 | Clickable artist/album links in now playing view | UI | UR-028 | Done |
 | DR-032 | List view option for library browsing (albums, artists) | UI | UR-029 | Done |
 | DR-033 | Genre browsing screen with quick filters | UI | UR-030 | Done |
 | DR-034 | Crossfade engine with configurable duration (0-12s) | Player | UR-031 | Done (Linux only) |
 | DR-035 | Gapless playback between sequential tracks | Player | UR-032 | Done (Linux only) |
 | DR-036 | Volume normalization with preset levels (Loud/Normal/Quiet) | Player | UR-033 | Done (Linux only) |
 | DR-037 | Remote session browser and control UI | UI | UR-010 | Done |
 | DR-038 | Home screen with hero banner carousel (featured/continue watching) | UI | UR-034 | Done |
 | DR-039 | Home screen horizontal carousels (recently added, recommendations) | UI | UR-034, UR-024 | Done |
 | DR-040 | Cast/crew section on movie/show detail pages | UI | UR-035 | Done |
 | DR-041 | Person/actor detail page with filmography grid | UI | UR-036 | Done |
 | DR-042 | Video library grid with poster cards, year, and rating badges | UI | UR-037 | Done |
 | DR-043 | Movie/show detail page with backdrop hero, synopsis, and metadata | UI | UR-038 | Done |
 | DR-044 | Horizontal scrolling actor/cast row with profile images | UI | UR-035 | Done |
 | DR-045 | Bottom navigation bar with Home, Library, Search buttons | UI | UR-039 | Done |
 | DR-046 | Dedicated search page with input and results | UI | UR-039 | Done |
 | DR-047 | Next episode auto-play popup with configurable countdown and episode limit | Player | UR-023 | Done |
 | DR-048 | Video settings (auto-play toggle, countdown duration, episode limit) | Settings | UR-023, UR-026 | Done |
 ---
 ## 3. Traceability Matrix
 ### User Requirements to Software Requirements
 | User Req | Integration Requirements | Development Requirements |
 |----------|-------------------------|-------------------------|
 | 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-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 |
 | UR-008 | IR-010 | DR-007, DR-011 |
 | UR-009 | IR-009, IR-010, IR-011 | - |
 | UR-010 | IR-012, IR-021 | DR-037 |
 | UR-011 | IR-013 | DR-003, DR-015, DR-018 |
 | UR-012 | IR-009, IR-014 | - |
 | UR-013 | IR-013 | DR-017 |
 | UR-014 | IR-010 | DR-014, DR-019 |
 | UR-015 | - | DR-005, DR-020 |
 | UR-016 | - | - |
 | UR-017 | - | DR-014, DR-021 |
 | UR-018 | IR-013 | DR-015, DR-018 |
 | UR-019 | IR-015 | DR-022 |
 | UR-020 | IR-016, IR-018 | DR-023 |
 | UR-021 | IR-016, IR-019 | DR-024 |
 | 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-026 | - | DR-029, DR-048, DR-050 |
 | UR-027 | IR-020 | DR-030 |
 | UR-028 | - | DR-031 |
 | UR-029 | - | DR-032 |
 | UR-030 | IR-010 | DR-033 |
 | UR-031 | - | DR-034 |
 | UR-032 | - | DR-035 |
 | UR-033 | - | DR-036 |
 | UR-034 | IR-010, IR-024 | DR-038, DR-039 |
 | UR-035 | IR-022, IR-023 | DR-040, DR-044 |
 | UR-036 | IR-022, IR-023 | DR-041 |
 | UR-037 | IR-010 | DR-042 |
 | UR-038 | IR-010 | DR-043 |
 | UR-039 | - | DR-045, DR-046 |
 ---
 ## 4. Test Traceability
 ### Unit Tests to Software Requirements
 | Test ID | Test Description | Traces To | Status |
 |---------|-----------------|-----------|--------|
 | UT-001 | Player state transitions | DR-001 | Pending |
 | UT-002 | MediaItem source URL resolution | DR-002, DR-003 | Pending |
 | UT-003 | Queue next/previous navigation | DR-005 | Pending |
 | UT-004 | Queue shuffle order generation | DR-005 | Pending |
 | UT-005 | Queue repeat mode behavior | DR-005 | Pending |
 | UT-006 | Jellyfin authentication flow | IR-009 | Pending |
 | UT-007 | Jellyfin library items parsing | IR-010 | Pending |
 | UT-008 | Repository pattern online/offline switching | DR-013 | Pending |
 | UT-009 | Offline mutation queue persistence | DR-014 | Pending |
 | UT-010 | Download queue management | DR-015 | Done |
 | UT-011 | Resume position storage and retrieval | DR-022 | Pending |
 | UT-012 | Sleep timer countdown logic | DR-029 | Pending |
 | UT-013 | Playback progress reporting throttling | DR-028 | Pending |
 | UT-014 | Database open and in-memory mode | IR-013, DR-012 | Done |
 | UT-015 | Database migrations run successfully | IR-013, DR-012 | Done |
 | UT-016 | All database tables created | IR-013, DR-012 | Done |
 | UT-017 | FTS5 search table created | IR-013, DR-012 | Done |
 | UT-018 | Server CRUD operations | IR-013, DR-012 | Done |
 | UT-019 | User CRUD operations | IR-013, DR-012 | Done |
 | UT-020 | Cascade delete server removes users | IR-013, DR-012 | Done |
 | UT-021 | Item insert and FTS search | IR-013, DR-012 | Done |
 | UT-022 | User data playback position storage | IR-013, DR-012, DR-022 | Done |
 | UT-023 | Sync queue operations | IR-013, DR-014 | Done |
 | UT-024 | Downloads table operations | IR-013, DR-015 | Done |
 | UT-025 | Migrations are idempotent | IR-013, DR-012 | Done |
 | UT-026 | NullBackend volume default value | DR-004 | Done |
 | UT-027 | NullBackend set volume | DR-004 | Done |
 | UT-028 | NullBackend volume clamping (high/low) | DR-004 | Done |
 | UT-029 | NullBackend volume boundary values | DR-004 | Done |
 | UT-030 | PlayerController volume default | DR-004, DR-009 | Done |
 | UT-031 | PlayerController set volume | DR-004, DR-009 | Done |
 | UT-032 | PlayerController muted default | DR-004, DR-009 | Done |
 | UT-033 | PlayerController volume delegates to backend | DR-004, DR-009 | Done |
 | UT-034 | Download event serialization roundtrip | DR-015 | Done |
 | UT-035 | Download event completed serialization | DR-015 | Done |
 | UT-036 | Download event failed serialization | DR-015 | Done |
 | UT-037 | Download worker exponential backoff | DR-015 | Done |
 | UT-038 | Download worker error retryable check | DR-015 | Done |
 | UT-039 | Download manager creation | DR-015 | Done |
 | UT-040 | Download manager set max concurrent | DR-015 | Done |
 | UT-041 | Download info serialization | DR-015 | Done |
 | UT-042 | Download command filename sanitization | DR-015, DR-018 | Done |
 | UT-043 | Download command filename extension preservation | DR-015, DR-018 | Done |
 | UT-044 | Offline item serialization | DR-017 | Done |
 | UT-045 | Smart cache default config | DR-015 | Done |
 | UT-046 | Smart cache album affinity tracking | DR-015 | Done |
 | UT-047 | Smart cache queue precache config | DR-015 | Done |
 | UT-048 | Smart cache storage limit check | DR-015 | Done |
 | UT-049 | Playlist create (offline) | DR-019, JA-019 | Done |
 | UT-050 | Playlist delete (offline) | DR-019, JA-019 | Done |
 | UT-051 | Playlist rename (offline) | DR-019, JA-019 | Done |
 | UT-052 | Playlist get items (offline) | DR-019, JA-019 | Done |
 | UT-053 | Playlist add items (offline) | DR-019, JA-020 | Done |
 | UT-054 | Playlist remove items (offline) | DR-019, JA-020 | Done |
 | UT-055 | Playlist reorder items (offline) | DR-019, JA-020 | Done |
 | UT-056 | Playlist entry serialization | DR-019, JA-019 | Done |
 | UT-057 | Playlist Tauri command param naming (camelCase) | DR-019, JA-019, JA-020 | Done |
 | UT-058 | Playlist repository client methods | DR-019, JA-019, JA-020 | Done |
 ### Integration Tests
 | Test ID | Test Description | Traces To | Status |
 |---------|-----------------|-----------|--------|
 | IT-001 | End-to-end authentication with Jellyfin server | IR-009, UR-009 | Pending |
 | IT-002 | Library browsing and item loading | IR-010, UR-007 | Pending |
 | IT-003 | Audio playback via libmpv | IR-003, UR-004 | Pending |
 | IT-004 | Video playback via libmpv | IR-003, UR-003 | Pending |
 | IT-005 | MPRIS lockscreen controls on Linux | IR-005, UR-006 | Pending |
 | IT-006 | Offline mode with local database | IR-013, UR-002 | Pending |
 | IT-007 | Media download and local playback | DR-015, UR-011 | Pending |
 | IT-008 | Subtitle track selection via libmpv | IR-018, UR-020 | Pending |
 | IT-009 | Audio track selection via libmpv | IR-019, UR-021 | Pending |
 | IT-010 | Playback progress sync to Jellyfin | IR-015, UR-025 | Pending |
 | IT-011 | Resume playback from server position | IR-015, UR-019 | Pending |
 | IT-012 | Equalizer bands via libmpv | IR-020, UR-027 | Pending |
 ---
 ## 5. Technical Debt
 ### Linux Keyring Integration Workaround
 **Issue**: The `keyring-rs` crate (v3.x) has issues with retrieving credentials from the Linux Secret Service API, despite successfully saving them.
 **Symptoms**:
 - Credentials are saved to the system keyring successfully (verified with `secret-tool search`)
 - Retrieval via the `keyring-rs` library fails with `NoEntry` error
 - Session restoration fails on app restart even though credentials exist
 **Root Cause**:
 The `keyring-rs` library's Linux backend doesn't correctly retrieve entries from the Secret Service that it previously stored. This appears to be a bug in how the library interfaces with the Secret Service D-Bus API.
 **Current Workaround**:
 We bypass the `keyring-rs` library on Linux and use direct system calls to `secret-tool`:
 - **Save**: `secret-tool store --label <label> service <service> username <username>`
 - **Retrieve**: `secret-tool lookup service <service> username <username>`
 - **Delete**: `secret-tool clear service <service> username <username>`
 **Implementation**:
 See [src-tauri/src/credentials.rs](../src-tauri/src/credentials.rs) for the
 Linux-specific `secret-tool` save/get/delete paths.
 **Future Fix**:
 - Monitor `keyring-rs` for bug fixes in future versions
 - Consider alternative secure storage libraries
 - Test if newer versions of `keyring-rs` (v4.x+) resolve the issue
 - Once fixed, remove the Linux-specific workaround and use the cross-platform `keyring-rs` API
 **Impact**:
 - Low - The workaround is functionally equivalent to proper keyring integration
 - Credentials are stored securely in the system keyring
 - Session restoration works correctly
 - Only affects Linux; macOS and Windows use the standard `keyring-rs` implementation
 **Dependencies**:
 - Requires `secret-tool` to be installed on Linux systems (part of `libsecret-tools` package)
 - Already available on most Linux distributions by default
 ---
 ### Platform Playback Backend Parity (Linux vs Android)
 **Issue**: The Linux (MPV) and Android (ExoPlayer) playback backends have diverged in feature implementation and architecture patterns.
 **Symptoms**:
 - Audio settings (crossfade, gapless playback, volume normalization) work on Linux but not on Android
 - Position update frequency differs between platforms (Linux: 250ms polling, Android: on-demand callbacks)
 - Thread safety models differ (Linux: `Arc<Mutex<>>`, Android: global `OnceLock` statics)
 **Root Cause**:
 The `PlayerBackend` trait defines optional audio settings methods with default empty implementations. The Linux `MpvBackend` overrides these with full MPV property commands, but `ExoPlayerBackend` uses the defaults.
 **Affected Files**:
 - [src-tauri/src/player/backend.rs](../src-tauri/src/player/backend.rs) - Trait with default empty implementations
 - [src-tauri/src/player/mpv_backend.rs](../src-tauri/src/player/mpv_backend.rs) - Full audio settings support
 - [src-tauri/src/player/android/mod.rs](../src-tauri/src/player/android/mod.rs) - Missing audio settings implementation
 **Feature Parity Matrix**:
 | Feature | Linux (MPV) | Android (ExoPlayer) | Status |
 |---------|-------------|---------------------|--------|
 | Basic playback | ✅ | ✅ | Parity |
 | Volume control | ✅ | ✅ | Parity |
 | Seek | ✅ | ✅ | Parity |
 | Crossfade | ✅ | ❌ | Gap |
 | Gapless playback | ✅ | ❌ | Gap |
 | Volume normalization | ✅ | ❌ | Gap |
 | Position updates | 250ms | On-demand | Inconsistent |
 **Future Fix**:
 1. Implement `set_audio_settings()` in `ExoPlayerBackend`
 2. Add Kotlin-side ExoPlayer configuration for crossfade (using `ConcatenatingMediaSource` or `DefaultMediaSourceFactory`)
 3. Implement gapless via ExoPlayer's built-in gapless support
 4. Add volume normalization via ExoPlayer's `LoudnessEnhancer` or audio processor
 5. Standardize position update frequency across platforms
 **Impact**:
 - Medium - Android users lack audio enhancement features advertised in requirements
 - User experience differs between platforms
 - UR-031 (Crossfade), UR-032 (Gapless), UR-033 (Normalization) only work on Linux
 **Traces To**: IR-004, UR-031, UR-032, UR-033, DR-034, DR-035, DR-036
 ---
 ### Frontend Playback Code Duplication
 **Issue**: Playback control handlers and state derivations are duplicated between `AudioPlayer.svelte` and `MiniPlayer.svelte`.
 **Symptoms**:
 - Identical try-catch wrapped handler functions in both components (~44 lines duplicated)
 - Same `$derived` state merging logic for local/remote playback in both components
 - Position conversion (ticks ↔ seconds) scattered across multiple files
 **Affected Files**:
 - [src/lib/components/player/AudioPlayer.svelte](../src/lib/components/player/AudioPlayer.svelte) - Duplicate handlers
 - [src/lib/components/player/MiniPlayer.svelte](../src/lib/components/player/MiniPlayer.svelte) - Duplicate handlers
 - [src/lib/services/playbackControl.ts](../src/lib/services/playbackControl.ts) - Position conversion
 - [src/lib/stores/playbackMode.ts](../src/lib/stores/playbackMode.ts) - Position conversion
 - [src/lib/services/playbackReporting.ts](../src/lib/services/playbackReporting.ts) - Position conversion
 **Duplicated Code**:
 ```typescript
 // These handlers are identical in both AudioPlayer and MiniPlayer:
 handlePlayPause(), handleNext(), handlePrevious(),
 handleToggleShuffle(), handleCycleRepeat(), handleVolumeChange()
 // These derived states use identical logic:
 displayMedia, displayIsPlaying, displayPosition, displayDuration
 ```
 **Future Fix**:
 1. Create `src/lib/utils/playbackUnits.ts`:
   ```typescript
   export const TICKS_PER_SECOND = 10_000_000;
   export const secondsToTicks = (s: number) => Math.floor(s * TICKS_PER_SECOND);
   export const ticksToSeconds = (t: number) => t / TICKS_PER_SECOND;
   ```
 2. Create `src/lib/composables/useMergedPlaybackState.svelte.ts`:
   - Export `displayMedia`, `displayIsPlaying`, `displayPosition`, `displayDuration`
   - Single source of truth for merged local/remote state
 3. Simplify handler wrappers using a utility:
   ```typescript
   export const withErrorHandler = (fn: () => Promise<void>, context: string) =>
     async () => { try { await fn(); } catch (e) { console.error(`${context}:`, e); } };
   ```
 **Impact**:
 - Low - Code works correctly but violates DRY principle
 - Maintenance burden when logic needs to change
 - Risk of handlers diverging over time
 **Traces To**: DR-009
@@ -3,6 +3,7 @@
  "version": "0.1.0",
  "description": "",
  "type": "module",
  "packageManager": "bun@1.3.5",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
@@ -18,7 +19,7 @@
    "test:rust": "./scripts/test-rust.sh",
    "android:build": "./scripts/build-android.sh",
    "android:build:release": "./scripts/build-android.sh release",
-    "android:build:clean": "rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target && npm install && npm run build",
+    "android:build:clean": "rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target && bun install && bun run build",
    "android:deploy": "./scripts/deploy-android.sh",
    "android:dev": "./scripts/build-and-deploy.sh",
    "android:check": "./scripts/check-android.sh",
@@ -94,7 +94,7 @@ The traceability system is integrated with Gitea Actions CI/CD:
 For details, see:
 - [Traceability CI Guide](../docs/traceability-ci.md) - Full CI/CD documentation
- [TRACES Quick Reference](../traces-quick-ref.md) - Quick guide for adding TRACES
+- [TRACES Quick Reference](../docs/traces-quick-ref.md) - Quick guide for adding TRACES
 ## Utility Scripts
@@ -0,0 +1,86 @@
 package com.dtourolle.jellytau
 import android.app.Activity
 import android.view.SurfaceView
 import android.view.ViewGroup
 import android.widget.FrameLayout
 import com.dtourolle.jellytau.player.JellyTauPlayer
 /**
 * Manages the video SurfaceView overlay in the Activity's view hierarchy.
 *
 * This class handles attaching and detaching the native ExoPlayer SurfaceView
 * so that it renders video content behind the WebView.
 */
 object VideoOverlayManager {
    private var attachedSurfaceView: SurfaceView? = null
    /**
     * Attach the video SurfaceView to the Activity's content view.
     *
     * The SurfaceView is added at index 0 (bottom of z-order) so it renders
     * behind the Tauri WebView, allowing Svelte controls to overlay on top.
     *
     * @param activity The Activity to attach the surface to
     */
    fun attachVideoSurface(activity: Activity) {
        try {
            // Get the SurfaceView from JellyTauPlayer
            val player = JellyTauPlayer.getInstance()
            val surfaceView = player.getSurfaceView()
            if (surfaceView == null) {
                android.util.Log.w("VideoOverlayManager", "No SurfaceView available to attach")
                return
            }
            // Get the root content view
            val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
            // Remove from parent if already attached elsewhere
            (surfaceView.parent as? ViewGroup)?.removeView(surfaceView)
            // Configure layout params to fill the screen
            val layoutParams = FrameLayout.LayoutParams(
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            // Add to content view at index 0 (behind WebView)
            contentView.addView(surfaceView, 0, layoutParams)
            attachedSurfaceView = surfaceView
            android.util.Log.d("VideoOverlayManager", "Video surface attached to view hierarchy")
        } catch (e: Exception) {
            android.util.Log.e("VideoOverlayManager", "Failed to attach video surface", e)
        }
    }
    /**
     * Detach the video SurfaceView from the Activity's view hierarchy.
     *
     * @param activity The Activity to detach the surface from
     */
    fun detachVideoSurface(activity: Activity) {
        try {
            attachedSurfaceView?.let { surfaceView ->
                val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
                contentView.removeView(surfaceView)
                attachedSurfaceView = null
                android.util.Log.d("VideoOverlayManager", "Video surface detached from view hierarchy")
            }
        } catch (e: Exception) {
            android.util.Log.e("VideoOverlayManager", "Failed to detach video surface", e)
        }
    }
    /**
     * Check if a video surface is currently attached.
     *
     * @return true if a surface is attached, false otherwise
     */
    fun isVideoSurfaceAttached(): Boolean {
        return attachedSurfaceView != null
    }
 }
@@ -52,6 +52,7 @@ pub struct RepositoryManagerWrapper(pub RepositoryManager);
 pub async fn repository_create(
    manager: State<'_, RepositoryManagerWrapper>,
    db: State<'_, crate::commands::storage::DatabaseWrapper>,
    connectivity: State<'_, crate::commands::connectivity::ConnectivityMonitorWrapper>,
    server_url: String,
    user_id: String,
    access_token: String,
@@ -68,9 +69,18 @@ pub async fn repository_create(
    })?;
    debug!("[REPO] HTTP client created successfully");
-    // Create online repository
+    // Grab a connectivity reporter so the online repository's server outcomes
    // drive the reachability state the UI observes (source of truth for the
    // offline/online banner). See docs/architecture/07-connectivity.md.
    let connectivity_reporter = {
        let monitor = connectivity.0.lock().await;
        monitor.reporter()
    };
    // Create online repository wired to connectivity reporting
    debug!("[REPO] Creating online repository...");
-    let online = OnlineRepository::new(Arc::new(http_client), server_url, user_id.clone(), access_token);
+    let online = OnlineRepository::new(Arc::new(http_client), server_url, user_id.clone(), access_token)
        .with_connectivity(connectivity_reporter);
    debug!("[REPO] Online repository created");
    // Create offline repository with async-safe database service
@@ -1,15 +1,23 @@
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tokio::sync::RwLock;
 use tauri::{AppHandle, Emitter};
 use serde::{Serialize, Deserialize};
 use crate::jellyfin::http_client::HttpClient;
-// Adaptive polling intervals (matches TypeScript)
+// Offline recovery probe interval.
-const AUTO_CHECK_INTERVAL_MS: u64 = 30000; // 30 seconds when online
+// Reachability while online is driven by real repository traffic, so there is
-const RETRY_CHECK_INTERVAL_MS: u64 = 5000;  // 5 seconds when offline
+// no online polling. While offline we probe quickly to detect the server
 // returning even when no user traffic is flowing.
 const RETRY_CHECK_INTERVAL_MS: u64 = 5000; // 5 seconds when offline
 // Time-window debounce for declaring the server offline.
 // A single dropped request must not trip the banner: we only flip to offline
 // once network failures have persisted continuously for this window with no
 // intervening success. Recovery (online) is instant on the first success.
 const OFFLINE_CONFIRM_WINDOW: Duration = Duration::from_secs(5);
 /// Connectivity status
 #[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
@@ -45,210 +53,115 @@ struct ConnectivityChangeEvent {
    is_reachable: bool,
 }
-/// Connectivity monitor for tracking server reachability
+/// Shared reachability state and transition logic.
-pub struct ConnectivityMonitor {
+///
-    server_url: Arc<RwLock<Option<String>>>,
+/// This is the single place that mutates reachability and emits events. It is
-    http_client: Arc<HttpClient>,
+/// cheap to clone (all fields are `Arc`/`Option`) and is shared by:
 /// - the `ConnectivityMonitor` (commands, offline recovery probe), and
 /// - `OnlineRepository`, which reports the outcome of every server request.
 ///
 /// Reachability is therefore driven by real traffic; the probe only fills the
 /// gap while offline.
 #[derive(Clone)]
 pub struct ConnectivityReporter {
    status: Arc<RwLock<ConnectivityStatus>>,
-    is_monitoring: Arc<AtomicBool>,
+    /// Timestamp of the first network failure in the current failure streak.
    /// Used to debounce the transition to offline (see `OFFLINE_CONFIRM_WINDOW`).
    first_failure_at: Arc<RwLock<Option<Instant>>>,
    app_handle: Option<AppHandle>,
 }
-impl ConnectivityMonitor {
+impl ConnectivityReporter {
-    /// Create a new connectivity monitor
+    fn new(status: Arc<RwLock<ConnectivityStatus>>, app_handle: Option<AppHandle>) -> Self {
    pub fn new(http_client: HttpClient) -> Self {
        Self {
-            server_url: Arc::new(RwLock::new(None)),
+            status,
-            http_client: Arc::new(http_client),
+            first_failure_at: Arc::new(RwLock::new(None)),
-            status: Arc::new(RwLock::new(ConnectivityStatus::default())),
+            app_handle,
            is_monitoring: Arc::new(AtomicBool::new(false)),
            app_handle: None,
        }
    }
-    /// Set the Tauri app handle for event emission
+    /// Current reachability as seen by this reporter (shared with the monitor
-    pub fn set_app_handle(&mut self, app_handle: AppHandle) {
+    /// and the UI). Useful for callers that want to branch on connectivity.
-        self.app_handle = Some(app_handle);
+    pub async fn is_reachable(&self) -> bool {
        self.status.read().await.is_server_reachable
    }
-    /// Update the server URL
+    /// Test-only: force the reporter into the offline state without going through
-    pub async fn set_server_url(&self, url: String) {
+    /// the debounce, so other modules' tests can set up an "offline" precondition.
-        log::info!("[ConnectivityMonitor] Setting server URL: {}", url);
+    #[cfg(test)]
-        let mut server_url = self.server_url.write().await;
+    pub async fn mark_unreachable_for_test(&self) {
-        *server_url = Some(url.clone());
+        self.apply_probe_result(false, Some("forced offline (test)".to_string()))
-        drop(server_url);
+            .await;
        // Check new server immediately
        log::info!("[ConnectivityMonitor] Checking reachability of new server...");
        let is_reachable = self.check_reachability().await;
        log::info!("[ConnectivityMonitor] New server is {}", if is_reachable { "REACHABLE" } else { "UNREACHABLE" });
    }
-    /// Get current connectivity status
+    /// Report that a real server request succeeded (or that the server answered
-    pub async fn get_status(&self) -> ConnectivityStatus {
+    /// at all, e.g. with 401/404/5xx). The server is up — recover instantly.
-        self.status.read().await.clone()
+    pub async fn report_success(&self) {
        *self.first_failure_at.write().await = None;
        self.set_reachable(true, None).await;
    }
-    /// Check if the Jellyfin server is reachable
+    /// Report that a real server request failed with a network-level error
-    pub async fn check_reachability(&self) -> bool {
+    /// (connection refused, timeout, DNS). Subject to the time-window debounce:
-        // Mark as checking
+    /// we only flip to offline once failures have persisted for
-        {
+    /// `OFFLINE_CONFIRM_WINDOW` with no intervening success.
-            let mut status = self.status.write().await;
+    pub async fn report_network_failure(&self, error: Option<String>) {
-            status.is_checking = true;
+        // If already offline, nothing to debounce.
        if !self.status.read().await.is_server_reachable {
            return;
        }
-        let server_url = self.server_url.read().await.clone();
+        let now = Instant::now();
-
+        let streak_start = {
-        if server_url.is_none() {
+            let mut first = self.first_failure_at.write().await;
-            log::warn!("[ConnectivityMonitor] Cannot check reachability: No server URL configured");
+            *first.get_or_insert(now)
            let mut status = self.status.write().await;
            status.is_server_reachable = false;
            status.connection_error = Some("No server URL configured".to_string());
            status.is_checking = false;
            return false;
        }
        let url = server_url.unwrap();
        let ping_url = format!("{}/System/Info/Public", url);
        // Store previous reachability state
        let was_reachable = {
            let status = self.status.read().await;
            status.is_server_reachable
        };
-        log::debug!("[ConnectivityMonitor] Pinging server: {}", ping_url);
+        if now.duration_since(streak_start) >= OFFLINE_CONFIRM_WINDOW {
            log::warn!(
                "[ConnectivityMonitor] Network failures sustained for {:?}; declaring offline",
                OFFLINE_CONFIRM_WINDOW
            );
            self.set_reachable(false, error).await;
        } else {
            log::debug!(
                "[ConnectivityMonitor] Network failure within debounce window; not yet offline"
            );
        }
    }
-        // Attempt to ping the server
+    /// Apply a deliberate reachability probe result (offline recovery probe or a
-        let is_reachable = self.http_client.ping(&ping_url).await;
+    /// manual check). Unlike `report_network_failure`, a probe is an explicit
    /// reachability test, so its result is applied immediately without debounce.
    async fn apply_probe_result(&self, is_reachable: bool, error: Option<String>) {
        if is_reachable {
            *self.first_failure_at.write().await = None;
        }
        self.set_reachable(is_reachable, error).await;
    }
-        log::debug!(
+    /// Core transition: update status and emit events only on an actual change.
-            "[ConnectivityMonitor] Ping result: {} (was: {})",
+    async fn set_reachable(&self, is_reachable: bool, error: Option<String>) {
-            if is_reachable { "SUCCESS" } else { "FAILED" },
+        let was_reachable = {
            if was_reachable { "reachable" } else { "unreachable" }
        );
        // Update status
        {
            let mut status = self.status.write().await;
            let was = status.is_server_reachable;
            status.is_server_reachable = is_reachable;
            status.last_checked = Some(chrono::Utc::now().to_rfc3339());
            status.connection_error = if is_reachable {
                None
            } else {
-                Some("Server unreachable".to_string())
+                Some(error.unwrap_or_else(|| "Server unreachable".to_string()))
            };
            status.is_checking = false;
-        }
+            was
        };
        // Emit events if reachability changed
        if is_reachable != was_reachable {
            self.emit_connectivity_change(is_reachable).await;
-        }
+            if is_reachable {
-
+                self.emit_server_reconnected().await;
        // Emit reconnection event
        if is_reachable && !was_reachable {
            self.emit_server_reconnected().await;
        }
        is_reachable
    }
    /// Mark server as reachable (called after successful API call)
    pub async fn mark_reachable(&self) {
        let mut status = self.status.write().await;
        let was_reachable = status.is_server_reachable;
        status.is_server_reachable = true;
        status.last_checked = Some(chrono::Utc::now().to_rfc3339());
        status.connection_error = None;
        drop(status);
        if !was_reachable {
            log::info!("[ConnectivityMonitor] Server marked as reachable (was unreachable)");
            self.emit_connectivity_change(true).await;
            self.emit_server_reconnected().await;
        }
    }
    /// Mark server as unreachable (called after failed API call)
    pub async fn mark_unreachable(&self, error: Option<String>) {
        let mut status = self.status.write().await;
        let was_reachable = status.is_server_reachable;
        status.is_server_reachable = false;
        status.last_checked = Some(chrono::Utc::now().to_rfc3339());
        status.connection_error = error.or_else(|| Some("Server unreachable".to_string()));
        let error_msg = status.connection_error.clone().unwrap_or_default();
        drop(status);
        if was_reachable {
            log::warn!("[ConnectivityMonitor] Server marked as unreachable (was reachable): {}", error_msg);
            self.emit_connectivity_change(false).await;
        }
    }
    /// Start monitoring connectivity with adaptive polling
    pub async fn start_monitoring(&self) {
        if self.is_monitoring.swap(true, Ordering::SeqCst) {
            log::info!("[ConnectivityMonitor] Already monitoring");
            return;
        }
        log::info!("[ConnectivityMonitor] Starting connectivity monitoring");
        // Perform immediate check before starting background task
        // This ensures we get an accurate state right away instead of assuming offline
        let is_reachable = self.check_reachability().await;
        log::info!("[ConnectivityMonitor] Initial connectivity check: {}", if is_reachable { "ONLINE" } else { "OFFLINE" });
        // Clone Arc references for the background task
        let status = Arc::clone(&self.status);
        let is_monitoring = Arc::clone(&self.is_monitoring);
        let server_url = Arc::clone(&self.server_url);
        let http_client = Arc::clone(&self.http_client);
        let self_clone = Arc::new(ConnectivityMonitorHandle {
            server_url,
            http_client,
            status,
            app_handle: self.app_handle.clone(),
        });
        // Spawn background monitoring task
        tokio::spawn(async move {
            while is_monitoring.load(Ordering::SeqCst) {
                // Determine interval based on current reachability
                let interval_ms = {
                    let status = self_clone.status.read().await;
                    if status.is_server_reachable {
                        AUTO_CHECK_INTERVAL_MS
                    } else {
                        RETRY_CHECK_INTERVAL_MS
                    }
                };
                // Wait for the interval
                tokio::time::sleep(Duration::from_millis(interval_ms)).await;
                // Check if still monitoring
                if !is_monitoring.load(Ordering::SeqCst) {
                    break;
                }
                // Perform connectivity check
                let _ = self_clone.check_reachability().await;
            }
-
+        }
            log::info!("[ConnectivityMonitor] Stopped monitoring");
        });
    }
    /// Stop monitoring connectivity
    pub fn stop_monitoring(&self) {
        log::info!("[ConnectivityMonitor] Stopping connectivity monitoring");
        self.is_monitoring.store(false, Ordering::SeqCst);
    }
    /// Emit connectivity change event to frontend
@@ -275,74 +188,160 @@ impl ConnectivityMonitor {
    }
 }
-/// Handle for the background monitoring task
+/// Connectivity monitor for tracking server reachability.
-struct ConnectivityMonitorHandle {
+///
 /// Reachability is driven primarily by real repository traffic via the shared
 /// [`ConnectivityReporter`]. The monitor itself only runs an offline recovery
 /// probe (see `start_monitoring`) and serves the connectivity Tauri commands.
 pub struct ConnectivityMonitor {
    server_url: Arc<RwLock<Option<String>>>,
    http_client: Arc<HttpClient>,
-    status: Arc<RwLock<ConnectivityStatus>>,
+    reporter: ConnectivityReporter,
-    app_handle: Option<AppHandle>,
+    is_monitoring: Arc<AtomicBool>,
 }
-impl ConnectivityMonitorHandle {
+impl ConnectivityMonitor {
-    async fn check_reachability(&self) -> bool {
+    /// Create a new connectivity monitor
    pub fn new(http_client: HttpClient) -> Self {
        let status = Arc::new(RwLock::new(ConnectivityStatus::default()));
        Self {
            server_url: Arc::new(RwLock::new(None)),
            http_client: Arc::new(http_client),
            reporter: ConnectivityReporter::new(status, None),
            is_monitoring: Arc::new(AtomicBool::new(false)),
        }
    }
    /// Set the Tauri app handle for event emission.
    /// Must be called before the reporter is shared with the repository.
    pub fn set_app_handle(&mut self, app_handle: AppHandle) {
        self.reporter.app_handle = Some(app_handle);
    }
    /// Get a cheap, cloneable reporter so the repository can feed server
    /// outcomes into the same reachability state the UI observes.
    pub fn reporter(&self) -> ConnectivityReporter {
        self.reporter.clone()
    }
    /// Update the server URL
    pub async fn set_server_url(&self, url: String) {
        log::info!("[ConnectivityMonitor] Setting server URL: {}", url);
        *self.server_url.write().await = Some(url);
        // Check new server immediately
        log::info!("[ConnectivityMonitor] Checking reachability of new server...");
        let is_reachable = self.check_reachability().await;
        log::info!("[ConnectivityMonitor] New server is {}", if is_reachable { "REACHABLE" } else { "UNREACHABLE" });
    }
    /// Get current connectivity status
    pub async fn get_status(&self) -> ConnectivityStatus {
        self.reporter.status.read().await.clone()
    }
    /// Deliberately probe the server's reachability (manual check / recovery probe).
    /// The result is applied immediately (no debounce) since this is an explicit test.
    pub async fn check_reachability(&self) -> bool {
        {
            let mut status = self.reporter.status.write().await;
            status.is_checking = true;
        }
        let server_url = self.server_url.read().await.clone();
-        if server_url.is_none() {
+        let Some(url) = server_url else {
            log::warn!("[ConnectivityMonitor] Cannot check reachability: No server URL configured");
            self.reporter
                .apply_probe_result(false, Some("No server URL configured".to_string()))
                .await;
            return false;
        }
        let url = server_url.unwrap();
        let ping_url = format!("{}/System/Info/Public", url);
        // Store previous reachability state
        let was_reachable = {
            let status = self.status.read().await;
            status.is_server_reachable
        };
-        // Attempt to ping the server
+        let ping_url = format!("{}/System/Info/Public", url);
        log::debug!("[ConnectivityMonitor] Pinging server: {}", ping_url);
        let is_reachable = self.http_client.ping(&ping_url).await;
        log::debug!(
            "[ConnectivityMonitor] Ping result: {}",
            if is_reachable { "SUCCESS" } else { "FAILED" }
        );
-        // Update status
+        self.reporter.apply_probe_result(is_reachable, None).await;
        {
            let mut status = self.status.write().await;
            status.is_server_reachable = is_reachable;
            status.last_checked = Some(chrono::Utc::now().to_rfc3339());
            status.connection_error = if is_reachable {
                None
            } else {
                Some("Server unreachable".to_string())
            };
        }
        // Emit events if reachability changed
        if is_reachable != was_reachable {
            self.emit_connectivity_change(is_reachable).await;
        }
        // Emit reconnection event
        if is_reachable && !was_reachable {
            self.emit_server_reconnected().await;
        }
        is_reachable
    }
-    async fn emit_connectivity_change(&self, is_reachable: bool) {
+    /// Mark server as reachable (called after successful API call / login)
-        if let Some(app_handle) = &self.app_handle {
+    pub async fn mark_reachable(&self) {
-            let event = ConnectivityChangeEvent { is_reachable };
+        self.reporter.report_success().await;
            if let Err(e) = app_handle.emit("connectivity:changed", event) {
                log::error!("[ConnectivityMonitor] Failed to emit connectivity change event: {}", e);
            }
        }
    }
-    async fn emit_server_reconnected(&self) {
+    /// Mark server as unreachable directly.
-        if let Some(app_handle) = &self.app_handle {
+    ///
-            if let Err(e) = app_handle.emit("connectivity:reconnected", ()) {
+    /// Used by deliberate signals (e.g. a failed login/connect) where the caller
-                log::error!("[ConnectivityMonitor] Failed to emit reconnection event: {}", e);
+    /// knows the server is unreachable now. Repository traffic should prefer
-            }
+    /// `reporter().report_network_failure()` so the debounce applies.
    pub async fn mark_unreachable(&self, error: Option<String>) {
        self.reporter.apply_probe_result(false, error).await;
    }
    /// Start the offline recovery probe.
    ///
    /// While **online**, reachability is kept fresh by real traffic, so the probe
    /// idles. While **offline**, it polls `/System/Info/Public` every
    /// `RETRY_CHECK_INTERVAL_MS` to detect the server returning even when no user
    /// traffic is flowing.
    pub async fn start_monitoring(&self) {
        if self.is_monitoring.swap(true, Ordering::SeqCst) {
            log::info!("[ConnectivityMonitor] Already monitoring");
            return;
        }
        log::info!("[ConnectivityMonitor] Starting connectivity monitoring (offline recovery probe)");
        // Perform an immediate check so startup reflects reality quickly.
        let is_reachable = self.check_reachability().await;
        log::info!("[ConnectivityMonitor] Initial connectivity check: {}", if is_reachable { "ONLINE" } else { "OFFLINE" });
        let is_monitoring = Arc::clone(&self.is_monitoring);
        let server_url = Arc::clone(&self.server_url);
        let http_client = Arc::clone(&self.http_client);
        let reporter = self.reporter.clone();
        tokio::spawn(async move {
            while is_monitoring.load(Ordering::SeqCst) {
                tokio::time::sleep(Duration::from_millis(RETRY_CHECK_INTERVAL_MS)).await;
                if !is_monitoring.load(Ordering::SeqCst) {
                    break;
                }
                // Only probe while offline — real traffic is the signal when online.
                if reporter.status.read().await.is_server_reachable {
                    continue;
                }
                let Some(url) = server_url.read().await.clone() else {
                    continue;
                };
                let ping_url = format!("{}/System/Info/Public", url);
                let is_reachable = http_client.ping(&ping_url).await;
                // Probe only ever recovers us to online; a failed probe leaves us
                // offline without re-emitting (no change).
                if is_reachable {
                    reporter.apply_probe_result(true, None).await;
                }
            }
            log::info!("[ConnectivityMonitor] Stopped monitoring");
        });
    }
    /// Stop monitoring connectivity
    pub fn stop_monitoring(&self) {
        log::info!("[ConnectivityMonitor] Stopping connectivity monitoring");
        self.is_monitoring.store(false, Ordering::SeqCst);
    }
 }
@@ -350,11 +349,22 @@ impl ConnectivityMonitorHandle {
 mod tests {
    use super::*;
    /// Build a reporter backed by a fresh (optimistic) status, with no app handle.
    /// Event emission is a no-op without a handle, which is exactly what we want
    /// for unit-testing the reachability state transitions.
    fn test_reporter() -> ConnectivityReporter {
        ConnectivityReporter::new(Arc::new(RwLock::new(ConnectivityStatus::default())), None)
    }
    async fn is_reachable(reporter: &ConnectivityReporter) -> bool {
        reporter.status.read().await.is_server_reachable
    }
    #[test]
    fn test_intervals() {
-        // Verify intervals match TypeScript
+        // Offline recovery probe interval (online has no polling).
        assert_eq!(AUTO_CHECK_INTERVAL_MS, 30000);
        assert_eq!(RETRY_CHECK_INTERVAL_MS, 5000);
        assert_eq!(OFFLINE_CONFIRM_WINDOW, Duration::from_secs(5));
    }
    #[tokio::test]
@@ -366,4 +376,120 @@ mod tests {
        assert!(status.connection_error.is_none());
        assert!(!status.is_checking);
    }
    /// A single (or brief) network failure must NOT flip the app offline:
    /// the time-window debounce keeps us online until the failure persists.
    ///
    /// @req-test: UR-002 - Access media when online or offline
    #[tokio::test]
    async fn test_single_network_failure_does_not_go_offline() {
        let reporter = test_reporter();
        assert!(is_reachable(&reporter).await, "starts online");
        reporter
            .report_network_failure(Some("timeout".to_string()))
            .await;
        assert!(
            is_reachable(&reporter).await,
            "one network failure within the debounce window stays online"
        );
        // But the failure streak is now being tracked.
        assert!(reporter.first_failure_at.read().await.is_some());
    }
    /// Once failures persist past OFFLINE_CONFIRM_WINDOW, we flip offline.
    /// We simulate elapsed time by backdating the streak start.
    ///
    /// @req-test: UR-002 - Access media when online or offline
    #[tokio::test]
    async fn test_sustained_network_failure_goes_offline() {
        let reporter = test_reporter();
        // First failure starts the streak.
        reporter.report_network_failure(None).await;
        assert!(is_reachable(&reporter).await);
        // Backdate the streak start to before the window.
        {
            let mut first = reporter.first_failure_at.write().await;
            *first = Some(Instant::now() - OFFLINE_CONFIRM_WINDOW - Duration::from_secs(1));
        }
        // Next failure now exceeds the window → offline.
        reporter
            .report_network_failure(Some("connection refused".to_string()))
            .await;
        assert!(
            !is_reachable(&reporter).await,
            "sustained network failure flips to offline"
        );
    }
    /// A success during a failure streak clears the streak and keeps us online —
    /// recovery is instant and never trips the banner.
    #[tokio::test]
    async fn test_success_clears_failure_streak() {
        let reporter = test_reporter();
        reporter.report_network_failure(None).await;
        assert!(reporter.first_failure_at.read().await.is_some());
        reporter.report_success().await;
        assert!(is_reachable(&reporter).await);
        assert!(
            reporter.first_failure_at.read().await.is_none(),
            "success resets the debounce streak"
        );
    }
    /// First success after being offline recovers instantly (no debounce on the
    /// way back up).
    #[tokio::test]
    async fn test_recovery_is_instant() {
        let reporter = test_reporter();
        // Force offline.
        reporter.apply_probe_result(false, Some("down".to_string())).await;
        assert!(!is_reachable(&reporter).await);
        // A single success brings us straight back online.
        reporter.report_success().await;
        assert!(is_reachable(&reporter).await);
        let status = reporter.status.read().await;
        assert!(status.connection_error.is_none());
    }
    /// Server-answered errors (401/404/5xx) are reported via report_success
    /// by the repository, because the server is demonstrably reachable. This
    /// test documents that contract: report_success means "server is up".
    #[tokio::test]
    async fn test_server_answered_error_counts_as_reachable() {
        let reporter = test_reporter();
        // Simulate being offline, then the server answers (even with an error).
        reporter.apply_probe_result(false, None).await;
        assert!(!is_reachable(&reporter).await);
        // Repository maps Authentication/NotFound/Server errors to report_success.
        reporter.report_success().await;
        assert!(
            is_reachable(&reporter).await,
            "a server that answers (even with 4xx/5xx) is reachable"
        );
    }
    /// report_network_failure is a no-op once already offline (nothing to debounce,
    /// no duplicate events).
    #[tokio::test]
    async fn test_network_failure_noop_when_already_offline() {
        let reporter = test_reporter();
        reporter.apply_probe_result(false, None).await;
        assert!(!is_reachable(&reporter).await);
        // Should not panic or change state.
        reporter.report_network_failure(Some("still down".to_string())).await;
        assert!(!is_reachable(&reporter).await);
    }
 }
@@ -217,6 +217,7 @@ impl PlayerController {
    /// Used on platforms where video is rendered outside the native backend
    /// (Linux WebKitGTK HTML5 <video>): the queue/UI state must reflect the
    /// item, but MPV must not start a redundant decode for it.
    #[cfg(target_os = "linux")]
    pub fn set_current_item(&self, item: MediaItem) -> Result<(), PlayerError> {
        debug!("[PlayerController] set_current_item (no backend load): {}", item.title);
@@ -5,7 +5,7 @@
 * beyond individual playback states. Enables persistent UI (miniplayer) and
 * proper transitions between content types.
 *
- * See software-architecture.md Section 2.1 for state machine diagram.
+ * See docs/architecture/01-rust-backend.md for the state machine diagram.
 */
 use log::info;
@@ -7,6 +7,7 @@ use log::{debug, error, info};
 use log::warn;
 use serde::{Deserialize, Serialize};
 use crate::connectivity::ConnectivityReporter;
 use crate::jellyfin::HttpClient;
 use super::{MediaRepository, types::*};
@@ -16,6 +17,10 @@ pub struct OnlineRepository {
    server_url: String,
    user_id: String,
    access_token: String,
    /// Reports the outcome of every server request to the connectivity monitor.
    /// This is the source of truth for the offline/online banner. `None` in
    /// tests / contexts where connectivity tracking isn't wired up.
    connectivity: Option<ConnectivityReporter>,
 }
 impl OnlineRepository {
@@ -30,6 +35,44 @@ impl OnlineRepository {
            server_url,
            user_id,
            access_token,
            connectivity: None,
        }
    }
    /// Attach a connectivity reporter so server outcomes drive the reachability
    /// state observed by the UI. See `report_outcome`.
    pub fn with_connectivity(mut self, reporter: ConnectivityReporter) -> Self {
        self.connectivity = Some(reporter);
        self
    }
    /// Feed a request outcome into the connectivity monitor.
    ///
    /// Classification (matches docs/architecture/07-connectivity.md):
    /// - `Ok` / `Authentication` / `NotFound` / `Server` → the server answered,
    ///   so it is reachable → `report_success` (instant recovery).
    /// - `Network` → connection-level failure → `report_network_failure`
    ///   (subject to the time-window debounce before going offline).
    /// - `Database` → not a server signal → ignored.
    async fn report_outcome<T>(&self, result: &Result<T, RepoError>) {
        let Some(reporter) = &self.connectivity else {
            return;
        };
        match result {
            Ok(_)
            | Err(RepoError::Authentication { .. })
            | Err(RepoError::NotFound { .. })
            | Err(RepoError::Server { .. }) => {
                reporter.report_success().await;
            }
            Err(RepoError::Network { message }) => {
                reporter.report_network_failure(Some(message.clone())).await;
            }
            Err(RepoError::Database { .. }) | Err(RepoError::Offline) => {
                // Local-side errors (cache failure / already-offline) — not a
                // statement about the server's reachability, so ignore them.
            }
        }
    }
@@ -63,6 +106,12 @@ impl OnlineRepository {
    /// Make authenticated GET request
    async fn get_json<T: for<'de> Deserialize<'de>>(&self, endpoint: &str) -> Result<T, RepoError> {
        let result = self.get_json_inner(endpoint).await;
        self.report_outcome(&result).await;
        result
    }
    async fn get_json_inner<T: for<'de> Deserialize<'de>>(&self, endpoint: &str) -> Result<T, RepoError> {
        let url = format!("{}{}", self.server_url, endpoint);
        let request = self.http_client.client.get(&url)
@@ -110,6 +159,12 @@ impl OnlineRepository {
    /// Make authenticated POST request
    async fn post_json<T: Serialize>(&self, endpoint: &str, body: &T) -> Result<(), RepoError> {
        let result = self.post_json_inner(endpoint, body).await;
        self.report_outcome(&result).await;
        result
    }
    async fn post_json_inner<T: Serialize>(&self, endpoint: &str, body: &T) -> Result<(), RepoError> {
        let url = format!("{}{}", self.server_url, endpoint);
        let request = self.http_client.client.post(&url)
@@ -145,6 +200,16 @@ impl OnlineRepository {
        &self,
        endpoint: &str,
        body: &T,
    ) -> Result<R, RepoError> {
        let result = self.post_json_response_inner(endpoint, body).await;
        self.report_outcome(&result).await;
        result
    }
    async fn post_json_response_inner<T: Serialize, R: for<'de> Deserialize<'de>>(
        &self,
        endpoint: &str,
        body: &T,
    ) -> Result<R, RepoError> {
        let url = format!("{}{}", self.server_url, endpoint);
@@ -193,9 +258,16 @@ impl OnlineRepository {
        })
    }
-    /// Get a video stream URL for playback with optional seeking support.
+    /// Get a video stream URL for playback at an arbitrary position (resume,
-    /// For direct streams, uses /Videos/{id}/stream.mp4 with transcoding to support seeking.
+    /// transcoded seeking, audio-track switching).
-    /// For transcoded streams (HEVC/10-bit), includes StartTimeTicks parameter.
+    ///
    /// Returns an HLS master playlist (`/Videos/{id}/master.m3u8`) transcoded to
    /// h264/aac. HLS is used rather than a progressive `stream.mp4` because the
    /// HTML5 `<video>` element (via HLS.js) starts playing within seconds and can
    /// seek within the stream, whereas a progressive MP4 transcode of HEVC source
    /// 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.
    pub async fn get_video_stream_url(
        &self,
        item_id: &str,
@@ -210,12 +282,11 @@ impl OnlineRepository {
        // Use provided audio stream index, or default to 0
        let audio_index = audio_stream_index.unwrap_or(0).to_string();
-        // Build URL with progressive MP4 transcoding for seeking support
+        // Build an HLS transcode URL. VideoCodec lists h264 first so the server
-        // This works for both direct streams and HEVC content
+        // transcodes HEVC/10-bit/unsupported sources to h264 the WebView can decode.
        let mut params = vec![
            ("api_key", self.access_token.clone()),
            ("DeviceId", "jellytau-tauri".to_string()),
            ("Container", "mp4".to_string()),
            ("VideoCodec", "h264".to_string()),
            ("AudioCodec", "aac".to_string()),
            ("AudioStreamIndex", audio_index),
@@ -223,6 +294,9 @@ impl OnlineRepository {
            ("VideoBitrate", "18000000".to_string()),
            ("AudioBitrate", "384000".to_string()),
            ("TranscodingMaxAudioChannels", "2".to_string()),
            ("SegmentContainer", "ts".to_string()),
            ("TranscodingContainer", "ts".to_string()),
            ("TranscodingProtocol", "hls".to_string()),
        ];
        if let Some(source_id) = media_source_id {
@@ -241,7 +315,7 @@ impl OnlineRepository {
            .join("&");
        let url = format!(
-            "{}/Videos/{}/stream.mp4?{}",
+            "{}/Videos/{}/master.m3u8?{}",
            self.server_url, item_id, query
        );
@@ -1147,23 +1221,29 @@ impl MediaRepository for OnlineRepository {
        let endpoint = format!("/Users/{}/FavoriteItems/{}", self.user_id, item_id);
        let url = format!("{}{}", self.server_url, endpoint);
-        let request = self.http_client.client.delete(&url)
+        let result = async {
-            .header("X-Emby-Authorization", self.auth_header())
+            let request = self.http_client.client.delete(&url)
-            .build()
+                .header("X-Emby-Authorization", self.auth_header())
-            .map_err(|e| RepoError::Network {
+                .build()
-                message: format!("Failed to build request: {}", e),
+                .map_err(|e| RepoError::Network {
-            })?;
+                    message: format!("Failed to build request: {}", e),
                })?;
-        let response = self.http_client.request_with_retry(request).await
+            let response = self.http_client.request_with_retry(request).await
-            .map_err(|e| RepoError::Network { message: e.to_string() })?;
+                .map_err(|e| RepoError::Network { message: e.to_string() })?;
-        if !response.status().is_success() {
+            if !response.status().is_success() {
-            return Err(RepoError::Server {
+                return Err(RepoError::Server {
-                message: format!("HTTP {}", response.status()),
+                    message: format!("HTTP {}", response.status()),
-            });
+                });
            }
            Ok(())
        }
        .await;
-        Ok(())
+        self.report_outcome(&result).await;
        result
    }
    async fn get_person(&self, person_id: &str) -> Result<MediaItem, RepoError> {
@@ -1388,6 +1468,91 @@ mod tests {
        )
    }
    /// Build a repository wired to a real ConnectivityReporter so we can assert
    /// how `report_outcome` classifies each `RepoError` into reachability.
    /// (No app handle → event emission is a harmless no-op.)
    fn create_test_repository_with_connectivity(
    ) -> (OnlineRepository, crate::connectivity::ConnectivityReporter) {
        let monitor_http = HttpClient::new(crate::jellyfin::HttpConfig::default())
            .expect("Failed to create HTTP client for monitor");
        let monitor = crate::connectivity::ConnectivityMonitor::new(monitor_http);
        let reporter = monitor.reporter();
        let repo = create_test_repository().with_connectivity(reporter.clone());
        (repo, reporter)
    }
    /// `report_outcome` is the seam between repository traffic and the
    /// connectivity monitor. Verify each `RepoError` variant routes correctly:
    /// - the server answering at all (Ok / 401 / 404 / 5xx) ⇒ reachable
    /// - a network-level failure ⇒ marked unreachable (debounce reduced for test)
    /// - local-side errors (Database / Offline) ⇒ no effect on reachability
    ///
    /// @req-test: UR-002 - Access media when online or offline
    /// @req-test: DR-013 - Repository pattern for online/offline data access
    #[tokio::test]
    async fn test_report_outcome_classifies_server_answered_as_reachable() {
        let (repo, reporter) = create_test_repository_with_connectivity();
        // Drive offline first so we can observe "recover to reachable".
        for err in [
            RepoError::Authentication { message: "401".into() },
            RepoError::NotFound { message: "404".into() },
            RepoError::Server { message: "500".into() },
        ] {
            reporter.mark_unreachable_for_test().await;
            assert!(!reporter.is_reachable().await, "precondition: offline");
            let result: Result<(), RepoError> = Err(err);
            repo.report_outcome(&result).await;
            assert!(
                reporter.is_reachable().await,
                "a server that answers should be reported reachable"
            );
        }
        // Ok should also report reachable.
        reporter.mark_unreachable_for_test().await;
        let ok: Result<(), RepoError> = Ok(());
        repo.report_outcome(&ok).await;
        assert!(reporter.is_reachable().await, "Ok ⇒ reachable");
    }
    /// Local-side errors must NOT flip reachability — they say nothing about the
    /// server.
    #[tokio::test]
    async fn test_report_outcome_ignores_local_errors() {
        let (repo, reporter) = create_test_repository_with_connectivity();
        // Force offline, then a Database/Offline error must leave it offline
        // (not falsely report reachable).
        reporter.mark_unreachable_for_test().await;
        for err in [RepoError::Database { message: "cache".into() }, RepoError::Offline] {
            let result: Result<(), RepoError> = Err(err);
            repo.report_outcome(&result).await;
            assert!(
                !reporter.is_reachable().await,
                "local-side error must not change reachability"
            );
        }
    }
    /// A network error routes through the debounced path. A single failure stays
    /// online (debounce window not yet elapsed).
    #[tokio::test]
    async fn test_report_outcome_network_error_is_debounced() {
        let (repo, reporter) = create_test_repository_with_connectivity();
        assert!(reporter.is_reachable().await, "starts online");
        let result: Result<(), RepoError> = Err(RepoError::Network { message: "timeout".into() });
        repo.report_outcome(&result).await;
        assert!(
            reporter.is_reachable().await,
            "a single network failure stays online (debounced)"
        );
    }
    #[tokio::test]
    async fn test_get_audio_stream_url_formats_correctly() {
        let repo = create_test_repository();
@@ -1403,6 +1568,46 @@ mod tests {
        );
    }
    #[tokio::test]
    async fn test_get_video_stream_url_returns_hls_with_position() {
        // Transcoded video resume/seek must produce an HLS master playlist with
        // StartTimeTicks, not a progressive stream.mp4 (which never starts playing
        // for HEVC sources). See get_video_stream_url docs.
        let repo = create_test_repository();
        let url = repo
            .get_video_stream_url("vid-1", Some("source-1"), Some(193.0), Some(1))
            .await
            .unwrap();
        assert!(
            url.starts_with("https://test.server.com/Videos/vid-1/master.m3u8?"),
            "expected HLS master playlist, got: {url}"
        );
        assert!(url.contains("VideoCodec=h264"));
        assert!(url.contains("MediaSourceId=source-1"));
        assert!(url.contains("AudioStreamIndex=1"));
        // 193.0 seconds * 10_000_000 ticks/sec
        assert!(url.contains("StartTimeTicks=1930000000"), "url: {url}");
        assert!(!url.contains("stream.mp4"));
    }
    #[tokio::test]
    async fn test_get_video_stream_url_omits_position_when_absent() {
        let repo = create_test_repository();
        let url = repo
            .get_video_stream_url("vid-1", None, None, None)
            .await
            .unwrap();
        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"));
    }
    #[tokio::test]
    async fn test_get_audio_stream_url_with_special_characters() {
        let repo = create_test_repository();
@@ -1,7 +1,12 @@
 // Connectivity state store for offline support
 //
-// Simplified wrapper over Rust connectivity monitor.
+// Pure reflection of the Rust ConnectivityMonitor. Reachability is the single
-// The Rust backend handles all polling, reachability checks, and adaptive intervals.
+// source of truth in Rust, derived from real repository traffic (success/
 // RepoError), with a time-window debounce before going offline and instant
 // recovery. This store only listens for `connectivity:changed` events and
 // mirrors status; it does not decide reachability itself. navigator.onLine is
 // advisory and triggers a recheck rather than forcing offline.
 // See docs/architecture/07-connectivity.md.
 // TRACES: UR-002 | DR-013
 import { writable, derived } from "svelte/store";
@@ -61,22 +66,27 @@ function createConnectivityStore() {
      }
    });
-    // Listen to browser online/offline events and update state
+    // Listen to browser online/offline events. These are ADVISORY only — the
    // Rust ConnectivityMonitor (fed by real repository traffic) is the source of
    // truth for server reachability. navigator.onLine can be wrong (e.g. a
    // LAN-only server is still reachable while the browser reports "offline"),
    // so we use these events to trigger an immediate recheck rather than forcing
    // the offline state. See docs/architecture/07-connectivity.md.
    window.addEventListener("online", () => {
      update((s) => ({ ...s, isOnline: true }));
      // Device regained network — ask the backend to re-verify the server now.
      checkServerReachable().catch((err) => {
        console.debug("[ConnectivityStore] Recheck after 'online' failed:", err);
      });
    });
    window.addEventListener("offline", () => {
-      update((s) => ({
+      // Reflect the browser's view of the device link, but let the backend
-        ...s,
+      // decide whether the server is actually reachable.
-        isOnline: false,
+      update((s) => ({ ...s, isOnline: false }));
-        isServerReachable: false,
+      checkServerReachable().catch((err) => {
-        connectionError: "Device is offline",
+        console.debug("[ConnectivityStore] Recheck after 'offline' failed:", err);
-      }));
+      });
      if (eventHandlers.onConnectivityChange) {
        eventHandlers.onConnectivityChange(false);
      }
    });
  }
@@ -199,43 +209,11 @@ function createConnectivityStore() {
    return checkServerReachable();
  }
-  /**
+  // Reachability is now driven by the Rust backend from real repository
-   * Mark server as reachable (e.g., after successful API call)
+  // traffic (see docs/architecture/07-connectivity.md). The frontend no longer
-   */
+  // mutates reachability itself, so the former markReachable/markUnreachable
-  async function markReachable(): Promise<void> {
+  // helpers have been removed. The underlying Rust commands remain available
-    try {
+  // for deliberate signals if ever needed.
      await commands.connectivityMarkReachable();
      // Update local state
      update((s) => ({
        ...s,
        isServerReachable: true,
        lastChecked: new Date(),
        connectionError: null,
      }));
    } catch (error) {
      console.error("[ConnectivityStore] Failed to mark reachable:", error);
    }
  }
  /**
   * Mark server as unreachable (e.g., after failed API call)
   */
  async function markUnreachable(error?: string): Promise<void> {
    try {
      await commands.connectivityMarkUnreachable(error ?? null);
      // Update local state
      update((s) => ({
        ...s,
        isServerReachable: false,
        lastChecked: new Date(),
        connectionError: error || "Server unreachable",
      }));
    } catch (err) {
      console.error("[ConnectivityStore] Failed to mark unreachable:", err);
    }
  }
  return {
    subscribe,
@@ -244,8 +222,6 @@ function createConnectivityStore() {
    setServerUrl,
    forceCheck,
    checkServerReachable,
    markReachable,
    markUnreachable,
    isNetworkError,
  };
 }
Author	SHA1	Message	Date
dtourolle	674c8e5cd0	ci(release): fix release-notes generation breaking jq publish step 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 3m11s Details Traceability Validation / Check Requirement Traces (push) Successful in 20s Details Build & Release / Run Tests (push) Successful in 3m40s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 18m36s Details Build & Release / Build Linux (push) Successful in 15m56s Details Build & Release / Build Android (push) Successful in 18m33s Details Build & Release / Create Release (push) Successful in 7s Details The release-notes echo lines used unescaped backticks, which the shell ran as command substitution; their output leaked control characters into release_notes.md, so jq failed with 'Invalid string: control characters ... must be escaped' when building the release payload. - Escape the backticks so they are literal markdown. - Remove emoji from the release-notes content (plain ASCII headings). - Handle an already-existing release (HTTP 409) by reusing its id for asset upload instead of failing.	2026-06-23 20:38:09 +02:00
dtourolleandClaude Opus 4.8	45aa029916	fix(connectivity): drive reachability from real repository traffic 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 3m32s Details Traceability Validation / Check Requirement Traces (push) Successful in 20s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 18m27s Details Build & Release / Run Tests (push) Successful in 3m36s Details Build & Release / Build Linux (push) Successful in 15m43s Details Build & Release / Build Android (push) Successful in 18m40s Details Build & Release / Create Release (push) Failing after 22s Details The offline/online switch was janky because two independent systems decided "online" and never communicated: - ConnectivityMonitor owned is_server_reachable (drove the UI banner) but learned reachability only from a standalone /System/Info/Public ping loop and from auth/login calls. - HybridRepository served all real data by racing cache-vs-server but never read or wrote reachability. So the banner reflected a side-channel poller, not the system the user actually experienced: a successful ping could read "online" while authenticated data calls 401'd or timed out, and three different timeout regimes (5s ping / 30s data / 100ms cache race) flapped against each other. Unify into a single source of truth: - Extract a cheap, cloneable ConnectivityReporter that owns all reachability transitions and event emission. - OnlineRepository reports the outcome of every server request to the reporter, classified via RepoError: Ok/Authentication/NotFound/Server => reachable (the server answered), Network => offline candidate, Database/Offline => ignored (not a server signal). - Time-window debounce (OFFLINE_CONFIRM_WINDOW = 5s): flip offline only after sustained network failure; recover instantly on the first success. - Demote the ping loop to an offline-only recovery probe (no online polling; real traffic is the signal when online). - Frontend: navigator.onLine is now advisory (triggers a recheck instead of forcing offline); removed the dead markReachable/markUnreachable store methods. Docs updated (README, 07-connectivity, 03-data-flow, 02-svelte-frontend) to describe the new model and fix pre-existing drift (HTTP client is 30s timeout + 5s ping, not the documented 10s/base_url). Tests: 12 connectivity tests (debounce, instant recovery, RepoError classification through report_outcome). Full suite: 398 Rust + 384 frontend passing, svelte-check clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-21 21:56:14 +02:00
dtourolleandClaude Opus 4.8	3faa595b76	fix(android): track VideoOverlayManager.kt in canonical source tree 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 2m28s Details Traceability Validation / Check Requirement Traces (push) Successful in 20s Details Build & Release / Run Tests (push) Successful in 3m11s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 17m51s Details Build & Release / Build Linux (push) Successful in 15m29s Details Build & Release / Build Android (push) Failing after 18m9s Details Build & Release / Create Release (push) Has been skipped Details JellyTauPlayer.kt references com.dtourolle.jellytau.VideoOverlayManager, but the file existed only in the gitignored gen/android dir, so it survived locally but vanished in CI (which regenerates gen/android via 'tauri android init'). sync-android-sources.sh copies top-level *.kt from src-tauri/android, so adding it there gets it synced into the build. Fixes: 'Unresolved reference: VideoOverlayManager' in :app:compileUniversalReleaseKotlin. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-21 21:55:30 +02:00
dtourolleandClaude Opus 4.8	7fb866a583	ci: fix release Android build --apk flag requires explicit value 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 2m26s Details Traceability Validation / Check Requirement Traces (push) Successful in 19s Details Build & Release / Run Tests (push) Successful in 2m29s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 17m57s Details Build & Release / Build Linux (push) Successful in 15m38s Details Build & Release / Build Android (push) Failing after 14m48s Details Build & Release / Create Release (push) Has been skipped Details Tauri CLI requires '--apk true'; bare '--apk' fails with "a value is required for '--apk <APK>'". The release workflow only reached this step now that checkout/container issues are fixed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-21 20:44:23 +02:00
dtourolle	0c3ed74fe1	ci: Improvements 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 12m47s Details Traceability Validation / Check Requirement Traces (push) Successful in 22s Details Build & Release / Run Tests (push) Successful in 2m27s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 28m0s Details Build & Release / Build Linux (push) Successful in 15m45s Details Build & Release / Build Android (push) Failing after 49s Details Build & Release / Create Release (push) Has been skipped Details	2026-06-21 17:38:06 +02:00
dtourolle	a5b6266a6d	Permanent CI fix 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 6m54s Details Traceability Validation / Check Requirement Traces (push) Successful in 22s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 1h14m25s Details Build & Release / Run Tests (push) Failing after 7s Details Build & Release / Build Linux (push) Has been skipped Details Build & Release / Build Android (push) Has been skipped Details Build & Release / Create Release (push) Has been skipped Details	2026-06-21 10:48:26 +02:00
dtourolle	a816c84f8c	fix CI 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 4m31s Details Traceability Validation / Check Requirement Traces (push) Successful in 21s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Has been cancelled Details	2026-06-21 10:35:14 +02:00
dtourolle	87762c03b6	Fix linux playback 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 4m38s Details Traceability Validation / Check Requirement Traces (push) Successful in 22s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Has been cancelled Details	2026-06-21 10:16:25 +02:00
dtourolle	975936b902	Merge pull request 'chore: clean up repo organization' (#2 ) from chore/repo-cleanup into master 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 4m44s Details Traceability Validation / Check Requirement Traces (push) Successful in 30s Details 🏗️ Build and Test JellyTau / Build Android APK (push) Has been cancelled Details Reviewed-on: #2	2026-06-21 07:53:30 +00:00
dtourolle	5ba9e0e958	chore: clean up repo organization 🏗️ Build and Test JellyTau / Run Tests (pull_request) Successful in 5m6s Details Traceability Validation / Check Requirement Traces (pull_request) Successful in 30s Details 🏗️ Build and Test JellyTau / Build Android APK (pull_request) Failing after 19m30s Details - Standardize on bun: remove package-lock.json, add packageManager field, gitignore non-bun lockfiles, fix stray npm install in android:build:clean - Remove stale build logs and empty dirs (src-tauri/plugins, docs/tickets) - Move android-dev.sh into scripts/ - Consolidate root docs into docs/ (docker/builder under docs/build/); move the architecture overview to docs/architecture/README.md - Extract Requirements Specification from README into docs/requirements.md and slim README down to a project intro + docs index - Fix internal references to the moved files	2026-06-21 09:52:09 +02:00