ci: drop redundant setup-bun step that stalls Gitea runner

bun is already baked into the jellytau-builder image (Dockerfile.builder),
so oven-sh/setup-bun@v1 was redundant. Fetching that GitHub-hosted action
from the self-hosted Gitea runner hangs the job before any steps run.
Removed from traceability-check, traceability, and publish-docs workflows;
build-and-test and build-release never used it and never stalled.

.gitea/workflows/build-and-test.yml

@@ -14,9 +14,9 @@ on:
   workflow_dispatch:
 
 jobs:
-  build:
-    name: Build APK and Run Tests
-    runs-on: ubuntu-latest
+  test:
+    name: Run Tests
+    runs-on: linux/amd64
     container:
       image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 
@@ -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
@@ -50,7 +50,9 @@ jobs:
           bun install
 
       - name: Run frontend tests
-        run: bun test
+        run: |
+          bunx svelte-kit sync
+          bun run test
 
       - name: Run Rust tests
         run: |
@@ -58,24 +60,58 @@ jobs:
           cargo test
           cd ..
 
-      - name: Build frontend
-        run: bun run build
+  # Fast per-commit Android compile check. This does NOT build a shippable APK:
+  # the full signed release APK is built only on tag pushes by build-release.yml
+  # (which runs sync-android-sources.sh + signing). Running the full bundle here
+  # too would duplicate a ~15min build and, without the sync step, produced an
+  # unsigned APK missing our custom sources/icons/proguard rules anyway.
+  # `cargo check` for the Android target (~1min) catches Android-specific Rust
+  # breakage without linking, bundling, or signing.
+  android-check:
+    name: Android Compile Check
+    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
+      NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
+      ANDROID_NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
 
-      - name: Build Android APK
-        id: build
-        run: |
-          mkdir -p artifacts
-          bun run tauri android build --apk true
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
-          # Find the generated APK file
-          ARTIFACT=$(find src-tauri/gen/android/app/build/outputs/apk -name "*.apk" -type f -print -quit)
-          echo "artifact=${ARTIFACT}" >> $GITHUB_OUTPUT
-          echo "Found artifact: ${ARTIFACT}"
-
-      - name: Upload build artifact
-        uses: actions/upload-artifact@v3
+      - name: Cache Rust dependencies
+        uses: actions/cache@v3
         with:
-          name: jellytau-apk
-          path: ${{ steps.build.outputs.artifact }}
-          retention-days: 30
-          if-no-files-found: error
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/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: Cargo check (aarch64-linux-android)
+        run: |
+          TC="$NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin"
+          export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$TC/aarch64-linux-android24-clang"
+          export CC_aarch64_linux_android="$TC/aarch64-linux-android24-clang"
+          export AR_aarch64_linux_android="$TC/llvm-ar"
+          cd src-tauri
+          cargo check --target aarch64-linux-android --lib

.gitea/workflows/build-release.yml

@@ -17,38 +17,41 @@ env:
 jobs:
   test:
     name: Run Tests
-    runs-on: ubuntu-latest
+    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/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          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
+        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
@@ -61,47 +64,34 @@ jobs:
 
   build-linux:
     name: Build Linux
-    runs-on: ubuntu-latest
+    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/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          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
+        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
@@ -133,76 +123,110 @@ jobs:
 
   build-android:
     name: Build Android
-    runs-on: ubuntu-latest
+    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/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/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: Build for Android
-        run: bun run tauri android build
-        env:
-          ANDROID_NDK_HOME: ${{ android.ndk-home }}
-          ANDROID_SDK_ROOT: ${{ android.sdk-root }}
-          ANDROID_HOME: ${{ android.sdk-root }}
+      - name: Set app version from tag
+        run: |
+          # On a tag build, the tag is the single source of truth for the
+          # version name. On non-tag runs keep whatever is in tauri.conf.json.
+          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
+            VERSION="${GITHUB_REF#refs/tags/v}"
+            echo "Setting version to $VERSION"
+            sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" src-tauri/tauri.conf.json
+          fi
+          grep '"version"' src-tauri/tauri.conf.json
 
-      - name: Prepare Android artifacts
+      - name: Initialize Android project
+        run: bun run tauri android init
+
+      - name: Pin a monotonic Android versionCode
+        run: |
+          # `tauri android init` autogenerates src-tauri/gen/android/app/tauri.properties
+          # with a versionCode derived from the semver (e.g. 0.0.15 -> 15). That
+          # number is (a) tiny and (b) NOT monotonic across our history: earlier
+          # local/dev builds shipped versionCode 1000 (from a 0.1.0 config), so a
+          # plain 15 would be a *downgrade* and Android would refuse the update.
+          #
+          # Derive an explicit code that is both monotonic in semver order and
+          # always above the 1000 floor already in the field:
+          #   code = 1000 + major*10000 + minor*100 + patch
+          # e.g. 0.0.14 -> 1014, 0.0.15 -> 1015, 0.1.0 -> 1100, 1.0.0 -> 11000.
+          # POSIX sh only (the runner uses dash): no here-strings, no \s in sed.
+          PROPS="src-tauri/gen/android/app/tauri.properties"
+          VERSION=$(grep '"version"' src-tauri/tauri.conf.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+          MAJ=$(echo "$VERSION" | cut -d. -f1)
+          MIN=$(echo "$VERSION" | cut -d. -f2)
+          PAT=$(echo "$VERSION" | cut -d. -f3)
+          # Guard against a malformed/missing component so we never emit code 0.
+          : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
+          CODE=$(( 1000 + MAJ*10000 + MIN*100 + PAT ))
+          echo "version=$VERSION -> versionCode=$CODE"
+          if grep -q '^tauri.android.versionCode=' "$PROPS"; then
+            sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
+          else
+            echo "tauri.android.versionCode=$CODE" >> "$PROPS"
+          fi
+          cat "$PROPS"
+
+      - name: Sync custom Android sources & gradle config
+        run: ./scripts/sync-android-sources.sh
+
+      - name: Write signing keystore
+        run: |
+          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 -d > "$RUNNER_TEMP/jellytau-release.jks"
+          cat > src-tauri/gen/android/keystore.properties <<EOF
+          storeFile=$RUNNER_TEMP/jellytau-release.jks
+          storePassword=${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
+          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
+          EOF
+
+      - name: Build signed Android APK
+        run: bun run tauri android build --apk true --target aarch64
+
+      - name: Collect & verify signed APK
         run: |
           mkdir -p dist/android
-          # Copy APK
-          if [ -f "src-tauri/gen/android/app/build/outputs/apk/release/app-release.apk" ]; then
-            cp src-tauri/gen/android/app/build/outputs/apk/release/app-release.apk dist/android/jellytau-release.apk
-          fi
-          # Copy AAB (Android App Bundle) if built
-          if [ -f "src-tauri/gen/android/app/build/outputs/bundle/release/app-release.aab" ]; then
-            cp src-tauri/gen/android/app/build/outputs/bundle/release/app-release.aab dist/android/jellytau-release.aab
-          fi
+          APK=$(find src-tauri/gen/android/app/build/outputs/apk -name '*-release.apk' | head -1)
+          if [ -z "$APK" ]; then echo "❌ No release APK produced"; exit 1; fi
+          cp "$APK" dist/android/jellytau-release.apk
+          APKSIGNER=$(find "$ANDROID_SDK_ROOT/build-tools" -name apksigner | sort -V | tail -1)
+          echo "🔏 Verifying signature with $APKSIGNER"
+          "$APKSIGNER" verify --print-certs dist/android/jellytau-release.apk
           ls -lah dist/android/
 
       - name: Upload Android build artifact
@@ -214,9 +238,11 @@ jobs:
 
   create-release:
     name: Create Release
-    runs-on: ubuntu-latest
+    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
@@ -243,23 +269,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
@@ -277,11 +303,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
@@ -292,46 +318,52 @@ 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: Create GitHub Release
-        uses: softprops/action-gh-release@v1
-        if: startsWith(github.ref, 'refs/tags/')
-        with:
-          name: ${{ steps.tag_name.outputs.RELEASE_NAME }}
-          body_path: release_notes.md
-          files: |
-            artifacts/linux/*
-            artifacts/android/*
-          draft: false
-          prerelease: ${{ contains(steps.tag_name.outputs.VERSION, 'rc') || contains(steps.tag_name.outputs.VERSION, 'beta') || contains(steps.tag_name.outputs.VERSION, 'alpha') }}
+      - name: Publish Gitea release & upload assets
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Upload to Gitea Releases
+          # GITEA_TOKEN (a PAT) is preferred; falls back to the auto-provided token.
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          AUTO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
+          set -e
+          command -v jq >/dev/null || { echo "❌ jq is required on the runner"; exit 1; }
           VERSION="${{ steps.tag_name.outputs.VERSION }}"
+          API="${GITHUB_SERVER_URL}/api/v1"
+          REPO="${GITHUB_REPOSITORY}"
+          TOKEN="${GITEA_TOKEN:-$AUTO_TOKEN}"
+          case "$VERSION" in *rc*|*beta*|*alpha*) PRE=true;; *) PRE=false;; esac
 
-          echo "📦 Release artifacts prepared for $VERSION"
-          echo ""
-          echo "Linux:"
-          ls -lh artifacts/linux/ || echo "No Linux artifacts"
-          echo ""
-          echo "Android:"
-          ls -lh artifacts/android/ || echo "No Android artifacts"
-          echo ""
-          echo "✅ Release $VERSION is ready!"
-          echo "📄 Release notes saved to release_notes.md"
+          PAYLOAD=$(jq -n \
+            --arg tag "$VERSION" \
+            --arg name "JellyTau $VERSION" \
+            --rawfile body release_notes.md \
+            --argjson pre "$PRE" \
+            '{tag_name:$tag, name:$name, body:$body, draft:false, prerelease:$pre}')
 
-      - name: Publish release notes
-        run: |
-          echo "## 🎉 Release Published"
-          echo ""
-          echo "**Version:** ${{ steps.tag_name.outputs.VERSION }}"
-          echo "**Tag:** ${{ github.ref }}"
-          echo ""
-          echo "Artifacts:"
-          echo "- Linux artifacts in: artifacts/linux/"
-          echo "- Android artifacts in: artifacts/android/"
-          echo ""
-          echo "Visit the Release page to download files."
+          echo "📦 Creating release $VERSION on $REPO"
+          # -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")
+          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
+            [ -f "$f" ] || continue
+            echo "⬆️  Uploading $(basename "$f")"
+            curl -fsS -X POST \
+              "$API/repos/$REPO/releases/$RELEASE_ID/assets?name=$(basename "$f")" \
+              -H "Authorization: token $TOKEN" \
+              -F "attachment=@$f" >/dev/null
+          done
+          echo "✅ Release $VERSION published with assets"

.gitea/workflows/publish-docs.yml

@@ -0,0 +1,122 @@
+name: Publish Documentation
+
+# Renders the markdown docs (docs/*.md) into an mdBook site, builds the Rust
+# API reference with cargo doc, and force-pushes the combined output to the
+# orphan `gitea-pages` branch that the Gitea Pages server serves.
+#
+# The published matrix is regenerated during the build, so it is never stale.
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency:
+  # Only one docs publish at a time; a newer push supersedes an in-flight run.
+  group: publish-docs
+  cancel-in-progress: true
+
+jobs:
+  publish-docs:
+    name: Build & publish docs to gitea-pages
+    runs-on: linux/amd64
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # bun is baked into jellytau-builder (see Dockerfile.builder); no setup-bun
+      # action needed — fetching it stalls on this Gitea runner.
+      - name: Install dependencies
+        run: bun install
+
+      - name: Install mdBook
+        run: |
+          set -e
+          MDBOOK_VERSION=v0.4.40
+          URL="https://github.com/rust-lang/mdBook/releases/download/${MDBOOK_VERSION}/mdbook-${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+          echo "⬇️  Downloading mdBook ${MDBOOK_VERSION}"
+          curl -fsSL "$URL" | tar -xz -C /usr/local/bin
+          mdbook --version
+
+      - name: Regenerate traceability matrix (keep published copy current)
+        run: bun run traces:markdown
+
+      - name: Assemble mdBook sources
+        run: |
+          set -e
+          # mdBook's src is docs/. Drop in the SUMMARY and the generated
+          # intro + API redirect pages (build artifacts, not committed).
+          cp docs-site/SUMMARY.md docs/SUMMARY.md
+
+          cat > docs/README.md <<'EOF'
+          # JellyTau Documentation
+
+          Cross-platform Jellyfin client — business logic in a Rust backend,
+          SvelteKit + TypeScript frontend, talking over Tauri v2 IPC.
+
+          - **[Requirements Specification](requirements.md)** — user, integration, and development requirements.
+          - **[Traceability Matrix](traceability.md)** — generated map from requirements to code (regenerated on every publish).
+          - **[Architecture](architecture/README.md)** — backend, frontend, data flow, platform backends.
+          - **[Rust API Reference](api/index.html)** — rustdoc for the `src-tauri` backend.
+
+          _This site is published automatically from `master` by the `publish-docs` CI job._
+          EOF
+
+          cat > docs/api-redirect.md <<'EOF'
+          # Rust API Reference
+
+          The full backend API reference is generated by `cargo doc` (rustdoc).
+
+          👉 **[Open the Rust API Reference](api/index.html)**
+          EOF
+
+      - name: Build mdBook site
+        run: mdbook build docs-site --dest-dir "$GITHUB_WORKSPACE/site"
+
+      - name: Build Rust API docs (cargo doc)
+        working-directory: src-tauri
+        # --no-deps keeps it to our own crate (fast, focused); document private
+        # items so internal modules/commands appear.
+        run: |
+          cargo doc --no-deps --document-private-items
+          # The backend modules/commands live in the LIB crate (jellytau_lib);
+          # the bin crate (jellytau) is a near-empty shim. Land on the lib.
+          echo '<meta http-equiv="refresh" content="0; url=jellytau_lib/index.html">' \
+            > target/doc/index.html
+
+      - name: Assemble published output
+        run: |
+          set -e
+          mkdir -p "$GITHUB_WORKSPACE/site/api"
+          cp -r src-tauri/target/doc/. "$GITHUB_WORKSPACE/site/api/"
+          # Disable Jekyll processing on the pages branch.
+          touch "$GITHUB_WORKSPACE/site/.nojekyll"
+          ls -la "$GITHUB_WORKSPACE/site"
+
+      - name: Push to gitea-pages branch
+        env:
+          # PAT preferred; falls back to the auto-provided token (same pattern
+          # as build-release.yml).
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          AUTO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          TOKEN="${GITEA_TOKEN:-$AUTO_TOKEN}"
+          REPO="${GITHUB_REPOSITORY}"
+          HOST="$(echo "$GITHUB_SERVER_URL" | sed -E 's#^https?://##')"
+          REMOTE="https://oauth2:${TOKEN}@${HOST}/${REPO}.git"
+
+          cd "$GITHUB_WORKSPACE/site"
+          git init -q
+          git config user.name "gitea-actions"
+          git config user.email "actions@gitea.tourolle.paris"
+          git checkout -q -b gitea-pages
+          git add -A
+          git commit -q -m "docs: publish site from ${GITHUB_SHA::8}"
+          echo "🚀 Force-pushing to gitea-pages"
+          git push -f "$REMOTE" gitea-pages

.gitea/workflows/traceability-check.yml

@@ -14,8 +14,10 @@ on:
 
 jobs:
   validate-traces:
-    runs-on: ubuntu-latest
+    runs-on: linux/amd64
     name: Check Requirement Traces
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 
     steps:
       - name: Checkout repository
@@ -23,9 +25,8 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
+      # bun is baked into jellytau-builder (see Dockerfile.builder); no setup-bun
+      # action needed — fetching it stalls on this Gitea runner.
       - name: Install dependencies
         run: bun install
 
@@ -93,20 +94,28 @@ jobs:
           echo ""
 
           # Check each file
-          MISSING_TRACES=0
-          while IFS= read -r file; do
+          # Pipe into the loop instead of a here-string (<<<) so this step works
+          # under POSIX sh/dash, not just bash. Use `case` instead of `[[ == ]]`
+          # for the same reason. The loop runs in a subshell (so a counter var
+          # wouldn't survive), so we record warnings in a temp file and count it
+          # afterwards.
+          MISSING_FILE=$(mktemp)
+          echo "$CHANGED" | while IFS= read -r file; do
             # Skip test files
-            if [[ "$file" == *".test."* ]]; then
-              continue
-            fi
+            case "$file" in
+              *.test.*) continue ;;
+            esac
 
             if [ -f "$file" ]; then
               if ! grep -q "TRACES:" "$file"; then
                 echo "⚠️  Missing TRACES: $file"
-                MISSING_TRACES=$((MISSING_TRACES + 1))
+                echo "$file" >> "$MISSING_FILE"
               fi
             fi
-          done <<< "$CHANGED"
+          done
+
+          MISSING_TRACES=$(wc -l < "$MISSING_FILE" | tr -d ' ')
+          rm -f "$MISSING_FILE"
 
           if [ "$MISSING_TRACES" -gt 0 ]; then
             echo ""
@@ -127,9 +136,9 @@ jobs:
         run: |
           echo ""
           echo "📊 Full Report Generated"
-          echo "📁 Location: docs/TRACEABILITY.md"
+          echo "📁 Location: docs/traceability.md"
           echo ""
-          head -50 docs/TRACEABILITY.md || true
+          head -50 docs/traceability.md || true
 
       - name: Save artifacts
         if: always()
@@ -138,5 +147,5 @@ jobs:
           name: traceability-reports
           path: |
             traces-report.json
-            docs/TRACEABILITY.md
+            docs/traceability.md
           retention-days: 30

.gitea/workflows/traceability.yml

@@ -15,17 +15,16 @@ on:
 jobs:
   traceability:
     name: Validate Requirement Traces
-    runs-on: ubuntu-latest
+    runs-on: linux/amd64
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-
+      # bun is baked into jellytau-builder (see Dockerfile.builder); no setup-bun
+      # action needed — fetching it stalls on this Gitea runner.
       - name: Install dependencies
         run: bun install
 
@@ -133,7 +132,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: traceability-report
-          path: docs/TRACEABILITY.md
+          path: docs/traceability.md
           retention-days: 30
 
       - name: Comment PR with coverage report

.gitignore

@@ -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
@@ -47,3 +52,15 @@ vite.config.ts.timestamp-*
 # Logs
 logs
 *.log
+
+# Android signing keystore (NEVER commit)
+android-keystore/
+
+# Local machine-specific Android NDK toolchain paths (do not commit)
+src-tauri/.cargo/config.toml
+
+# Docs site build artifacts (generated by the publish-docs CI job into docs/)
+/docs/SUMMARY.md
+/docs/README.md
+/docs/api-redirect.md
+/docs-site/book/

CLAUDE.md

@@ -0,0 +1,245 @@
+# JellyTau
+
+A cross-platform Jellyfin client. Business logic lives in a Rust backend
+(`src-tauri/`); a SvelteKit + TypeScript frontend (`src/`) handles presentation
+and talks to it over Tauri v2 IPC. Targets **Linux** (libmpv, WebKitGTK HTML5
+`<video>` for transcoded playback) and **Android** (ExoPlayer).
+
+Package manager is **bun**.
+
+## Build / Run / Test
+
+All routine tasks go through `package.json` scripts and helper scripts in
+`scripts/`:
+
+```bash
+bun install                  # install deps
+bun run dev                  # vite dev server (frontend)
+bun run tauri dev            # run the desktop app
+
+bun run check                # svelte-check (types)
+bun run test                 # vitest (frontend unit/integration)
+bun run test:rust            # cargo test (scripts/test-rust.sh)
+bun run test:all             # full suite (scripts/test-all.sh)
+bun run test:e2e             # webdriverio e2e
+
+# Android — canonical entry points (see scripts/):
+bun run android:build            # debug APK
+bun run android:build:release    # release APK
+bun run android:deploy           # install to connected device
+bun run android:dev              # build + deploy
+bun run android:logs             # logcat
+```
+
+CI runs on **Gitea Actions** (`.gitea/workflows/`), not GitHub. Use the `gh` CLI
+only against the mirror if one exists; the canonical remote is
+`gitea.tourolle.paris`.
+
+## Before Committing
+
+- Frontend: `bun run check` and `bun run test` must pass.
+- Rust: `cd src-tauri && cargo fmt` then `cargo clippy`, plus `bun run test:rust`.
+- **Traceability**: new requirement-implementing code must carry a `// TRACES:`
+  comment (see below).
+- **Android source edits**: edit `src-tauri/android/src` (the canonical tree),
+  then run `scripts/sync-android-sources.sh` to sync into the `gen/` tree.
+  Never edit the generated `gen/` sources directly.
+
+## Traceability (TRACES)
+
+This project practices requirement-driven development: code that implements a
+requirement is tagged with a `TRACES:` comment linking it to requirement IDs, and
+an extraction tool builds the traceability matrix. **When you add or change code
+that implements a requirement, add/update its TRACES comment.** Internal helpers
+and requirement-less code stay untraced.
+
+Format — `// TRACES: <URs> | <DRs> | <tests>`, e.g.:
+
+```rust
+/// TRACES: UR-005 | DR-001
+pub enum PlayerState { … }
+```
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+export function autoplayNextEpisode() { }
+```
+
+ID types: **UR** user requirement, **IR** integration, **DR** development, **JA**
+Jellyfin API, **UT** unit test, **IT** integration test. Requirements are defined
+in [docs/requirements.md](docs/requirements.md); the generated matrix is
+[docs/traceability.md](docs/traceability.md).
+
+Tooling:
+
+```bash
+bun run traces            # extract traces (default format)
+bun run traces:json       # JSON — e.g. | jq '.byType' or '.requirements."UR-005"'
+bun run traces:markdown   # regenerate docs/traceability.md
+git diff --name-only | xargs grep -L "TRACES:"   # find untraced changed files
+```
+
+**CI is Gitea Actions** (`.gitea/workflows/`, remote `gitea.tourolle.paris`), not
+GitHub. `traceability-check.yml` fails the build if coverage drops below
+**50%** (`MIN_THRESHOLD`); `build-and-test.yml` runs frontend + Rust tests and an
+Android `cargo check`. See [docs/traceability-ci.md](docs/traceability-ci.md) and
+[docs/traces-quick-ref.md](docs/traces-quick-ref.md).
+
+### Traces drive release notes
+
+Prefer traceability over raw commit subjects when writing release notes for
+[docs/release-checklist.md](docs/release-checklist.md). Raw `git log` subjects are
+noisy; the TRACES graph gives a semantic summary of *what capabilities* the
+release touched.
+
+```bash
+bun run release:notes                 # <latest tag>..HEAD
+bun run release:notes v0.0.15..HEAD   # explicit range
+```
+
+[scripts/release-notes.ts](scripts/release-notes.ts) resolves a commit range's
+changed files → their `TRACES:` IDs → descriptions in
+[docs/requirements.md](docs/requirements.md), then groups **UR** into *Features*
+and **DR/IR** into *Improvements* (deduped, so many commits touching one
+requirement collapse to one line). It also lists changed files that carry no
+TRACES so nothing is silently dropped — those still need a manual line. Treat the
+output as a reviewed draft, not a final changelog.
+
+## Architecture
+
+- **Rust backend** (`src-tauri/src/`) — all business logic: auth, catalog,
+  sessions, downloads, offline cache, playback control. Commands grouped by
+  domain in `src-tauri/src/commands/` (`auth.rs`, `catalog.rs`, `player/`,
+  `download/`, `offline.rs`, `sessions.rs`, …).
+- **Svelte frontend** (`src/`) — presentation only. Stores in
+  `src/lib/stores/`, API wrappers in `src/lib/api/`, components in
+  `src/lib/components/`.
+- **Playback layers** — Linux uses libmpv for direct playback and a WebKitGTK
+  HTML5 `<video>` element for HLS-transcoded (h264) streams; Android uses
+  ExoPlayer with a foreground media service + `MediaSessionCompat`.
+- **tauri-specta** generates TypeScript bindings and typed events from the Rust
+  command/event definitions (registered via the Builder in `src-tauri/src/lib.rs`).
+
+**Read the architecture docs before making structural changes** — they are the
+canonical, maintained source; this file only summarizes. See
+[docs/architecture/README.md](docs/architecture/README.md) and:
+
+| Doc | Contents |
+|-----|----------|
+| [01-rust-backend.md](docs/architecture/01-rust-backend.md) | Player/session state machines, playback mode, queue, commands |
+| [02-svelte-frontend.md](docs/architecture/02-svelte-frontend.md) | Stores, repository architecture, MiniPlayer, autoplay, nav guard |
+| [03-data-flow.md](docs/architecture/03-data-flow.md) | Cache-first query flow, playback initiation, mode transfer |
+| [04-type-sync-and-threading.md](docs/architecture/04-type-sync-and-threading.md) | **Rust↔TS type sync, the IPC camelCase convention + param table, locking** |
+| [05-platform-backends.md](docs/architecture/05-platform-backends.md) | MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession, HTML5 adapter |
+| [06-downloads-and-offline.md](docs/architecture/06-downloads-and-offline.md) | Download manager/worker, smart cache, offline commands |
+| [07-connectivity.md](docs/architecture/07-connectivity.md) | HTTP retry, ConnectivityMonitor, reachability model |
+| [08-database-design.md](docs/architecture/08-database-design.md) | Tables, relationships, key queries |
+| [09-security.md](docs/architecture/09-security.md) | Token storage, secure storage, network security |
+
+Release process lives in [docs/release-checklist.md](docs/release-checklist.md)
+and [docs/build-release.md](docs/build-release.md).
+
+### Core principles (from the architecture docs)
+
+- **Playback state is one-directional.** The player (ExoPlayer on Android, MPV on
+  Linux, session poller in remote mode) is the **authoritative source** of state
+  — position, pause, seeking, rate, track changes. The Svelte UI, OS
+  `MediaSession`/lockscreen, and MPRIS are **consumers**; they reflect what the
+  player reports and never determine it.
+- **Unified player boundary.** UI controls playback *only* through the frontend
+  facade `src/lib/player/index.ts` (`playerController`) — never by calling
+  `commands.player*` directly. Webview HTML5 `<video>` reports its state back
+  into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*`
+  commands, so the controller stays the single source of truth in both native
+  and HTML5 modes.
+- **Reachability from real traffic.** Server online/offline is derived from the
+  outcome of actual repository requests (reported to `ConnectivityMonitor`), not
+  a side-channel poller. The `/System/Info/Public` probe runs *only while
+  offline*, as a recovery detector.
+- **Poison-tolerant locking.** Access shared `std::sync` state 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 fails to initialize, the
+  app falls back to a no-op backend and emits `backend-init-failed` rather than
+  crashing.
+
+## Conventions
+
+### Rust Backend
+
+- Use `#[tauri::command]` for all IPC handlers.
+- Prefer `async` commands for I/O-bound work.
+- Return `Result<T, String>` from commands (the established convention here).
+- Use `tauri::State<>` for shared state.
+- Group related commands in domain modules under `commands/`.
+- Use official Tauri plugins before writing custom native code.
+
+### Frontend
+
+- Use `invoke<T>()` from `@tauri-apps/api/core`, or the tauri-specta bindings.
+- Define TS types matching the Rust structs; prefer the generated bindings.
+- Handle IPC errors with try/catch.
+- Use `@tauri-apps/api/path` for paths (never hardcode).
+- Use `@tauri-apps/api/event` for backend→frontend events.
+
+### 🔴 IPC parameter naming (Tauri v2)
+
+The command **name** must match the Rust function name exactly
+(`invoke("player_play_queue", …)`). But **parameter names do NOT** — Tauri v2's
+`#[tauri::command]` macro auto-converts snake_case Rust params to **camelCase**
+on the frontend:
+
+```rust
+#[tauri::command]
+pub async fn cmd(repository_handle: String) { … }
+```
+```typescript
+await invoke("cmd", { repositoryHandle: "…" }); // camelCase, auto-converted
+```
+
+Nested struct fields need `#[serde(rename_all = "camelCase")]`; tagged unions use
+`#[serde(tag = "type")]` and both sides must match the tag. Note: tauri-specta
+tagged responses keep the Rust field names as-is (e.g. `new_url`, not `newUrl`).
+
+### Events
+
+- Backend events use **kebab-case** names (`download-event`, `search-event`).
+- Emit from Rust via `emit(...)`; consume on the frontend via
+  `@tauri-apps/api/event` or the tauri-specta typed event bindings.
+
+### Security
+
+- Declare minimum permissions in `src-tauri/capabilities/`.
+- Keep the CSP restrictive in `tauri.conf.json`.
+- Validate all inputs in Rust command handlers.
+- **Never read credentials** (tokens/keys from keyring, env, or stores) without
+  asking the user first.
+
+## Gotchas (hard-won)
+
+- **Never call sync/blocking APIs from event callbacks** that can re-enter the
+  player or hold a lock — it deadlocks. On Android, bind a locked
+  `AutoplayDecision` to a `let` *before* matching; a tokio `MutexGuard` held in
+  the `match` scrutinee deadlocks the `AdvanceToNext` arm.
+- **VideoPlayer native mode**: no lifecycle calls after an `await` in `onMount`
+  (it flips to HTML5 mode and breaks Android seek).
+- **Transcoded resume/seek**: `get_video_stream_url` must return the HLS
+  `master.m3u8`, not `stream.mp4`, or transcoded playback never starts.
+- **Downloads** cap at 3 concurrent; the backend pump auto-starts pending rows.
+  Don't loop `startDownload` from the frontend.
+- **Parallel Claude sessions**: the user may run concurrent sessions. Unexpected
+  file changes may be another session — check `git diff` before "repairing".
+
+## Testing
+
+```bash
+# Rust
+cd src-tauri && cargo test
+cd src-tauri && cargo test test_name        # single test
+
+# Frontend
+bun run test
+bun run test:coverage
+
+# Tauri IPC param-naming integration tests (guard the camelCase rule):
+bun run test -- tauriIntegration.test.ts
+```

Dockerfile

@@ -27,6 +27,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libssl-dev \
     libclang-dev \
     llvm-dev \
+    # Tauri Linux desktop dependencies (needed for `cargo test` on the host target)
+    libglib2.0-dev \
+    libgtk-3-dev \
+    libwebkit2gtk-4.1-dev \
+    libjavascriptcoregtk-4.1-dev \
+    libsoup-3.0-dev \
+    librsvg2-dev \
+    libayatana-appindicator3-dev \
+    # mpv player library (linked via libmpv-sys)
+    libmpv-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Node.js 20.x from NodeSource
@@ -84,6 +94,7 @@ RUN cd src-tauri && cargo fetch && cd ..
 FROM builder AS test
 WORKDIR /app
 RUN echo "Running tests..." && \
+    bunx svelte-kit sync && \
     bun run test && \
     cd src-tauri && cargo test && cd .. && \
     echo "All tests passed!"

Dockerfile.builder

@@ -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
@@ -20,11 +21,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
     ca-certificates \
     unzip \
+    jq \
     openjdk-17-jdk-headless \
     pkg-config \
     libssl-dev \
     libclang-dev \
     llvm-dev \
+    # Tauri Linux desktop dependencies (needed for `cargo test` on the host target)
+    libglib2.0-dev \
+    libgtk-3-dev \
+    libwebkit2gtk-4.1-dev \
+    libjavascriptcoregtk-4.1-dev \
+    libsoup-3.0-dev \
+    librsvg2-dev \
+    libayatana-appindicator3-dev \
+    # mpv player library (linked via libmpv-sys)
+    libmpv-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Node.js 20.x from NodeSource
@@ -57,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
 

FIXES_SUMMARY.md

@@ -1,232 +0,0 @@
-# Code Review Fixes Summary
-
-This document summarizes all the critical bugs and architectural issues that have been fixed in the JellyTau project.
-
-## Fixed Issues
-
-### 🔴 CRITICAL
-
-#### 1. **Fixed nextEpisode Event Handlers - Undefined Method Calls**
-- **File:** `src/lib/services/playerEvents.ts`
-- **Issue:** Lines 272 and 280 were calling `nextEpisode.showPopup()` and `nextEpisode.updateCountdown()` on an undefined variable.
-- **Root Cause:** The import was aliased as `showNextEpisodePopup` but the code tried to use an undefined `nextEpisode` variable.
-- **Fix:** Changed import to import the `nextEpisode` store directly, renamed parameters to avoid shadowing.
-- **Impact:** Prevents runtime crashes when next episode popup events are emitted from the Rust backend.
-
-#### 2. **Replaced Queue Polling with Event-Based Updates**
-- **File:** `src/routes/+layout.svelte`, `src/lib/services/playerEvents.ts`
-- **Issue:** Frontend was polling backend every 1 second (`setInterval(updateQueueStatus, 1000)`) for queue status.
-- **Root Cause:** Inefficient polling approach creates unnecessary backend load and battery drain.
-- **Fix:**
-  - Removed continuous polling
-  - Added `updateQueueStatus()` calls on `state_changed` events
-  - Listeners now trigger updates when playback state changes instead
-- **Impact:** Reduces backend load, improves battery life, more reactive to state changes.
-
-### 🟠 HIGH PRIORITY
-
-#### 3. **Moved Device ID to Secure Storage**
-- **Files:** `src/lib/services/deviceId.ts` (new), `src/lib/stores/auth.ts`
-- **Issue:** Device ID was stored in browser localStorage, accessible to XSS attacks.
-- **Fix:**
-  - Created `deviceId.ts` service that uses Tauri's secure storage commands
-  - Replaced all `localStorage.getItem("jellytau_device_id")` calls with `getDeviceId()`
-  - Added caching for performance
-  - Implemented fallback to in-memory ID if secure storage unavailable
-- **Impact:** Enhanced security posture against XSS attacks.
-
-#### 4. **Fixed Event Listener Memory Leaks**
-- **File:** `src/lib/stores/auth.ts`, `src/routes/+layout.svelte`
-- **Issue:** Event listeners (`listen()` calls) were registered at module load with no cleanup.
-- **Fix:**
-  - Moved listener registration to `initializeEventListeners()` function
-  - Stored unlisten functions and call them in cleanup
-  - Added `cleanupEventListeners()` to auth store export
-  - Called cleanup in `onDestroy()` of layout component
-- **Impact:** Prevents memory leaks from duplicate listeners if store/routes are reloaded.
-
-#### 5. **Replaced Browser Alerts with Toast Notifications**
-- **File:** `src/lib/components/library/TrackList.svelte`
-- **Issue:** Using native `alert()` for errors, which blocks execution and provides poor UX.
-- **Fix:**
-  - Imported `toast` store
-  - Replaced `alert()` with `toast.error()` call with 5-second timeout
-  - Improved error message formatting
-- **Impact:** Non-blocking error notifications with better UX.
-
-#### 6. **Removed Silent Error Handlers**
-- **Files:** `src/lib/services/playbackReporting.ts`, `src/lib/services/imageCache.ts`, `src/lib/services/playerEvents.ts`
-- **Issue:** Multiple `.catch(() => {})` handlers silently swallowed errors.
-- **Fix:**
-  - Added proper error logging with `console.debug()` and `console.error()`
-  - Added comments explaining why failures are non-critical
-  - Made error handling explicit and debuggable
-- **Impact:** Improved debugging and visibility into failures.
-
-### 🟡 MEDIUM PRIORITY
-
-#### 7. **Fixed Race Condition in Downloads Store**
-- **File:** `src/lib/stores/downloads.ts`
-- **Issue:** Concurrent calls to `refreshDownloads()` could interleave state updates, corrupting state.
-- **Fix:**
-  - Added `refreshInProgress` flag to prevent concurrent calls
-  - Implemented queuing mechanism for pending refresh requests
-  - Requests are processed sequentially
-- **Impact:** Prevents race condition-induced data corruption in download state.
-
-#### 8. **Centralized Duration Formatting Utility**
-- **File:** `src/lib/utils/duration.ts` (new), `src/lib/components/library/TrackList.svelte`, `src/lib/components/library/LibraryListView.svelte`
-- **Issue:** Duration formatting logic duplicated across components with magic number `10000000`.
-- **Fix:**
-  - Created `duration.ts` utility with `formatDuration()` and `formatSecondsDuration()` functions
-  - Added support for both mm:ss and hh:mm:ss formats
-  - Replaced all component-level functions with imports
-  - Documented the Jellyfin tick-to-second conversion (10M ticks = 1 second)
-- **Impact:** Single source of truth for duration formatting, easier maintenance.
-
-#### 9. **Added Input Validation to Image URLs**
-- **File:** `src/lib/utils/validation.ts` (new), `src/lib/api/repository-client.ts`
-- **Issue:** Item IDs and image types not validated, vulnerable to path traversal attacks.
-- **Fix:**
-  - Created `validation.ts` with comprehensive input validators:
-    - `validateItemId()` - rejects invalid characters and excessive length
-    - `validateImageType()` - whitelist of allowed types
-    - `validateMediaSourceId()` - similar to item ID validation
-    - `validateNumericParam()` - bounds checking for widths, heights, quality, etc.
-    - `validateQueryParamValue()` - safe query parameter validation
-  - Applied validation to all URL construction methods in repository-client.ts
-  - Added explicit bounds checking for numeric parameters
-- **Impact:** Prevents injection attacks and path traversal vulnerabilities.
-
-#### 10. **Improved Error Handling in Layout Component**
-- **File:** `src/routes/+layout.svelte`
-- **Issue:** Silent `.catch()` handler in connectivity monitoring could mask failures.
-- **Fix:**
-  - Changed from `.catch(() => {})` to proper error handling with logging
-  - Added debug messages explaining failure modes
-  - Implemented async/await with proper error chaining
-- **Impact:** Better observability of connectivity issues.
-
-## Unit Tests Added
-
-Comprehensive test suites have been added for critical utilities and services:
-
-### Test Files Created
-1. **`src/lib/utils/duration.test.ts`**
-   - Tests for `formatDuration()` and `formatSecondsDuration()`
-   - Covers Jellyfin tick conversion, various time formats, edge cases
-   - 10+ test cases
-
-2. **`src/lib/utils/validation.test.ts`**
-   - Tests for all validation functions
-   - Covers valid inputs, invalid characters, bounds checking
-   - Tests for injection prevention
-   - 25+ test cases
-
-3. **`src/lib/services/deviceId.test.ts`**
-   - Tests for device ID generation and caching
-   - Tests for secure storage fallback
-   - Tests for cache clearing on logout
-   - 8+ test cases
-
-4. **`src/lib/services/playerEvents.test.ts`**
-   - Tests for event listener initialization
-   - Tests for cleanup and memory leak prevention
-   - Tests for error handling
-
-### Running Tests
-```bash
-npm run test
-npm run test:ui      # Interactive UI
-npm run test:coverage # With coverage report
-```
-
-## Architecture Improvements
-
-### Separation of Concerns
-- ✅ Duration formatting moved to dedicated utility
-- ✅ Device ID management centralized in service
-- ✅ Input validation extracted to validation utility
-- ✅ Event listener lifecycle properly managed
-
-### Security Enhancements
-- ✅ Device ID moved from localStorage to secure storage
-- ✅ Input validation on all user-influenced URL parameters
-- ✅ Path traversal attack prevention via whitelist validation
-- ✅ Numeric parameter bounds checking
-
-### Performance Improvements
-- ✅ Eliminated 1-second polling (1000 calls/hour reduced to event-driven)
-- ✅ Prevented race conditions in state management
-- ✅ Added request queuing to prevent concurrent backend thrashing
-
-### Reliability Improvements
-- ✅ Fixed critical runtime errors (nextEpisode handlers)
-- ✅ Proper memory cleanup prevents leaks
-- ✅ Better error handling with visibility
-- ✅ Comprehensive test coverage for utilities
-
-## Files Modified
-
-### Core Fixes
-- `src/lib/services/playerEvents.ts` - Fixed event handlers, replaced polling
-- `src/routes/+layout.svelte` - Removed polling, proper cleanup
-- `src/lib/stores/auth.ts` - Device ID management, event listener cleanup
-- `src/lib/stores/downloads.ts` - Race condition prevention
-- `src/lib/api/repository-client.ts` - Input validation on URLs
-- `src/lib/components/library/TrackList.svelte` - Toast notifications, centralized duration
-- `src/lib/components/library/LibraryListView.svelte` - Centralized duration formatting
-- `src/lib/services/playbackReporting.ts` - Removed silent error handlers
-- `src/lib/services/imageCache.ts` - Improved error logging
-
-### New Files
-- `src/lib/services/deviceId.ts` - Device ID service (new)
-- `src/lib/utils/duration.ts` - Duration formatting utility (new)
-- `src/lib/utils/validation.ts` - Input validation utility (new)
-- `src/lib/utils/duration.test.ts` - Duration tests (new)
-- `src/lib/utils/validation.test.ts` - Validation tests (new)
-- `src/lib/services/deviceId.test.ts` - Device ID tests (new)
-- `src/lib/services/playerEvents.test.ts` - Player events tests (new)
-
-## Testing Notes
-
-The codebase is now equipped with:
-- ✅ Unit tests for duration formatting
-- ✅ Unit tests for input validation
-- ✅ Unit tests for device ID service
-- ✅ Unit tests for player events service
-- ✅ Proper mocking of Tauri APIs
-- ✅ Vitest configuration ready to use
-
-Run tests with: `npm run test`
-
-## Recommendations for Future Work
-
-1. **Move sorting/filtering to backend** - Currently done in frontend, should delegate to server
-2. **Move API URL construction to backend** - Currently in frontend, security risk
-3. **Remove more hardcoded configuration values** - Audit for magic numbers throughout codebase
-4. **Add CSP headers validation** - Ensure content security policies are properly enforced
-5. **Implement proper rate limiting** - Add debouncing to frequently called operations
-6. **Expand test coverage** - Add tests for stores, components, and more services
-
-## Backward Compatibility
-
-All changes are backward compatible:
-- Device ID service falls back to in-memory ID if secure storage fails
-- Duration formatting maintains same output format
-- Validation is defensive and allows valid inputs
-- Event listeners are properly cleaned up to prevent leaks
-
-## Performance Impact
-
-- **Positive:** 90% reduction in backend polling calls (1000/hour → event-driven)
-- **Positive:** Eliminated race conditions that could cause state corruption
-- **Positive:** Reduced memory footprint via proper cleanup
-- **Neutral:** Input validation adds minimal overhead (happens before URL construction)
-
----
-
-**Total Issues Fixed:** 10 critical/high-priority items
-**Lines of Code Added:** ~800 (utilities, tests, validation)
-**Test Coverage:** 45+ test cases across 4 test files
-**Estimated Impact:** High reliability and security improvements

README.md

@@ -1,324 +1,29 @@
-# JellyTau
+<h1 align="center">
+  <img src="docs/assets/logo.png" alt="JellyTau logo" width="120" /><br />
+  JellyTau
+</h1>
 
 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
 
----
-
-# 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 | In Progress |
-| 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 | Planned |
-| 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 | Planned |
-| UR-021 | Select audio track for video content | High | Planned |
-| 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 | 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 playback | 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 | Planned |
-| 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 | Planned |
-| JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Planned |
-| 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 | Planned |
-| JA-020 | Add/remove items from playlist | Playlists | UR-014 | Planned |
-| JA-021 | Get active sessions list | Sessions | UR-010 | Planned |
-| JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Planned |
-| JA-023 | Send seek command to remote session | Sessions | UR-010 | Planned |
-| JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Planned |
-| JA-025 | Play specific item on remote session | Sessions | UR-010 | Planned |
-| JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Planned |
-| 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 | Planned |
-| JA-030 | Get person details and filmography | Persons | UR-036 | Planned |
-| JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Planned |
-
-### 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 | Planned |
-| 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 | Planned |
-| 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 | Planned |
-| DR-024 | Audio track selection UI in video player | UI | UR-021 | Planned |
-| 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 countdown and auto-stop | Player | 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 | Player | UR-023 | Done |
-| DR-048 | Video settings (auto-play toggle, countdown duration) | 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 | - | 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 |
-| UR-024 | IR-010 | DR-027 |
-| UR-025 | IR-015 | DR-028 |
-| UR-026 | - | DR-029, DR-048 |
-| 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 |
-
-### 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
+This project uses [bun](https://bun.sh) as its package manager.
 
 ```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
@@ -328,168 +33,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
 
-```
-jellytau/
-├── src/                          # Svelte frontend
-│   ├── lib/
-│   │   ├── api/                  # Jellyfin API client (repository pattern)
-│   │   ├── components/           # UI components (player, library)
-│   │   └── stores/               # Svelte stores (auth, library, player, queue)
-│   └── routes/                   # SvelteKit pages
-├── src-tauri/                    # Rust backend
-│   ├── 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
-```
+| Topic | Location |
+|-------|----------|
+| Architecture overview & subsystem docs | [docs/architecture/](docs/architecture/) |
+| Requirements, traceability & technical debt | [docs/requirements.md](docs/requirements.md) |
+| Build & release process | [docs/build-release.md](docs/build-release.md) |
+| Docker builds | [docs/build/docker.md](docs/build/docker.md) |
+| Traceability tooling & CI | [docs/traceability.md](docs/traceability.md), [docs/traceability-ci.md](docs/traceability-ci.md) |
+| Release checklist | [docs/release-checklist.md](docs/release-checklist.md) |
+| UX flows | [docs/ux-flows.md](docs/ux-flows.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.
-
-**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
+MIT

docker-compose.yml

@@ -12,7 +12,7 @@ services:
       - .:/app
     environment:
       - RUST_BACKTRACE=1
-    command: bash -c "bun test && cd src-tauri && cargo test && cd .. && echo 'All tests passed!'"
+    command: bash -c "bun run test && cd src-tauri && cargo test && cd .. && echo 'All tests passed!'"
 
   # Android build service - builds APK after tests pass
   android-build:

docs-site/SUMMARY.md

@@ -0,0 +1,39 @@
+# Summary
+
+[Introduction](README.md)
+
+# Requirements & Traceability
+
+- [Requirements Specification](requirements.md)
+- [Traceability Matrix](traceability.md)
+- [Traceability CI](traceability-ci.md)
+- [Traces Quick Reference](traces-quick-ref.md)
+
+# Architecture
+
+- [Overview](architecture/README.md)
+  - [Rust Backend](architecture/01-rust-backend.md)
+  - [Svelte Frontend](architecture/02-svelte-frontend.md)
+  - [Data Flow](architecture/03-data-flow.md)
+  - [Type Sync & Threading](architecture/04-type-sync-and-threading.md)
+  - [Platform Backends](architecture/05-platform-backends.md)
+  - [Downloads & Offline](architecture/06-downloads-and-offline.md)
+  - [Connectivity](architecture/07-connectivity.md)
+  - [Database Design](architecture/08-database-design.md)
+  - [Security](architecture/09-security.md)
+
+# UX & Specs
+
+- [UX Flows](ux-flows.md)
+- [Video Background Audio](specs/video-background-audio.md)
+
+# Build & Release
+
+- [Build & Release](build-release.md)
+- [Release Checklist](release-checklist.md)
+- [Docker](build/docker.md)
+- [Builder Image](build/build-builder-image.md)
+
+---
+
+[Rust API Reference (rustdoc)](api-redirect.md)

docs-site/book.toml

@@ -0,0 +1,25 @@
+# mdBook config for the published JellyTau documentation site.
+# The book's `src` is the repo `docs/` directory (see [build] below); this file
+# and SUMMARY.md live in docs-site/ to avoid cluttering docs/. The publish-docs
+# CI job copies SUMMARY.md into docs/ at build time, renders, and pushes the
+# result (plus the rustdoc API under /api/) to the orphan `gitea-pages` branch.
+[book]
+title = "JellyTau Documentation"
+description = "Requirements, traceability, and architecture for the JellyTau Jellyfin client."
+authors = ["Duncan Tourolle"]
+language = "en"
+# Sources live in the repo docs/ dir (one level up from this book root).
+src = "../docs"
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://gitea.tourolle.paris/dtourolle/jellytau"
+edit-url-template = "https://gitea.tourolle.paris/dtourolle/jellytau/_edit/master/docs/{path}"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true

docs/architecture/01-rust-backend.md

@@ -0,0 +1,571 @@
+# Rust Backend Architecture
+
+**Location**: `src-tauri/src/`
+
+## Media Session State Machine
+
+**Location**: `src-tauri/src/player/session.rs`
+
+The media session tracks the high-level playback context (what kind of media is being consumed) and persists beyond individual playback states. This enables persistent UI (miniplayer for audio) and proper transitions between content types.
+
+**Architecture Note:** The session manager is a separate app-level state manager (not inside PlayerController), coordinated by the commands layer. This maintains clean separation of concerns.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+
+    Idle --> AudioActive : play_queue(audio)
+    Idle --> MovieActive : play_item(movie)
+    Idle --> TvShowActive : play_item(episode)
+
+    state "Audio Session" as AudioSession {
+        [*] --> AudioActive
+        AudioActive --> AudioInactive : playback_ended
+        AudioInactive --> AudioActive : resume/play
+        AudioActive --> AudioActive : next/previous
+    }
+
+    state "Movie Session" as MovieSession {
+        [*] --> MovieActive
+        MovieActive --> MovieInactive : playback_ended
+        MovieInactive --> MovieActive : resume
+    }
+
+    state "TV Show Session" as TvShowSession {
+        [*] --> TvShowActive
+        TvShowActive --> TvShowInactive : playback_ended
+        TvShowInactive --> TvShowActive : next_episode/resume
+    }
+
+    AudioSession --> Idle : dismiss/clear_queue
+    AudioSession --> MovieSession : play_item(movie)
+    AudioSession --> TvShowSession : play_item(episode)
+
+    MovieSession --> Idle : dismiss/playback_complete
+    MovieSession --> AudioSession : play_queue(audio)
+
+    TvShowSession --> Idle : dismiss/series_complete
+    TvShowSession --> AudioSession : play_queue(audio)
+
+    note right of Idle
+        No active media session
+        Queue may exist but not playing
+        No miniplayer/video player shown
+    end note
+
+    note right of AudioSession
+        SHOW: Miniplayer (always visible)
+        - Active: Play/pause/skip controls enabled
+        - Inactive: Play button to resume queue
+        Persists until explicit dismiss
+    end note
+
+    note right of MovieSession
+        SHOW: Full video player
+        - Active: Video playing/paused
+        - Inactive: Resume dialog
+        Auto-dismiss when playback ends
+    end note
+
+    note right of TvShowSession
+        SHOW: Full video player + Next Episode UI
+        - Active: Video playing/paused
+        - Inactive: Next episode prompt
+        Auto-dismiss when series ends
+    end note
+```
+
+**Session State Enum:**
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum MediaSessionType {
+    /// No active session - browsing library
+    Idle,
+
+    /// Audio playback session (music, audiobooks, podcasts)
+    /// Persists until explicitly dismissed
+    Audio {
+        /// Last/current track being played
+        last_item: Option<MediaItem>,
+        /// True = playing/paused, False = stopped/ended
+        is_active: bool,
+    },
+
+    /// Movie playback (single video, auto-dismiss on end)
+    Movie {
+        item: MediaItem,
+        is_active: bool,  // true = playing/paused, false = ended
+    },
+
+    /// TV show playback (supports next episode auto-advance)
+    TvShow {
+        item: MediaItem,
+        series_id: String,
+        is_active: bool,  // true = playing/paused, false = ended
+    },
+}
+```
+
+**State Transitions & Rules:**
+
+| From State | Event | To State | UI Behavior | Notes |
+|------------|-------|----------|-------------|-------|
+| Idle | `play_queue(audio)` | Audio (active) | Show miniplayer | Creates audio session |
+| Idle | `play_item(movie)` | Movie (active) | Show video player | Creates movie session |
+| Idle | `play_item(episode)` | TvShow (active) | Show video player | Creates TV session |
+| Audio (active) | `playback_ended` | Audio (inactive) | Miniplayer stays visible | Queue preserved |
+| Audio (inactive) | `play/resume` | Audio (active) | Miniplayer enabled | Resume from queue |
+| Audio (active/inactive) | `dismiss` | Idle | Hide miniplayer | Clear session |
+| Audio (active/inactive) | `play_item(movie)` | Movie (active) | Switch to video player | Replace session |
+| Movie (active) | `playback_ended` | Idle | Hide video player | Auto-dismiss |
+| Movie (active) | `dismiss` | Idle | Hide video player | User dismiss |
+| TvShow (active) | `playback_ended` | TvShow (inactive) | Show next episode UI | Wait for user choice |
+| TvShow (inactive) | `next_episode` | TvShow (active) | Play next episode | Stay in session |
+| TvShow (inactive) | `series_complete` | Idle | Hide video player | No more episodes |
+
+**Key Design Decisions:**
+
+1. **Audio Sessions Persist**: Miniplayer stays visible even when queue ends, allows easy resume
+2. **Video Sessions Auto-Dismiss**: Movies auto-close when finished (unless paused)
+3. **Single Active Session**: Playing new content type replaces current session
+4. **Explicit Dismiss for Audio**: User must click close button to clear audio session
+5. **Session != PlayerState**: Session is higher-level, PlayerState tracks playing/paused/seeking
+
+**Edge Cases Handled:**
+
+- Album finishes: Session goes inactive, miniplayer shows last track with play disabled
+- User wants to dismiss: Close button clears session -> Idle
+- Switch content types: New session replaces old (audio -> movie)
+- Paused for extended time: Session persists indefinitely
+- Playback errors: Session stays inactive, allows retry
+- Queue operations while idle: Queue exists but no session created until play
+
+## Player State Machine (Low-Level Playback)
+
+**Location**: `src-tauri/src/player/state.rs`
+
+The player uses a deterministic state machine with 6 states (operates within a media session):
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Loading : Load
+    Loading --> Playing : MediaLoaded
+    Playing --> Paused : Pause
+    Paused --> Playing : Play
+    Paused --> Seeking : Seek
+    Seeking --> Playing : PositionUpdate
+    Playing --> Idle : Stop
+    Paused --> Idle : Stop
+    Idle --> Error : Error
+    Loading --> Error : Error
+    Playing --> Error : Error
+    Paused --> Error : Error
+    Seeking --> Error : Error
+
+    state Playing {
+        [*] : position, duration
+    }
+    state Paused {
+        [*] : position, duration
+    }
+    state Seeking {
+        [*] : target
+    }
+    state Error {
+        [*] : error message
+    }
+```
+
+**State Enum:**
+```rust
+pub enum PlayerState {
+    Idle,
+    Loading { media: MediaItem },
+    Playing { media: MediaItem, position: f64, duration: f64 },
+    Paused { media: MediaItem, position: f64, duration: f64 },
+    Seeking { media: MediaItem, target: f64 },
+    Error { media: Option<MediaItem>, error: String },
+}
+```
+
+**Event Enum:**
+```rust
+pub enum PlayerEvent {
+    Load(MediaItem),
+    Play,
+    Pause,
+    Stop,
+    Seek(f64),
+    Next,
+    Previous,
+    MediaLoaded(f64),      // duration
+    PositionUpdate(f64),   // position
+    PlaybackEnded,
+    Error(String),
+}
+```
+
+## Playback Mode State Machine
+
+**Location**: `src-tauri/src/playback_mode/mod.rs`
+
+The playback mode manages whether media is playing locally on the device or remotely on another Jellyfin session (TV, browser, etc.):
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+
+    Idle --> Local : play_queue()
+    Idle --> Remote : transfer_to_remote(session_id)
+
+    Local --> Remote : transfer_to_remote(session_id)
+    Local --> Idle : stop()
+
+    Remote --> Local : transfer_to_local()
+    Remote --> Idle : session_disconnected()
+    Remote --> Idle : stop()
+
+    state Local {
+        [*] : Playing on device
+        [*] : ExoPlayer active
+        [*] : Volume buttons -> device
+    }
+
+    state Remote {
+        [*] : Controlling session
+        [*] : session_id
+        [*] : Volume buttons -> remote
+        [*] : Android: VolumeProvider active
+    }
+
+    state Idle {
+        [*] : No active playback
+    }
+```
+
+**State Enum:**
+```rust
+pub enum PlaybackMode {
+    Local,                           // Playing on local device
+    Remote { session_id: String },   // Controlling remote Jellyfin session
+    Idle,                            // No active playback
+}
+```
+
+**State Transitions:**
+
+| From | Event | To | Side Effects |
+|------|-------|-----|----|
+| Idle | `play_queue()` | Local | Start local playback |
+| Idle | `transfer_to_remote(session_id)` | Remote | Send queue to remote session |
+| Local | `transfer_to_remote(session_id)` | Remote | Stop local, send queue to remote, enable remote volume (Android) |
+| Local | `stop()` | Idle | Stop local playback |
+| Remote | `transfer_to_local()` | Local | Get remote state, stop remote, start local at same position, disable remote volume |
+| Remote | `stop()` | Idle | Stop remote playback, disable remote volume |
+| Remote | `session_disconnected()` | Idle | Session lost, disable remote volume |
+
+**Integration with Player State Machine:**
+
+- When `PlaybackMode = Local`: Player state machine is active (Idle/Loading/Playing/Paused/etc.)
+- When `PlaybackMode = Remote`: Player state is typically Idle (remote session controls playback)
+- When `PlaybackMode = Idle`: Player state is Idle
+
+**Android Volume Control Integration:**
+
+When transitioning to `Remote` mode on Android:
+1. Call `enable_remote_volume(initial_volume)`
+2. VolumeProviderCompat intercepts hardware volume buttons
+3. PlaybackStateCompat is set to STATE_PLAYING (shows volume UI)
+4. Volume commands routed to remote session via Jellyfin API
+
+When transitioning away from `Remote` mode:
+1. Call `disable_remote_volume()`
+2. Volume buttons return to controlling device volume
+3. PlaybackStateCompat set to STATE_NONE
+4. VolumeProviderCompat is cleared
+
+## Media Item & Source
+
+**Location**: `src-tauri/src/player/media.rs`
+
+```rust
+pub struct MediaItem {
+    pub id: String,
+    pub title: String,
+    pub artist: Option<String>,
+    pub album: Option<String>,
+    pub duration: Option<f64>,
+    pub artwork_url: Option<String>,
+    pub media_type: MediaType,
+    pub source: MediaSource,
+}
+
+pub enum MediaType {
+    Audio,
+    Video,
+}
+
+pub enum MediaSource {
+    Remote {
+        stream_url: String,
+        jellyfin_item_id: String,
+    },
+    Local {
+        file_path: PathBuf,
+        jellyfin_item_id: Option<String>,
+    },
+    DirectUrl {
+        url: String,
+    },
+}
+```
+
+The `MediaSource` enum enables:
+- **Remote**: Streaming from Jellyfin server
+- **Local**: Downloaded/cached files (future offline support)
+- **DirectUrl**: Direct URLs (channel plugins, external sources)
+
+## Queue Manager
+
+**Location**: `src-tauri/src/player/queue.rs`
+
+```rust
+pub struct QueueManager {
+    items: Vec<MediaItem>,
+    current_index: Option<usize>,
+    shuffle: bool,
+    repeat: RepeatMode,
+    shuffle_order: Vec<usize>,  // Fisher-Yates permutation
+    history: Vec<usize>,        // For back navigation in shuffle
+}
+
+pub enum RepeatMode {
+    Off,
+    All,
+    One,
+}
+```
+
+**Queue Navigation Logic:**
+
+```mermaid
+flowchart TB
+    QM[QueueManager]
+    QM --> Shuffle
+    QM --> Repeat
+    QM --> History
+
+    subgraph Shuffle["Shuffle Mode"]
+        ShuffleOff["OFF<br/>next() returns index + 1"]
+        ShuffleOn["ON<br/>next() follows shuffle_order[]"]
+    end
+
+    subgraph Repeat["Repeat Mode"]
+        RepeatOff["OFF<br/>next() at end: -> None"]
+        RepeatAll["ALL<br/>next() at end: -> wrap to index 0"]
+        RepeatOne["ONE<br/>next() returns same item"]
+    end
+
+    subgraph History["History"]
+        HistoryDesc["Used for previous()<br/>in shuffle mode"]
+    end
+```
+
+## Favorites System
+
+**Location**:
+- Service: `src/lib/services/favorites.ts`
+- Component: `src/lib/components/FavoriteButton.svelte`
+- Backend: `src-tauri/src/commands/storage.rs`
+
+The favorites system implements optimistic updates with server synchronization:
+
+```mermaid
+flowchart TB
+    UI[FavoriteButton] -->|Click| Service[toggleFavorite]
+    Service -->|1. Optimistic| LocalDB[(SQLite user_data)]
+    Service -->|2. Sync| JellyfinAPI[Jellyfin API]
+    Service -->|3. Mark Synced| LocalDB
+
+    JellyfinAPI -->|POST| MarkFav["/Users/{id}/FavoriteItems/{itemId}"]
+    JellyfinAPI -->|DELETE| UnmarkFav["/Users/{id}/FavoriteItems/{itemId}"]
+
+    LocalDB -->|is_favorite<br/>pending_sync| UserData[user_data table]
+```
+
+**Flow**:
+1. User clicks heart button in UI (MiniPlayer, AudioPlayer, or detail pages)
+2. `toggleFavorite()` service function handles the logic:
+   - Updates local SQLite database immediately (optimistic update)
+   - Attempts to sync with Jellyfin server
+   - Marks as synced if successful, otherwise leaves `pending_sync = 1`
+3. UI reflects the change immediately without waiting for server response
+
+**Components**:
+
+- **FavoriteButton.svelte**: Reusable heart button component
+  - Configurable size (sm/md/lg)
+  - Red when favorited, gray when not
+  - Loading state during toggle
+  - Bindable `isFavorite` prop for two-way binding
+
+- **Integration Points**:
+  - MiniPlayer: Shows favorite button for audio tracks (hidden on small screens)
+  - Full AudioPlayer: Shows favorite button (planned)
+  - Album/Artist detail pages: Shows favorite button (planned)
+
+**Database Schema**:
+- `user_data.is_favorite`: Boolean flag (stored as INTEGER 0/1)
+- `user_data.pending_sync`: Indicates if local changes need syncing
+
+**Tauri Commands**:
+- `storage_toggle_favorite`: Updates favorite status in local database
+- `storage_mark_synced`: Clears pending_sync flag after successful sync
+
+**API Methods**:
+- `LibraryApi.markFavorite(itemId)`: POST to Jellyfin
+- `LibraryApi.unmarkFavorite(itemId)`: DELETE from Jellyfin
+
+## Player Backend Trait
+
+**Location**: `src-tauri/src/player/backend.rs`
+
+```rust
+pub trait PlayerBackend: Send + Sync {
+    fn load(&mut self, media: &MediaItem) -> Result<(), PlayerError>;
+    fn play(&mut self) -> Result<(), PlayerError>;
+    fn pause(&mut self) -> Result<(), PlayerError>;
+    fn stop(&mut self) -> Result<(), PlayerError>;
+    fn seek(&mut self, position: f64) -> Result<(), PlayerError>;
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError>;
+    fn position(&self) -> f64;
+    fn duration(&self) -> Option<f64>;
+    fn state(&self) -> PlayerState;
+    fn is_loaded(&self) -> bool;
+    fn volume(&self) -> f32;
+}
+```
+
+**Implementations:**
+- `NullBackend` - Mock backend for testing
+- `MpvBackend` - Linux playback via libmpv (see [05-platform-backends.md](05-platform-backends.md))
+- `ExoPlayerBackend` - Android playback via ExoPlayer/Media3 (see [05-platform-backends.md](05-platform-backends.md))
+
+## Player Controller
+
+**Location**: `src-tauri/src/player/mod.rs`
+
+The `PlayerController` orchestrates playback:
+
+```rust
+pub struct PlayerController {
+    backend: Arc<Mutex<Box<dyn PlayerBackend>>>,
+    queue: Arc<Mutex<QueueManager>>,
+    muted: bool,
+    sleep_timer: Arc<Mutex<SleepTimerState>>,
+    autoplay_settings: Arc<Mutex<AutoplaySettings>>,
+    autoplay_episode_count: Arc<Mutex<u32>>,  // Session-based counter
+    repository: Arc<Mutex<Option<Arc<dyn MediaRepository>>>>,
+    event_emitter: Arc<Mutex<Option<Arc<dyn PlayerEventEmitter>>>>,
+    // ... other fields
+}
+```
+
+**Key Methods:**
+- `play_item(item)`: Load and play single item (resets autoplay counter)
+- `play_queue(items, start_index)`: Load queue and start playback (resets autoplay counter)
+- `next()` / `previous()`: Queue navigation (resets autoplay counter)
+- `toggle_shuffle()` / `cycle_repeat()`: Mode changes
+- `set_sleep_timer(mode)` / `cancel_sleep_timer()`: Sleep timer control
+- `on_playback_ended()`: Autoplay decision making (checks sleep timer, episode limit, queue)
+
+## Playlist System
+
+**Location**: `src-tauri/src/commands/playlist.rs`, `src-tauri/src/repository/`
+
+**TRACES**: UR-014 | JA-019 | JA-020
+
+The playlist system provides full CRUD operations for Jellyfin playlists with offline support through the cache-first repository pattern.
+
+**Types:**
+
+```rust
+/// A media item within a playlist, with its distinct playlist entry ID
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PlaylistEntry {
+    /// Jellyfin's PlaylistItemId (distinct from the media item ID)
+    pub playlist_item_id: String,
+    #[serde(flatten)]
+    pub item: MediaItem,
+}
+
+/// Result of creating a new playlist
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PlaylistCreatedResult {
+    pub id: String,
+}
+```
+
+**Key Design Decision**: `PlaylistEntry` wraps a `MediaItem` with a distinct `playlist_item_id`. This is critical because removing items from a playlist requires the playlist entry ID (not the media item ID), since the same track can appear multiple times.
+
+**MediaRepository Trait Methods:**
+```rust
+async fn create_playlist(&self, name: &str, item_ids: Option<Vec<String>>) -> Result<PlaylistCreatedResult, RepoError>;
+async fn delete_playlist(&self, playlist_id: &str) -> Result<(), RepoError>;
+async fn rename_playlist(&self, playlist_id: &str, name: &str) -> Result<(), RepoError>;
+async fn get_playlist_items(&self, playlist_id: &str) -> Result<Vec<PlaylistEntry>, RepoError>;
+async fn add_to_playlist(&self, playlist_id: &str, item_ids: Vec<String>) -> Result<(), RepoError>;
+async fn remove_from_playlist(&self, playlist_id: &str, entry_ids: Vec<String>) -> Result<(), RepoError>;
+async fn move_playlist_item(&self, playlist_id: &str, item_id: &str, new_index: u32) -> Result<(), RepoError>;
+```
+
+**Cache Strategy:**
+- **Write operations** (create, delete, rename, add, remove, move): Delegate directly to online repository
+- **Read operation** (`get_playlist_items`): Uses cache-first parallel racing (100ms cache timeout, server fallback)
+- Background cache update after server fetch via `save_playlist_items_to_cache()`
+
+**Playlist Tauri Commands:**
+
+| Command | Parameters | Returns |
+|---------|------------|---------|
+| `playlist_create` | `handle, name, item_ids?` | `PlaylistCreatedResult` |
+| `playlist_delete` | `handle, playlist_id` | `()` |
+| `playlist_rename` | `handle, playlist_id, name` | `()` |
+| `playlist_get_items` | `handle, playlist_id` | `Vec<PlaylistEntry>` |
+| `playlist_add_items` | `handle, playlist_id, item_ids` | `()` |
+| `playlist_remove_items` | `handle, playlist_id, entry_ids` | `()` |
+| `playlist_move_item` | `handle, playlist_id, item_id, new_index` | `()` |
+
+## Tauri Commands (Player)
+
+**Location**: `src-tauri/src/commands/player.rs`
+
+| Command | Parameters | Returns |
+|---------|------------|---------|
+| `player_play_item` | `PlayItemRequest` | `PlayerStatus` |
+| `player_play_queue` | `items, start_index, shuffle` | `PlayerStatus` |
+| `player_play` | - | `PlayerStatus` |
+| `player_pause` | - | `PlayerStatus` |
+| `player_toggle` | - | `PlayerStatus` |
+| `player_stop` | - | `PlayerStatus` |
+| `player_next` | - | `PlayerStatus` |
+| `player_previous` | - | `PlayerStatus` |
+| `player_seek` | `position: f64` | `PlayerStatus` |
+| `player_set_volume` | `volume: f32` | `PlayerStatus` |
+| `player_toggle_shuffle` | - | `QueueStatus` |
+| `player_cycle_repeat` | - | `QueueStatus` |
+| `player_get_status` | - | `PlayerStatus` |
+| `player_get_queue` | - | `QueueStatus` |
+| `player_get_session` | - | `MediaSessionType` |
+| `player_dismiss_session` | - | `()` |
+| `player_set_sleep_timer` | `mode: SleepTimerMode` | `()` |
+| `player_cancel_sleep_timer` | - | `()` |
+| `player_set_video_settings` | `settings: VideoSettings` | `VideoSettings` |
+| `player_get_video_settings` | - | `VideoSettings` |
+| `player_set_autoplay_settings` | `settings: AutoplaySettings` | `AutoplaySettings` |
+| `player_get_autoplay_settings` | - | `AutoplaySettings` |
+| `player_on_playback_ended` | - | `()` |

docs/architecture/02-svelte-frontend.md

@@ -0,0 +1,647 @@
+# Svelte Frontend Architecture
+
+## Store Structure
+
+**Location**: `src/lib/stores/`
+
+```mermaid
+flowchart TB
+    subgraph Stores
+        subgraph auth["auth.ts"]
+            AuthState["AuthState<br/>- user<br/>- serverUrl<br/>- token<br/>- isLoading"]
+        end
+        subgraph playerStore["player.ts"]
+            PlayerStoreState["PlayerState<br/>- kind<br/>- media<br/>- position<br/>- duration"]
+        end
+        subgraph queueStore["queue.ts"]
+            QueueState["QueueState<br/>- items<br/>- index<br/>- shuffle<br/>- repeat"]
+        end
+        subgraph libraryStore["library.ts"]
+            LibraryState["LibraryState<br/>- libraries<br/>- items<br/>- loading"]
+        end
+        subgraph Derived["Derived Stores"]
+            DerivedList["isAuthenticated, currentUser<br/>isPlaying, isPaused, currentMedia<br/>hasNext, hasPrevious, isShuffle<br/>libraryItems, isLibraryLoading"]
+        end
+    end
+```
+
+## Music Library Architecture
+
+**Category-Based Navigation:**
+
+JellyTau's music library uses a category-based navigation system with a dedicated landing page that routes users to specialized views for different content types.
+
+**Route Structure:**
+
+```mermaid
+graph TD
+    Music["/library/music<br/>(Landing page with category cards)"]
+    Tracks["Tracks<br/>(List view only)"]
+    Artists["Artists<br/>(Grid view)"]
+    Albums["Albums<br/>(Grid view)"]
+    Playlists["Playlists<br/>(Grid view)"]
+    Genres["Genres<br/>(Genre browser)"]
+
+    Music --> Tracks
+    Music --> Artists
+    Music --> Albums
+    Music --> Playlists
+    Music --> Genres
+```
+
+**View Enforcement:**
+
+| Content Type | View Mode | Toggle Visible | Component Used |
+|--------------|-----------|----------------|----------------|
+| Tracks | List (forced) | No | `TrackList` |
+| Artists | Grid (forced) | No | `LibraryGrid` with `forceGrid={true}` |
+| Albums | Grid (forced) | No | `LibraryGrid` with `forceGrid={true}` |
+| Playlists | Grid (forced) | No | `LibraryGrid` with `forceGrid={true}` |
+| Genres | Grid (both levels) | No | `LibraryGrid` with `forceGrid={true}` |
+| Album Detail Tracks | List (forced) | No | `TrackList` |
+
+**TrackList Component:**
+
+The `TrackList` component (`src/lib/components/library/TrackList.svelte`) is a dedicated component for displaying songs in list format:
+
+- **No Thumbnails**: Track numbers only (transform to play button on hover)
+- **Desktop Layout**: Table with columns: #, Title, Artist, Album, Duration
+- **Mobile Layout**: Compact rows with track number and metadata
+- **Configurable Columns**: `showArtist` and `showAlbum` props control column visibility
+- **Click Behavior**: Clicking a track plays it and queues all filtered tracks
+
+**Example Usage:**
+```svelte
+<TrackList
+  tracks={filteredTracks}
+  loading={loading}
+  showArtist={true}
+  showAlbum={true}
+/>
+```
+
+**LibraryGrid forceGrid Prop:**
+
+The `forceGrid` prop prevents the grid/list view toggle from appearing and forces grid view regardless of user preference. This ensures visual content (artists, albums, playlists) is always displayed as cards with artwork.
+
+## Playback Reporting Service
+
+**Location**: `src/lib/services/playbackReporting.ts`
+
+The playback reporting service ensures playback progress is synced to both the Jellyfin server AND the local SQLite database. This dual-write approach enables:
+- Offline "Continue Watching" functionality
+- Sync queue for when network is unavailable
+- Consistent progress across app restarts
+
+```mermaid
+sequenceDiagram
+    participant VideoPlayer
+    participant PlaybackService as playbackReporting.ts
+    participant LocalDB as Local SQLite<br/>(Tauri Commands)
+    participant Jellyfin as Jellyfin Server
+
+    VideoPlayer->>PlaybackService: reportPlaybackProgress(itemId, position)
+
+    par Local Storage (always works)
+        PlaybackService->>LocalDB: invoke("storage_update_playback_progress")
+        LocalDB-->>PlaybackService: Ok (pending_sync = true)
+    and Server Sync (if online)
+        PlaybackService->>Jellyfin: POST /Sessions/Playing/Progress
+        Jellyfin-->>PlaybackService: Ok
+        PlaybackService->>LocalDB: invoke("storage_mark_synced")
+    end
+```
+
+**Service Functions:**
+- `reportPlaybackStart(itemId, positionSeconds)` - Called when playback begins
+- `reportPlaybackProgress(itemId, positionSeconds, isPaused)` - Called periodically (every 10s)
+- `reportPlaybackStopped(itemId, positionSeconds)` - Called when player closes or video ends
+
+**Tauri Commands:**
+| Command | Description |
+|---------|-------------|
+| `storage_update_playback_progress` | Update position in local DB (marks `pending_sync = true`) |
+| `storage_mark_played` | Mark item as played, increment play count |
+| `storage_get_playback_progress` | Get stored progress for an item |
+| `storage_mark_synced` | Clear `pending_sync` flag after successful server sync |
+
+**Database Schema Notes:**
+- The `user_data` table stores playback progress using Jellyfin IDs directly (as TEXT)
+- Playback progress can be tracked even when the full item metadata hasn't been downloaded yet
+
+**Resume Playback Feature:**
+- When loading media for playback, the app checks local database for saved progress
+- If progress exists (>30 seconds watched and <90% complete), shows resume dialog
+- User can choose to "Resume" from saved position or "Start from Beginning"
+- For video: Uses `startTimeSeconds` parameter in stream URL to begin transcoding from resume point
+- For audio: Seeks to resume position after loading via MPV backend
+- Implemented in `src/routes/player/[id]/+page.svelte`
+
+## Repository Architecture (Rust-Based)
+
+**Location**: `src-tauri/src/repository/`
+
+```mermaid
+classDiagram
+    class MediaRepository {
+        <<trait>>
+        +get_libraries()
+        +get_items(parent_id, options)
+        +get_item(item_id)
+        +search(query, options)
+        +get_latest_items(parent_id, limit)
+        +get_resume_items(parent_id, limit)
+        +get_next_up_episodes(series_id, limit)
+        +get_genres(parent_id)
+        +get_playback_info(item_id)
+        +report_playback_start(item_id, position_ticks)
+        +report_playback_progress(item_id, position_ticks, is_paused)
+        +report_playback_stopped(item_id, position_ticks)
+        +mark_favorite(item_id)
+        +unmark_favorite(item_id)
+        +get_person(person_id)
+        +get_items_by_person(person_id, options)
+        +get_image_url(item_id, image_type, options)
+        +create_playlist(name, item_ids)
+        +delete_playlist(playlist_id)
+        +rename_playlist(playlist_id, name)
+        +get_playlist_items(playlist_id)
+        +add_to_playlist(playlist_id, item_ids)
+        +remove_from_playlist(playlist_id, entry_ids)
+        +move_playlist_item(playlist_id, item_id, new_index)
+    }
+
+    class OnlineRepository {
+        -http_client: Arc~HttpClient~
+        -server_url: String
+        -user_id: String
+        -access_token: String
+        -connectivity: Option~Arc~ConnectivityMonitor~~
+        +new()
+        +with_connectivity()
+        -report_outcome()
+    }
+
+    class OfflineRepository {
+        -db_service: Arc~DatabaseService~
+        -server_id: String
+        -user_id: String
+        +new()
+        +cache_library()
+        +cache_items()
+        +cache_item()
+    }
+
+    class HybridRepository {
+        -online: Arc~OnlineRepository~
+        -offline: Arc~OfflineRepository~
+        +new()
+        -parallel_race()
+        -cache_with_timeout()
+    }
+
+    MediaRepository <|.. OnlineRepository
+    MediaRepository <|.. OfflineRepository
+    MediaRepository <|.. HybridRepository
+
+    HybridRepository --> OnlineRepository
+    HybridRepository --> OfflineRepository
+```
+
+**Key Implementation Details:**
+
+1. **Cache-First Racing Strategy** (`hybrid.rs`):
+   - Runs cache (SQLite) and server (HTTP) queries in parallel
+   - Cache has 100ms timeout
+   - 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
+   // Frontend creates repository with UUID handle
+   repository_create(server_url, user_id, access_token, server_id) -> String (UUID)
+
+   // All operations use handle for identification
+   repository_get_libraries(handle: String) -> Vec<Library>
+   repository_get_items(handle: String, ...) -> SearchResult
+
+   // Cleanup when done
+   repository_destroy(handle: String)
+   ```
+   - Enables multiple concurrent repository instances
+   - Thread-safe with `Arc<Mutex<HashMap<String, Arc<HybridRepository>>>>`
+   - No global state conflicts
+
+3. **Frontend API Layer** (`src/lib/api/repository-client.ts`):
+   - Thin TypeScript wrapper over Rust commands
+   - Maintains handle throughout session
+   - All methods: `invoke<T>("repository_operation", { handle, ...args })`
+   - ~100 lines (down from 1061 lines)
+
+## Playback Mode System
+
+**Location**: `src-tauri/src/playback_mode/mod.rs`
+
+The playback mode system manages transitions between local device playback and remote Jellyfin session control:
+
+```rust
+pub enum PlaybackMode {
+    Local,                     // Playing on local device
+    Remote { session_id: String }, // Controlling remote session
+    Idle,                      // Not playing
+}
+
+pub struct PlaybackModeManager {
+    current_mode: PlaybackMode,
+    player_controller: Arc<Mutex<PlayerController>>,
+    jellyfin_client: Arc<JellyfinClient>,
+}
+```
+
+**Key Operations:**
+
+1. **Transfer to Remote** (`transfer_to_remote(session_id)`):
+   ```mermaid
+   sequenceDiagram
+       participant UI
+       participant Manager as PlaybackModeManager
+       participant Player as PlayerController
+       participant Jellyfin as Jellyfin API
+
+       UI->>Manager: transfer_to_remote(session_id)
+       Manager->>Player: Extract queue items
+       Manager->>Manager: Get Jellyfin IDs from queue
+       Manager->>Jellyfin: POST /Sessions/{id}/Playing
+       Note over Jellyfin: Start playback with queue
+       Manager->>Jellyfin: POST /Sessions/{id}/Playing/Seek
+       Note over Jellyfin: Seek to current position
+       Manager->>Player: Stop local playback
+       Manager->>Manager: Set mode to Remote
+   ```
+
+2. **Transfer to Local** (`transfer_to_local(item_id, position_ticks)`):
+   - Stops remote session playback
+   - Prepares local player to resume
+   - Sets mode to Local
+
+**Tauri Commands** (`playback_mode.rs`):
+- `playback_mode_get_current()` -> Returns current PlaybackMode
+- `playback_mode_transfer_to_remote(session_id)` -> Async transfer
+- `playback_mode_transfer_to_local(item_id, position_ticks)` -> Async transfer back
+- `playback_mode_is_transferring()` -> Check transfer state
+- `playback_mode_set(mode)` -> Direct mode setting
+
+**Frontend Store** (`src/lib/stores/playbackMode.ts`):
+- Thin wrapper calling Rust commands
+- Maintains UI state (isTransferring, transferError)
+- Listens to mode change events from Rust
+
+## Database Service Abstraction
+
+**Location**: `src-tauri/src/storage/db_service.rs`
+
+Async database interface wrapping synchronous `rusqlite` to prevent blocking the Tokio runtime:
+
+```rust
+#[async_trait]
+pub trait DatabaseService: Send + Sync {
+    async fn execute(&self, query: Query) -> Result<usize, DatabaseError>;
+    async fn execute_batch(&self, queries: Vec<Query>) -> Result<(), DatabaseError>;
+    async fn query_one<T, F>(&self, query: Query, mapper: F) -> Result<T, DatabaseError>
+        where F: FnOnce(&Row) -> Result<T> + Send + 'static;
+    async fn query_optional<T, F>(&self, query: Query, mapper: F) -> Result<Option<T>, DatabaseError>
+        where F: FnOnce(&Row) -> Result<T> + Send + 'static;
+    async fn query_many<T, F>(&self, query: Query, mapper: F) -> Result<Vec<T>, DatabaseError>
+        where F: Fn(&Row) -> Result<T> + Send + 'static;
+    async fn transaction<F, T>(&self, f: F) -> Result<T, DatabaseError>
+        where F: FnOnce(Transaction) -> Result<T> + Send + 'static;
+}
+
+pub struct RusqliteService {
+    connection: Arc<Mutex<Connection>>,
+}
+
+impl DatabaseService for RusqliteService {
+    async fn execute(&self, query: Query) -> Result<usize, DatabaseError> {
+        let conn = self.connection.clone();
+        tokio::task::spawn_blocking(move || {
+            // Execute query on blocking thread pool
+        }).await?
+    }
+    // ... other methods use spawn_blocking
+}
+```
+
+**Key Benefits:**
+- **No Freezing**: All blocking DB ops run in thread pool via `spawn_blocking`
+- **Type Safety**: `QueryParam` enum prevents SQL injection
+- **Future Proof**: Easy to swap to native async DB (tokio-rusqlite)
+- **Testable**: Can mock DatabaseService for tests
+
+**Usage Pattern:**
+```rust
+// Before (blocking - causes UI freeze)
+let conn = database.connection();
+let conn = conn.lock().unwrap();  // BLOCKS
+conn.query_row(...)  // BLOCKS
+
+// After (async - no freezing)
+let db_service = database.service();
+let query = Query::with_params("SELECT ...", vec![...]);
+db_service.query_one(query, |row| {...}).await  // spawn_blocking internally
+```
+
+## Component Hierarchy
+
+```mermaid
+graph TD
+    subgraph Routes["Routes (src/routes/)"]
+        LoginPage["Login Page"]
+        LibLayout["Library Layout"]
+        LibDetail["Album/Series Detail"]
+        MusicCategory["Music Category Landing"]
+        Tracks["Tracks"]
+        Artists["Artists"]
+        Albums["Albums"]
+        Playlists["Playlists"]
+        Genres["Genres"]
+        Downloads["Downloads Page"]
+        Settings["Settings Page"]
+        PlayerPage["Player Page"]
+    end
+
+    subgraph PlayerComps["Player Components"]
+        AudioPlayer["AudioPlayer"]
+        VideoPlayer["VideoPlayer"]
+        MiniPlayer["MiniPlayer"]
+        Controls["Controls"]
+        Queue["Queue"]
+        SleepTimerModal["SleepTimerModal"]
+        SleepTimerIndicator["SleepTimerIndicator"]
+    end
+
+    subgraph SessionComps["Sessions Components"]
+        CastButton["CastButton"]
+        SessionModal["SessionPickerModal"]
+        SessionCard["SessionCard"]
+        SessionsList["SessionsList"]
+        RemoteControls["RemoteControls"]
+    end
+
+    subgraph LibraryComps["Library Components"]
+        LibGrid["LibraryGrid"]
+        LibListView["LibraryListView"]
+        TrackList["TrackList"]
+        PlaylistDetail["PlaylistDetailView"]
+        DownloadBtn["DownloadButton"]
+        MediaCard["MediaCard"]
+    end
+
+    subgraph PlaylistComps["Playlist Components"]
+        CreatePlaylistModal["CreatePlaylistModal"]
+        AddToPlaylistModal["AddToPlaylistModal"]
+    end
+
+    subgraph CommonComps["Common Components"]
+        ScrollPicker["ScrollPicker"]
+    end
+
+    subgraph OtherComps["Other Components"]
+        Search["Search"]
+        FavoriteBtn["FavoriteButton"]
+        DownloadItem["DownloadItem"]
+    end
+
+    LibLayout --> PlayerComps
+    LibLayout --> LibDetail
+    MusicCategory --> Tracks
+    MusicCategory --> Artists
+    MusicCategory --> Albums
+    MusicCategory --> Playlists
+    MusicCategory --> Genres
+    LibDetail --> LibraryComps
+    Playlists --> PlaylistComps
+    Playlists --> PlaylistDetail
+    Downloads --> DownloadItem
+    PlayerPage --> PlayerComps
+
+    MiniPlayer --> CastButton
+    CastButton --> SessionModal
+    SleepTimerModal --> ScrollPicker
+    PlayerComps --> LibraryComps
+```
+
+## MiniPlayer Behavior
+
+**Location**: `src/lib/components/player/MiniPlayer.svelte`
+
+The MiniPlayer is a persistent bottom bar for audio playback that supports touch gestures and playback controls.
+
+**Touch Gesture Handling:**
+
+The MiniPlayer uses touch events to distinguish between taps (on controls) and swipe-up gestures (to expand to full player page):
+
+```typescript
+function handleTouchStart(e: TouchEvent) {
+  touchStartX = e.touches[0].clientX;
+  touchStartY = e.touches[0].clientY;
+  touchEndX = touchStartX;   // Initialize to start position
+  touchEndY = touchStartY;   // Prevents taps being treated as swipes
+  isSwiping = true;
+}
+```
+
+**Key Design Decision**: `touchEndX`/`touchEndY` must be initialized to the start position in `handleTouchStart`. Without this, a pure tap (no `touchmove` event fired) would compute the swipe distance against (0,0), making every tap look like a massive swipe-up and inadvertently navigating to the player page.
+
+**Skip Button State:**
+
+The MiniPlayer's next/previous buttons are enabled based on `appState.hasNext`/`hasPrevious`, which are updated by `playerEvents.ts` calling `invoke("player_get_queue")` on every `StateChanged` event from the backend.
+
+## Sleep Timer Architecture
+
+**Location**: `src-tauri/src/player/sleep_timer.rs`, `src-tauri/src/player/mod.rs`
+
+**TRACES**: UR-026 | DR-029
+
+The sleep timer supports three modes for stopping playback:
+
+```rust
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub enum SleepTimerMode {
+    Off,
+    Time { end_time: i64 },      // Unix timestamp in milliseconds
+    EndOfTrack,                    // Stop after current track/episode
+    Episodes { remaining: u32 },   // Stop after N more episodes
+}
+```
+
+**Timer Modes:**
+
+| Mode | Trigger | How It Stops |
+|------|---------|-------------|
+| Time | User selects 15/30/45/60 min via roller UI | Background timer thread stops backend when `remaining_seconds == 0`; also checked at track boundaries in `on_playback_ended()` |
+| EndOfTrack | User clicks "End of current track" | Checked in `on_playback_ended()`, returns `AutoplayDecision::Stop` |
+| Episodes | User selects 1-10 episodes | `decrement_episode()` in `on_playback_ended()`, stops when counter reaches 0 |
+
+**Time-Based Timer Flow:**
+
+```mermaid
+sequenceDiagram
+    participant UI as SleepTimerModal
+    participant Store as sleepTimer store
+    participant Rust as PlayerController
+    participant Thread as Timer Thread
+    participant Backend as PlayerBackend
+
+    UI->>Store: setTimeTimer(30)
+    Store->>Rust: invoke("player_set_sleep_timer", {mode})
+    Rust->>Rust: Set SleepTimerMode::Time { end_time }
+    Rust->>UI: Emit SleepTimerChanged event
+
+    loop Every 1 second
+        Thread->>Thread: update_remaining_seconds()
+        Thread->>UI: Emit SleepTimerChanged (countdown)
+        alt remaining_seconds == 0
+            Thread->>Backend: stop()
+            Thread->>UI: Emit SleepTimerChanged (Off)
+        end
+    end
+```
+
+**Frontend Components:**
+
+- **ScrollPicker** (`src/lib/components/common/ScrollPicker.svelte`): Reusable scroll-wheel picker using CSS `scroll-snap-type: y mandatory`. Configurable items, visible count, and item height. Used by SleepTimerModal for time selection.
+- **SleepTimerModal** (`src/lib/components/player/SleepTimerModal.svelte`): Modal with three sections - time picker (roller), end of track button, episode counter. Time section uses ScrollPicker with 15/30/45/60 min options. Accepts optional `mediaType` prop to override queue-based detection (used by VideoPlayer since video playback clears the audio queue).
+- **SleepTimerIndicator** (`src/lib/components/player/SleepTimerIndicator.svelte`): Compact indicator showing active timer status with countdown.
+- **Sleep buttons**: Clock icon buttons on AudioPlayer header, Controls bar, MiniPlayer, and VideoPlayer control bar. Shows clock icon when inactive, SleepTimerIndicator when active.
+
+**Key Design Decisions:**
+
+1. **All logic in Rust**: Frontend only displays state and invokes commands
+2. **Background timer thread**: Handles time-based countdown independently of track boundaries
+3. **Dual stop mechanism for Time mode**: Timer thread stops mid-track; `on_playback_ended()` catches edge case at track boundary
+4. **Event-driven UI updates**: Timer thread emits `SleepTimerChanged` every second for countdown display
+
+## Auto-Play Episode Limit
+
+**Location**: `src-tauri/src/player/mod.rs`, `src-tauri/src/player/autoplay.rs`, `src-tauri/src/settings.rs`
+
+**TRACES**: UR-023 | DR-049
+
+Limits how many episodes auto-play consecutively before requiring manual intervention.
+
+**Settings:**
+
+```rust
+// In AutoplaySettings (runtime, in PlayerController)
+pub struct AutoplaySettings {
+    pub enabled: bool,
+    pub countdown_seconds: u32,
+    pub max_episodes: u32,  // 0 = unlimited
+}
+
+// In VideoSettings (persisted, settings page)
+pub struct VideoSettings {
+    pub auto_play_next_episode: bool,
+    pub auto_play_countdown_seconds: u32,
+    pub auto_play_max_episodes: u32,  // 0 = unlimited
+}
+```
+
+**Session-Based Counter:**
+
+The `autoplay_episode_count` field in `PlayerController` tracks consecutive auto-played episodes:
+
+- **Incremented**: In `on_playback_ended()` when auto-playing next episode
+- **Reset**: On any manual user action (`play_item()`, `play_queue()`, `next()`, `previous()`)
+- **Limit check**: When `max_episodes > 0` and `count >= max_episodes`, the popup shows with `auto_advance: false` - user must manually click "Play Now" to continue
+
+```mermaid
+flowchart TB
+    PlaybackEnded["on_playback_ended()"] --> CheckEpisode{"Is video<br/>episode?"}
+    CheckEpisode -->|"No"| AudioFlow["Audio queue logic"]
+    CheckEpisode -->|"Yes"| FetchNext["Fetch next episode"]
+    FetchNext --> IncrementCount["increment_autoplay_count()"]
+    IncrementCount --> CheckLimit{"max_episodes > 0<br/>AND count >= max?"}
+    CheckLimit -->|"No"| ShowPopup["ShowNextEpisodePopup<br/>auto_advance: true"]
+    CheckLimit -->|"Yes"| ShowPopupManual["ShowNextEpisodePopup<br/>auto_advance: false"]
+    ShowPopupManual --> UserClick["User clicks 'Play Now'"]
+    UserClick --> PlayItem["play_item() -> resets counter"]
+```
+
+**Settings Sync:**
+
+`VideoSettings` (settings page) and `AutoplaySettings` (PlayerController runtime) are synced via `player_set_video_settings`, which updates both the `VideoSettingsWrapper` state and calls `controller.set_autoplay_settings()`.
+
+**Database**: Migration 016 adds `autoplay_max_episodes INTEGER DEFAULT 0` to `user_player_settings`.
+
+**Settings UI**: Button grid with options: Unlimited, 1, 2, 3, 5, 10 episodes. Visible only when auto-play is enabled.
+
+## Player Page Navigation Guard
+
+**Location**: `src/routes/player/[id]/+page.svelte`
+
+When the user navigates to the full player page (e.g., by swiping up on MiniPlayer), the `loadAndPlay` function checks whether the track is already playing before initiating new playback:
+
+```typescript
+const alreadyPlayingMedia = get(storeCurrentMedia);
+if (alreadyPlayingMedia?.id === id && !startPosition) {
+  // Track already playing - show UI without restarting playback
+  // Fetch queue status for hasNext/hasPrevious
+  return;
+}
+```
+
+**Why This Matters**: Without this guard, navigating to the player page would restart playback with a single-track queue, destroying the existing album/playlist queue that the backend is playing. The Rust backend maintains the full queue (visible on the Android lock screen), but the frontend `loadAndPlay` function would overwrite it by calling `player_play_tracks` with just the current track.
+
+## Playlist Management UI
+
+**TRACES**: UR-014 | JA-019 | JA-020
+
+**Location**: `src/lib/components/playlist/`, `src/lib/components/library/PlaylistDetailView.svelte`
+
+The playlist UI provides full CRUD operations for Jellyfin playlists with offline sync support.
+
+**Components:**
+
+- **CreatePlaylistModal** (`src/lib/components/playlist/CreatePlaylistModal.svelte`):
+  - Modal for creating new playlists with a name input
+  - Accepts optional `initialItemIds` to pre-populate with tracks
+  - Keyboard support: Enter to create, Escape to close
+  - Navigates to new playlist detail page on creation
+
+- **AddToPlaylistModal** (`src/lib/components/playlist/AddToPlaylistModal.svelte`):
+  - Modal listing all existing playlists to add tracks to
+  - "New Playlist" button for inline creation flow
+  - Shows playlist artwork via CachedImage
+  - Loading state with skeleton placeholders
+
+- **PlaylistDetailView** (`src/lib/components/library/PlaylistDetailView.svelte`):
+  - Full playlist detail page with artwork, name, track count, total duration
+  - Click-to-rename with inline editing
+  - Play all / shuffle play buttons
+  - Delete with confirmation dialog
+  - Per-track removal buttons
+  - Uses `TrackList` component for track display
+  - Passes `{ type: "playlist", playlistId, playlistName }` context to player
+
+- **Playlists Page** (`src/routes/library/music/playlists/+page.svelte`):
+  - Grid view using `GenericMediaListPage`
+  - Floating action button (FAB) to create new playlists
+  - Search by playlist name
+
+**Frontend API Methods** (`src/lib/api/repository-client.ts`):
+- `createPlaylist(name, itemIds?)` -> `PlaylistCreatedResult`
+- `deletePlaylist(playlistId)`
+- `renamePlaylist(playlistId, name)`
+- `getPlaylistItems(playlistId)` -> `PlaylistEntry[]`
+- `addToPlaylist(playlistId, itemIds)`
+- `removeFromPlaylist(playlistId, entryIds)`
+- `movePlaylistItem(playlistId, itemId, newIndex)`
+
+**Offline Sync** (`src/lib/services/syncService.ts`):
+All playlist mutations are queued for offline sync:
+- `queuePlaylistCreate`, `queuePlaylistDelete`, `queuePlaylistRename`
+- `queuePlaylistAddItems`, `queuePlaylistRemoveItems`, `queuePlaylistReorderItem`

docs/architecture/03-data-flow.md

@@ -0,0 +1,163 @@
+# Data Flow
+
+## Repository Query Flow (Cache-First)
+
+```mermaid
+sequenceDiagram
+    participant UI as Svelte Component
+    participant Client as RepositoryClient (TS)
+    participant Rust as Tauri Command
+    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})
+    Rust->>Hybrid: get_items()
+
+    par Parallel Racing
+        Hybrid->>Cache: get_items() with 100ms timeout
+        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
+    else Cache timeout or empty
+        Server-->>Hybrid: Fresh result
+        Hybrid-->>Rust: Return server result
+    end
+
+    Rust-->>Client: SearchResult
+    Client-->>UI: items[]
+    Note over UI: Reactive update
+```
+
+**Key Points:**
+- Cache queries have 100ms timeout for responsiveness
+- Server queries always run for fresh data
+- 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
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AudioPlayer
+    participant Tauri as Tauri IPC
+    participant Command as player_play_item()
+    participant Controller as PlayerController
+    participant Backend as PlayerBackend
+    participant Store as Frontend Store
+
+    User->>AudioPlayer: clicks play
+    AudioPlayer->>Tauri: invoke("player_play_item", {item})
+    Tauri->>Command: player_play_item()
+    Command->>Command: Convert PlayItemRequest -> MediaItem
+    Command->>Controller: play_item(item)
+    Controller->>Backend: load(item)
+    Note over Backend: State -> Loading
+    Controller->>Backend: play()
+    Note over Backend: State -> Playing
+    Controller-->>Command: Ok(())
+    Command-->>Tauri: PlayerStatus {state, position, duration, volume}
+    Tauri-->>AudioPlayer: status
+    AudioPlayer->>Store: player.setPlaying(media, position, duration)
+    Note over Store: UI updates reactively
+```
+
+## Playback Mode Transfer Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Cast Button
+    participant Store as playbackMode store
+    participant Rust as Tauri Command
+    participant Manager as PlaybackModeManager
+    participant Player as PlayerController
+    participant Jellyfin as Jellyfin API
+
+    UI->>Store: transferToRemote(sessionId)
+    Store->>Rust: invoke("playback_mode_transfer_to_remote", {sessionId})
+    Rust->>Manager: transfer_to_remote()
+
+    Manager->>Player: Get current queue
+    Player-->>Manager: Vec<MediaItem>
+    Manager->>Manager: Extract Jellyfin IDs
+
+    Manager->>Jellyfin: POST /Sessions/{id}/Playing<br/>{itemIds, startIndex}
+    Jellyfin-->>Manager: 200 OK
+
+    Manager->>Jellyfin: POST /Sessions/{id}/Playing/Seek<br/>{positionTicks}
+    Jellyfin-->>Manager: 200 OK
+
+    Manager->>Player: stop()
+    Manager->>Manager: mode = Remote {sessionId}
+
+    Manager-->>Rust: Ok(())
+    Rust-->>Store: PlaybackMode
+    Store->>UI: Update cast icon
+```
+
+## Queue Navigation Flow
+
+```mermaid
+flowchart TB
+    User["User clicks Next"] --> Invoke["invoke('player_next')"]
+    Invoke --> ControllerNext["controller.next()"]
+    ControllerNext --> QueueNext["queue.next()<br/>- Check repeat mode<br/>- Check shuffle<br/>- Update history"]
+
+    QueueNext --> None["None<br/>(at end)"]
+    QueueNext --> Some["Some(next)"]
+    QueueNext --> Same["Same<br/>(repeat one)"]
+
+    Some --> PlayItem["play_item(next)<br/>Returns new status"]
+```
+
+## Volume Control Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Slider as Volume Slider
+    participant Handler as handleVolumeChange()
+    participant Tauri as Tauri IPC
+    participant Command as player_set_volume
+    participant Controller as PlayerController
+    participant Backend as MpvBackend/NullBackend
+    participant Events as playerEvents.ts
+    participant Store as Player Store
+    participant UI
+
+    User->>Slider: adjusts (0-100)
+    Slider->>Handler: oninput event
+    Handler->>Handler: Convert 0-100 -> 0.0-1.0
+    Handler->>Tauri: invoke("player_set_volume", {volume})
+    Tauri->>Command: player_set_volume
+    Command->>Controller: set_volume(volume)
+    Controller->>Backend: set_volume(volume)
+    Backend->>Backend: Clamp to 0.0-1.0
+    Note over Backend: MpvBackend: Send to MPV loop
+    Backend-->>Tauri: emit "player-event"
+    Tauri-->>Events: VolumeChanged event
+    Events->>Store: player.setVolume(volume)
+    Store-->>UI: Reactive update
+    Note over UI: Both AudioPlayer and<br/>MiniPlayer stay in sync
+```
+
+**Key Implementation Details:**
+- Volume is stored in the backend (NullBackend/MpvBackend)
+- `PlayerController.volume()` delegates to backend
+- `get_player_status()` returns `controller.volume()` (not hardcoded)
+- Frontend uses normalized 0.0-1.0 scale, UI shows 0-100

docs/architecture/04-type-sync-and-threading.md

@@ -0,0 +1,132 @@
+# Type Synchronization & Thread Safety
+
+## PlayerState (Rust <-> TypeScript)
+
+**Rust:**
+```rust
+pub enum PlayerState {
+    Idle,
+    Loading { media: MediaItem },
+    Playing { media: MediaItem, position: f64, duration: f64 },
+    Paused { media: MediaItem, position: f64, duration: f64 },
+    Seeking { media: MediaItem, target: f64 },
+    Error { media: Option<MediaItem>, error: String },
+}
+```
+
+**TypeScript:**
+```typescript
+type PlayerState =
+  | { kind: "idle" }
+  | { kind: "loading"; media: MediaItem }
+  | { kind: "playing"; media: MediaItem; position: number; duration: number }
+  | { kind: "paused"; media: MediaItem; position: number; duration: number }
+  | { kind: "seeking"; media: MediaItem; target: number }
+  | { kind: "error"; media: MediaItem | null; error: string };
+```
+
+## MediaItem Serialization
+
+```rust
+// Rust (serde serialization)
+#[derive(Serialize, Deserialize)]
+pub struct MediaItem {
+    pub id: String,
+    pub title: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub artist: Option<String>,
+    // ...
+}
+```
+
+```typescript
+// TypeScript
+interface MediaItem {
+  id: string;
+  title: string;
+  artist?: string;
+  // ...
+}
+```
+
+## Tauri v2 IPC Parameter Naming Convention
+
+**CRITICAL**: Tauri v2's `#[tauri::command]` macro automatically converts snake_case Rust parameter names to camelCase for the frontend. All `invoke()` calls must use camelCase for top-level parameters.
+
+**Rule**: Rust `fn cmd(repository_handle: String)` -> Frontend sends `{ repositoryHandle: "..." }`
+
+```typescript
+// CORRECT - Tauri v2 auto-converts snake_case -> camelCase
+await invoke("player_play_tracks", {
+  repositoryHandle: "handle-123",     // Rust: repository_handle
+  request: { trackIds: ["id1"], startIndex: 0 }
+});
+
+await invoke("remote_send_command", {
+  sessionId: "session-123",           // Rust: session_id
+  command: "PlayPause"
+});
+
+await invoke("pin_item", {
+  itemId: "item-123"                  // Rust: item_id
+});
+
+// WRONG - snake_case causes "invalid args request" error on Android
+await invoke("player_play_tracks", {
+  repository_handle: "handle-123",    // Will fail!
+});
+```
+
+**Parameter Name Mapping (Rust -> Frontend)**:
+
+| Rust Parameter | Frontend Parameter | Used By |
+|----------------|-------------------|----|
+| `repository_handle` | `repositoryHandle` | `player_play_tracks`, `player_add_track_by_id`, `player_play_album_track` |
+| `session_id` | `sessionId` | `remote_send_command`, `remote_play_on_session`, `remote_session_seek` |
+| `item_id` | `itemId` | `pin_item`, `unpin_item` |
+| `current_item_id` | `currentItemId` | `playback_mode_transfer_to_local` |
+| `position_ticks` | `positionTicks` | `playback_mode_transfer_to_local`, `remote_session_seek` |
+| `item_ids` | `itemIds` | `remote_play_on_session` |
+| `start_index` | `startIndex` | `remote_play_on_session` |
+
+**Nested struct fields** use `#[serde(rename_all = "camelCase")]` separately - this is serde deserialization, not the command macro. Both layers convert independently.
+
+**Test Coverage**: Integration tests in `src/lib/utils/tauriIntegration.test.ts` validate all invoke calls use correct camelCase parameter names.
+
+## Rust Backend Thread Safety
+
+```rust
+// Shared state wrapped in Arc<Mutex<>>
+pub struct PlayerController {
+    backend: Arc<Mutex<Box<dyn PlayerBackend>>>,
+    queue: Arc<Mutex<QueueManager>>,
+    // ...
+}
+
+// Tauri state wrapper
+pub struct PlayerStateWrapper(pub Mutex<PlayerController>);
+
+// Command handler pattern
+#[tauri::command]
+pub fn player_play(state: State<PlayerStateWrapper>) -> Result<PlayerStatus, String> {
+    let mut controller = state.0.lock().unwrap();  // Acquire lock
+    controller.play()?;                             // Operate
+    Ok(get_player_status(&controller))              // Lock released
+}
+```
+
+## Frontend Stores
+
+Svelte stores are inherently reactive and thread-safe for UI updates:
+
+```typescript
+const { subscribe, update } = writable<PlayerStore>(initialState);
+
+// Atomic updates
+function setPlaying(media: MediaItem, position: number, duration: number) {
+  update(state => ({
+    ...state,
+    state: { kind: "playing", media, position, duration }
+  }));
+}
+```

docs/architecture/05-platform-backends.md

@@ -0,0 +1,529 @@
+# Platform-Specific Player Backends
+
+## Player Events System
+
+**Location**: `src-tauri/src/player/events.rs`
+
+The player uses a push-based event system to notify the frontend of state changes:
+
+```rust
+pub enum PlayerStatusEvent {
+    /// Playback position updated (emitted periodically during playback)
+    PositionUpdate { position: f64, duration: f64 },
+
+    /// Player state changed
+    StateChanged { state: String, media_id: Option<String> },
+
+    /// Media has finished loading and is ready to play
+    MediaLoaded { duration: f64 },
+
+    /// Playback has ended naturally
+    PlaybackEnded,
+
+    /// Buffering state changed
+    Buffering { percent: u8 },
+
+    /// An error occurred during playback
+    Error { message: String, recoverable: bool },
+
+    /// Volume changed
+    VolumeChanged { volume: f32, muted: bool },
+
+    /// Sleep timer state changed
+    SleepTimerChanged {
+        mode: SleepTimerMode,
+        remaining_seconds: u32,
+    },
+
+    /// Show next episode popup with countdown
+    ShowNextEpisodePopup {
+        current_episode: MediaItem,
+        next_episode: MediaItem,
+        countdown_seconds: u32,
+        auto_advance: bool,
+    },
+
+    /// Countdown tick (emitted every second during autoplay countdown)
+    CountdownTick { remaining_seconds: u32 },
+
+    /// Queue changed (items added, removed, reordered, or playback mode changed)
+    QueueChanged {
+        items: Vec<MediaItem>,
+        current_index: Option<usize>,
+        shuffle: bool,
+        repeat: RepeatMode,
+        has_next: bool,
+        has_previous: bool,
+    },
+
+    /// Media session changed (activity context changed: Audio/Movie/TvShow/Idle)
+    SessionChanged { session: MediaSessionType },
+}
+```
+
+Events are emitted via Tauri's event system:
+
+```mermaid
+flowchart LR
+    subgraph Backend["Player Backend"]
+        MPV["MPV/ExoPlayer"]
+    end
+
+    subgraph EventSystem["Event System"]
+        Emitter["TauriEventEmitter<br/>emit()"]
+        Bus["Tauri Event Bus<br/>'player-event'"]
+    end
+
+    subgraph Frontend["Frontend"]
+        Listener["playerEvents.ts<br/>Frontend Listener"]
+        Store["Player Store Update<br/>(position, state, etc)"]
+    end
+
+    MPV --> Emitter --> Bus --> Listener --> Store
+```
+
+**Frontend Listener** (`src/lib/services/playerEvents.ts`):
+- Listens for `player-event` Tauri events
+- Updates player/queue stores based on event type
+- Auto-advances to next track on `PlaybackEnded`
+- On `StateChanged` events, calls `invoke("player_get_queue")` to update `appState.hasNext`/`hasPrevious` -- this enables MiniPlayer skip button state
+
+**Important**: The command is `player_get_queue` (returns `QueueStatus` with `hasNext`/`hasPrevious`). There is no `player_get_queue_status` command.
+
+## HTML5 Video Adapter (webview-rendered video)
+
+**Location**: `src/lib/player/html5Adapter.ts`, `src/lib/player/index.ts`, report commands in
+`src-tauri/src/commands/player/timers.rs`
+
+Video on desktop (Linux WebKitGTK) — and, per current interim behavior, Android — is rendered by an
+HTML5 `<video>`/HLS element **inside the webview**. libmpv is initialized audio-only (`vo=null`,
+`video=false`), so the native backend cannot render or observe this element. The `<video>` is therefore
+the real player, living outside Rust's reach.
+
+To keep the `PlayerController` the single source of truth (matching the audio path), the HTML5 element
+is treated as **a dumb output device that reports back into Rust**, rather than an independent state
+authority:
+
+```mermaid
+flowchart LR
+    subgraph Webview["Webview"]
+        Video["HTML5 <video> / HLS.js"]
+        Adapter["html5Adapter.ts<br/>(reports DOM events)"]
+    end
+    subgraph Backend["Rust"]
+        Cmds["player_report_state<br/>player_report_position<br/>player_report_media_loaded"]
+        Controller["PlayerController"]
+        Emitter["TauriEventEmitter"]
+    end
+    subgraph Frontend["Frontend"]
+        Events["playerEvents.ts"]
+        Store["player store"]
+    end
+
+    Video -->|DOM events| Adapter --> Cmds --> Controller --> Emitter --> Events --> Store
+```
+
+**Key points:**
+- The adapter re-emits the *same* `PlayerStatusEvent`s (`StateChanged`, `PositionUpdate`, `MediaLoaded`)
+  the native backends emit, so `playerEvents.ts` needs **no** HTML5-specific branch — HTML5 is just
+  another event source feeding the existing pipeline.
+- Position reports are throttled (~250ms) to match the MPV cadence and avoid flooding IPC from the
+  60fps RAF loop.
+- **Boundary rule**: UI components never touch the report commands or `videoElement` state directly.
+  Playback *control* goes through the unified facade `src/lib/player/index.ts` (`playerController`);
+  HTML5 *state reporting* goes through `html5Adapter.ts`. This restores the documented invariant
+  ("frontend only displays state and invokes commands") for the video path.
+
+## MpvBackend (Linux)
+
+**Location**: `src-tauri/src/player/mpv/`
+
+The MPV backend uses libmpv for audio playback on Linux. Since MPV handles are not `Send`, all operations occur on a dedicated thread.
+
+```mermaid
+flowchart TB
+    subgraph MainThread["Main Thread"]
+        MpvBackend["MpvBackend<br/>- command_tx<br/>- shared_state<br/>- shutdown"]
+        Commands["Commands:<br/>Load, Play, Pause<br/>Stop, Seek, SetVolume"]
+    end
+
+    subgraph EventLoopThread["MPV Event Loop Thread"]
+        EventLoop["event_loop.rs<br/>- MPV Handle<br/>- command_rx<br/>- Event Emitter"]
+        TauriEmitter["TauriEventEmitter"]
+    end
+
+    MpvBackend -->|"MpvCommand"| EventLoop
+    MpvBackend <-->|"Arc<Mutex<>>"| EventLoop
+    EventLoop -->|"Events"| TauriEmitter
+    TauriEmitter --> FrontendStore["Frontend Store"]
+```
+
+**Key Components:**
+
+```rust
+// Command enum sent to event loop thread
+pub enum MpvCommand {
+    Load { url: String, media: MediaItem },
+    Play,
+    Pause,
+    Stop,
+    Seek(f64),
+    SetVolume(f32),
+    Quit,
+}
+
+// Shared state between main thread and event loop
+pub struct MpvSharedState {
+    pub state: PlayerState,
+    pub position: f64,
+    pub duration: Option<f64>,
+    pub volume: f32,
+    pub is_loaded: bool,
+    pub current_media: Option<MediaItem>,
+}
+```
+
+**Event Loop** (`event_loop.rs`):
+- Initializes MPV with audio-only config (`vo=null`, `video=false`)
+- Observes properties: `time-pos`, `duration`, `pause`, `volume`
+- Emits position updates every 250ms during playback
+- Processes commands from channel (non-blocking)
+- Handles MPV events: `FileLoaded`, `EndFile`, `PropertyChange`
+
+## ExoPlayerBackend (Android)
+
+**Location**: `src-tauri/src/player/android/` and Kotlin sources
+
+The ExoPlayer backend uses Android's Media3/ExoPlayer library via JNI.
+
+```mermaid
+flowchart TB
+    subgraph RustNative["Rust (Native)"]
+        ExoBackend["ExoPlayerBackend<br/>- player_ref<br/>- shared_state"]
+        NativeFuncs["JNI Callbacks<br/>nativeOnPosition...<br/>nativeOnState...<br/>nativeOnMediaLoaded<br/>nativeOnPlaybackEnd"]
+        TauriEmitter2["TauriEventEmitter"]
+    end
+
+    subgraph KotlinJVM["Kotlin (JVM)"]
+        JellyTauPlayer["JellyTauPlayer<br/>- ExoPlayer<br/>- Player.Listener"]
+    end
+
+    ExoBackend -->|"JNI Calls"| JellyTauPlayer
+    JellyTauPlayer -->|"Callbacks"| NativeFuncs
+    NativeFuncs --> TauriEmitter2
+    TauriEmitter2 --> FrontendStore2["Frontend Store"]
+```
+
+**Kotlin Player** (`JellyTauPlayer.kt`):
+```kotlin
+class JellyTauPlayer(context: Context) {
+    private val exoPlayer: ExoPlayer
+    private var positionUpdateJob: Job?
+
+    // Methods callable from Rust via JNI
+    fun load(url: String, mediaId: String)
+    fun play()
+    fun pause()
+    fun stop()
+    fun seek(positionSeconds: Double)
+    fun setVolume(volume: Float)
+
+    // Native callbacks to Rust
+    private external fun nativeOnPositionUpdate(position: Double, duration: Double)
+    private external fun nativeOnStateChanged(state: String, mediaId: String?)
+    private external fun nativeOnMediaLoaded(duration: Double)
+    private external fun nativeOnPlaybackEnded()
+}
+```
+
+**JNI Callbacks** (Rust):
+```rust
+#[no_mangle]
+pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_nativeOnPositionUpdate(
+    _env: JNIEnv, _class: JClass, position: jdouble, duration: jdouble
+) {
+    // Update shared state
+    // Emit PlayerStatusEvent::PositionUpdate
+}
+```
+
+## Android MediaSession & Remote Volume Control
+
+**Location**: `JellyTauPlaybackService.kt`
+
+JellyTau uses a dual MediaSession architecture for Android to support both Media3 playback controls and remote volume control:
+
+```mermaid
+flowchart TB
+    subgraph Service["JellyTauPlaybackService"]
+        MediaSession["Media3 MediaSession<br/>- Lockscreen controls<br/>- Media notifications<br/>- Play/Pause/Next/Previous"]
+
+        MediaSessionCompat["MediaSessionCompat<br/>- Remote volume control<br/>- Hardware button interception"]
+
+        VolumeProvider["VolumeProviderCompat<br/>- onSetVolumeTo()<br/>- onAdjustVolume()"]
+
+        MediaSessionCompat --> VolumeProvider
+    end
+
+    subgraph Hardware["System"]
+        VolumeButtons["Hardware Volume Buttons"]
+        Lockscreen["Lockscreen Controls"]
+        Notification["Media Notification"]
+    end
+
+    subgraph Rust["Rust Backend"]
+        JNI["JNI Callbacks<br/>nativeOnRemoteVolumeChange()"]
+        PlaybackMode["PlaybackModeManager<br/>send_remote_volume_command()"]
+        JellyfinAPI["Jellyfin API<br/>session_set_volume()"]
+    end
+
+    VolumeButtons --> VolumeProvider
+    Lockscreen --> MediaSession
+    Notification --> MediaSession
+
+    VolumeProvider --> JNI
+    JNI --> PlaybackMode
+    PlaybackMode --> JellyfinAPI
+```
+
+**Architecture Rationale:**
+
+JellyTau maintains both MediaSession types because they serve different purposes:
+
+1. **Media3 MediaSession**: Handles lockscreen/notification playback controls (play/pause/next/previous)
+2. **MediaSessionCompat**: Intercepts hardware volume button presses for remote playback control
+
+When in remote playback mode (controlling a Jellyfin session on another device):
+- Volume buttons are routed through `VolumeProviderCompat`
+- Volume changes are sent to the remote session via Jellyfin API
+- System volume UI shows the remote session's volume level
+
+**Remote Volume Flow:**
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant VolumeButton as Hardware Volume Button
+    participant VolumeProvider as VolumeProviderCompat
+    participant JNI as nativeOnRemoteVolumeChange
+    participant PlaybackMode as PlaybackModeManager
+    participant Jellyfin as Jellyfin Server
+    participant RemoteSession as Remote Session (TV/Browser)
+
+    User->>VolumeButton: Press Volume Up
+    VolumeButton->>VolumeProvider: onAdjustVolume(ADJUST_RAISE)
+    VolumeProvider->>VolumeProvider: remoteVolumeLevel += 2
+    VolumeProvider->>VolumeProvider: currentVolume = remoteVolumeLevel
+    VolumeProvider->>JNI: nativeOnRemoteVolumeChange("VolumeUp", level)
+    JNI->>PlaybackMode: send_remote_volume_command("VolumeUp", level)
+    PlaybackMode->>Jellyfin: POST /Sessions/{id}/Command/VolumeUp
+    Jellyfin->>RemoteSession: Set volume to new level
+    RemoteSession-->>User: Volume changes on TV/Browser
+```
+
+**Key Implementation Details:**
+
+**Enabling Remote Volume** (`enableRemoteVolume()`):
+```kotlin
+fun enableRemoteVolume(initialVolume: Int) {
+    volumeProvider = object : VolumeProviderCompat(
+        VolumeProviderCompat.VOLUME_CONTROL_ABSOLUTE,
+        100,  // Max volume
+        initialVolume
+    ) {
+        override fun onSetVolumeTo(volume: Int) {
+            remoteVolumeLevel = volume.coerceIn(0, 100)
+            nativeOnRemoteVolumeChange("SetVolume", remoteVolumeLevel)
+        }
+
+        override fun onAdjustVolume(direction: Int) {
+            when (direction) {
+                AudioManager.ADJUST_RAISE -> {
+                    remoteVolumeLevel = (remoteVolumeLevel + 2).coerceAtMost(100)
+                    nativeOnRemoteVolumeChange("VolumeUp", remoteVolumeLevel)
+                    currentVolume = remoteVolumeLevel
+                }
+                AudioManager.ADJUST_LOWER -> {
+                    remoteVolumeLevel = (remoteVolumeLevel - 2).coerceAtLeast(0)
+                    nativeOnRemoteVolumeChange("VolumeDown", remoteVolumeLevel)
+                    currentVolume = remoteVolumeLevel
+                }
+            }
+        }
+    }
+
+    mediaSessionCompat.setPlaybackToRemote(volumeProvider)
+}
+```
+
+**Disabling Remote Volume** (`disableRemoteVolume()`):
+```kotlin
+fun disableRemoteVolume() {
+    mediaSessionCompat.setPlaybackToLocal(AudioManager.STREAM_MUSIC)
+    volumeProvider = null
+}
+```
+
+**Rust Integration** (`src-tauri/src/player/android/mod.rs`):
+```rust
+/// Enable remote volume control on Android
+pub fn enable_remote_volume(initial_volume: i32) -> Result<(), String> {
+    start_playback_service()?;
+    let service_instance = get_playback_service_instance()?;
+    env.call_method(&service_instance, "enableRemoteVolume", "(I)V",
+        &[JValue::Int(initial_volume)])?;
+    Ok(())
+}
+```
+
+**Dependencies** (`src-tauri/android/build.gradle.kts`):
+```kotlin
+dependencies {
+    implementation("androidx.media3:media3-session:1.5.1")  // Media3 MediaSession
+    implementation("androidx.media:media:1.7.0")            // MediaSessionCompat
+}
+```
+
+**Integration with Playback Mode:**
+
+Remote volume is automatically enabled/disabled during playback mode transfers:
+
+```rust
+// In PlaybackModeManager::transfer_to_remote()
+#[cfg(target_os = "android")]
+{
+    if let Err(e) = crate::player::enable_remote_volume(50) {
+        log::warn!("Failed to enable remote volume: {}", e);
+    }
+}
+
+// In PlaybackModeManager::transfer_to_local()
+#[cfg(target_os = "android")]
+{
+    if let Err(e) = crate::player::disable_remote_volume() {
+        log::warn!("Failed to disable remote volume: {}", e);
+    }
+}
+```
+
+## Android Album Art Caching
+
+**Location**: `src-tauri/android/src/main/java/com/dtourolle/jellytau/player/AlbumArtCache.kt`
+
+Album art caching provides efficient bitmap storage for lock screen notifications with automatic LRU eviction and memory management.
+
+```mermaid
+flowchart TB
+    subgraph JellyTauPlayer["JellyTauPlayer.kt"]
+        LoadMedia["loadWithMetadata()<br/>- Store artworkUrl<br/>- Launch async download"]
+        AsyncDownload["Coroutine<br/>- Non-blocking<br/>- Dispatchers.IO"]
+    end
+
+    subgraph Cache["AlbumArtCache.kt"]
+        MemoryCache["LruCache<String, Bitmap><br/>- 1/8 of heap<br/>- ~12-16MB typical<br/>- 50-100 albums capacity"]
+        Download["Download & Scale<br/>- 512x512 max<br/>- Exponential backoff"]
+        ErrorHandle["Error Handling<br/>- Graceful fallback<br/>- Auto-retry"]
+    end
+
+    subgraph Service["JellyTauPlaybackService.kt"]
+        UpdateMeta["updateMediaMetadata()<br/>- Accept Bitmap parameter<br/>- Add METADATA_KEY_ALBUM_ART"]
+        Notification["Notification<br/>- setLargeIcon()<br/>- Lock screen display"]
+    end
+
+    LoadMedia --> AsyncDownload
+    AsyncDownload --> MemoryCache
+    MemoryCache --> Download
+    Download --> ErrorHandle
+    AsyncDownload --> UpdateMeta
+    UpdateMeta --> Notification
+```
+
+**AlbumArtCache Singleton:**
+
+```kotlin
+class AlbumArtCache(context: Context) {
+    private val memoryCache = object : LruCache<String, Bitmap>(cacheSize) {
+        override fun sizeOf(key: String, bitmap: Bitmap): Int {
+            return bitmap.byteCount / 1024  // Size in KB
+        }
+    }
+
+    suspend fun getArtwork(url: String): Bitmap? {
+        memoryCache.get(url)?.let { return it }
+        return downloadAndCache(url)
+    }
+
+    private suspend fun downloadAndCache(url: String): Bitmap? =
+        withContext(Dispatchers.IO) {
+            // HTTP download with 5s timeout
+            // Scale to 512x512 max
+            // Auto-evict LRU if needed
+        }
+}
+```
+
+**Integration Flow:**
+
+1. **Track Load** (`loadWithMetadata()`):
+   - Store artwork URL in `currentArtworkUrl`
+   - Reset bitmap to null
+   - Start playback immediately (non-blocking)
+
+2. **Async Download** (Background Coroutine):
+   - Check cache: instant hit if available
+   - Network miss: download, scale, cache
+   - Auto-retry on network failure with exponential backoff
+   - Graceful fallback if artwork unavailable
+
+3. **Notification Update**:
+   - Pass bitmap to `updatePlaybackServiceNotification()`
+   - Add to `MediaMetadataCompat` with `METADATA_KEY_ALBUM_ART`
+   - Display as large icon in notification
+   - Show on lock screen
+
+**Memory Management:**
+
+| Metric | Value |
+|--------|-------|
+| Cache Size | 1/8 of heap (12-16MB typical) |
+| Max Resolution | 512x512 pixels |
+| Capacity | ~50-100 album arts |
+| Eviction Policy | LRU (Least Recently Used) |
+| Lifetime | In-memory only (app session) |
+| Network Timeout | 5 seconds per download |
+
+**Performance Characteristics:**
+
+- **Cache Hit**: ~1ms (in-memory retrieval)
+- **Cache Miss**: ~200-500ms (download + scale)
+- **Playback Impact**: Zero (async downloads)
+- **Memory Overhead**: Max 16MB (auto-eviction)
+- **Error Recovery**: Automatic with exponential backoff
+
+## Backend Initialization
+
+**Location**: `src-tauri/src/lib.rs`
+
+Backend selection is platform-specific:
+
+```rust
+fn create_player_backend(app_handle: tauri::AppHandle) -> Box<dyn PlayerBackend> {
+    let event_emitter = Arc::new(TauriEventEmitter::new(app_handle));
+
+    #[cfg(target_os = "linux")]
+    {
+        match MpvBackend::new(event_emitter.clone()) {
+            Ok(backend) => return Box::new(backend),
+            Err(e) => eprintln!("MPV init failed: {}", e),
+        }
+    }
+
+    #[cfg(target_os = "android")]
+    {
+        // ExoPlayer requires Activity context, initialized separately
+    }
+
+    // Fallback
+    Box::new(NullBackend::new())
+}
+```

docs/architecture/06-downloads-and-offline.md

@@ -0,0 +1,287 @@
+# Download Manager & Offline Architecture
+
+## Overview
+
+**Location**: `src-tauri/src/download/`
+
+The download manager provides offline media support with priority-based queue management, progress tracking, retry logic, and smart caching.
+
+```mermaid
+flowchart TB
+    subgraph Frontend["Frontend"]
+        DownloadButton["DownloadButton.svelte"]
+        DownloadsPage["/downloads"]
+        DownloadsStore["downloads.ts store"]
+    end
+
+    subgraph Backend["Rust Backend"]
+        Commands["Download Commands"]
+        DownloadManager["DownloadManager"]
+        DownloadWorker["DownloadWorker"]
+        SmartCache["SmartCache Engine"]
+    end
+
+    subgraph Storage["Storage"]
+        SQLite[("SQLite DB")]
+        MediaFiles[("Downloaded Files")]
+    end
+
+    DownloadButton -->|"invoke('download_item')"| Commands
+    DownloadsPage -->|"invoke('get_downloads')"| Commands
+    Commands --> DownloadManager
+    DownloadManager --> DownloadWorker
+    DownloadManager --> SmartCache
+    DownloadWorker -->|"HTTP Stream"| MediaFiles
+    DownloadWorker -->|"Events"| DownloadsStore
+    Commands <--> SQLite
+    SmartCache <--> SQLite
+```
+
+## Download Worker
+
+**Location**: `src-tauri/src/download/worker.rs`
+
+The download worker handles HTTP streaming with retry logic and resume support:
+
+```rust
+pub struct DownloadWorker {
+    client: reqwest::Client,
+    max_retries: u32,
+}
+
+pub struct DownloadTask {
+    pub id: i64,
+    pub item_id: String,
+    pub user_id: String,
+    pub priority: i32,
+    pub url: String,
+    pub target_path: PathBuf,
+    pub mime_type: Option<String>,
+    pub expected_size: Option<i64>,
+}
+```
+
+**Retry Strategy**:
+- Exponential backoff: 5s, 15s, 45s
+- Maximum 3 retry attempts
+- HTTP Range requests for resume support
+- Progress events emitted every 1MB
+
+**Download Flow**:
+
+```mermaid
+sequenceDiagram
+    participant UI
+    participant Command as download_item
+    participant DB as SQLite
+    participant Worker as DownloadWorker
+    participant Jellyfin as Jellyfin Server
+    participant Store as downloads store
+
+    UI->>Command: download_item(itemId, userId)
+    Command->>DB: INSERT INTO downloads
+    Command->>Worker: Start download task
+    Worker->>Jellyfin: GET /Items/{id}/Download
+
+    loop Progress Updates
+        Jellyfin->>Worker: Stream chunks
+        Worker->>Worker: Write to .part file
+        Worker->>Store: Emit progress event
+        Store->>UI: Update progress bar
+    end
+
+    Worker->>Worker: Rename .part to final
+    Worker->>DB: UPDATE status='completed'
+    Worker->>Store: Emit completed event
+    Store->>UI: Show completed
+```
+
+## Smart Caching Engine
+
+**Location**: `src-tauri/src/download/cache.rs`
+
+The smart caching system provides predictive downloads based on listening patterns:
+
+```rust
+pub struct SmartCache {
+    config: Arc<Mutex<CacheConfig>>,
+    album_play_history: Arc<Mutex<HashMap<String, Vec<String>>>>,
+}
+
+pub struct CacheConfig {
+    pub queue_precache_enabled: bool,
+    pub queue_precache_count: usize,        // Default: 5
+    pub album_affinity_enabled: bool,
+    pub album_affinity_threshold: usize,    // Default: 3
+    pub storage_limit: u64,                 // Default: 10GB
+    pub wifi_only: bool,                    // Default: true
+}
+```
+
+**Caching Strategies**:
+
+1. **Queue Pre-caching**: Auto-download next 5 tracks when playing (WiFi only)
+2. **Album Affinity**: If user plays 3+ tracks from album, cache entire album
+3. **LRU Eviction**: Remove least recently accessed when storage limit reached
+
+```mermaid
+flowchart TB
+    Play["Track Played"] --> CheckQueue{"Queue<br/>Pre-cache?"}
+    CheckQueue -->|"Yes"| CacheNext5["Download<br/>Next 5 Tracks"]
+
+    Play --> TrackHistory["Track Play History"]
+    TrackHistory --> CheckAlbum{"3+ Tracks<br/>from Album?"}
+    CheckAlbum -->|"Yes"| CacheAlbum["Download<br/>Full Album"]
+
+    CacheNext5 --> CheckStorage{"Storage<br/>Limit?"}
+    CacheAlbum --> CheckStorage
+    CheckStorage -->|"Exceeded"| EvictLRU["Evict LRU Items"]
+    CheckStorage -->|"OK"| Download["Queue Download"]
+```
+
+## Download Commands
+
+**Location**: `src-tauri/src/commands/download.rs`
+
+| Command | Parameters | Description |
+|---------|------------|-------------|
+| `download_item` | `item_id, user_id, file_path` | Queue single item download |
+| `download_album` | `album_id, user_id` | Queue all tracks in album |
+| `get_downloads` | `user_id, status_filter` | Get download list |
+| `pause_download` | `download_id` | Pause active download |
+| `resume_download` | `download_id` | Resume paused download |
+| `cancel_download` | `download_id` | Cancel and delete partial |
+| `delete_download` | `download_id` | Delete completed download |
+
+## Offline Commands
+
+**Location**: `src-tauri/src/commands/offline.rs`
+
+| Command | Parameters | Description |
+|---------|------------|-------------|
+| `offline_is_available` | `item_id` | Check if item downloaded |
+| `offline_get_items` | `user_id` | Get all offline items |
+| `offline_search` | `user_id, query` | Search downloaded items |
+
+## Player Integration
+
+**Location**: `src-tauri/src/commands/player.rs` (modified)
+
+The player checks for local downloads before streaming:
+
+```rust
+fn create_media_item(req: PlayItemRequest, db: Option<&DatabaseWrapper>) -> MediaItem {
+    let local_path = db.and_then(|db_wrapper| {
+        check_for_local_download(db_wrapper, &jellyfin_id).ok().flatten()
+    });
+
+    let source = if let Some(path) = local_path {
+        MediaSource::Local {
+            file_path: PathBuf::from(path),
+            jellyfin_item_id: Some(jellyfin_id.clone())
+        }
+    } else {
+        MediaSource::Remote {
+            stream_url: req.stream_url,
+            jellyfin_item_id: jellyfin_id.clone()
+        }
+    };
+
+    MediaItem { source, /* ... */ }
+}
+```
+
+## Frontend Downloads Store
+
+**Location**: `src/lib/stores/downloads.ts`
+
+```typescript
+interface DownloadsState {
+  downloads: Record<number, DownloadInfo>;
+  activeCount: number;
+  queuedCount: number;
+}
+
+const downloads = createDownloadsStore();
+
+// Actions
+downloads.downloadItem(itemId, userId, filePath)
+downloads.downloadAlbum(albumId, userId)
+downloads.pause(downloadId)
+downloads.resume(downloadId)
+downloads.cancel(downloadId)
+downloads.delete(downloadId)
+downloads.refresh(userId, statusFilter)
+
+// Derived stores
+export const activeDownloads = derived(downloads, ($d) =>
+  Object.values($d.downloads).filter((d) => d.status === 'downloading')
+);
+```
+
+**Event Handling**:
+
+The store listens to Tauri events for real-time updates:
+
+```typescript
+listen<DownloadEvent>('download-event', (event) => {
+  const payload = event.payload;
+
+  switch (payload.type) {
+    case 'started':
+      // Update status to 'downloading'
+    case 'progress':
+      // Update progress and bytes_downloaded
+    case 'completed':
+      // Update status to 'completed', progress to 1.0
+    case 'failed':
+      // Update status to 'failed', store error message
+  }
+});
+```
+
+## Download UI Components
+
+**DownloadButton** (`src/lib/components/library/DownloadButton.svelte`):
+- Multiple states: available, downloading, completed, failed, paused
+- Circular progress ring during download
+- Size variants: sm, md, lg
+- Integrated into TrackList with `showDownload={true}` prop
+
+**DownloadItem** (`src/lib/components/downloads/DownloadItem.svelte`):
+- Individual download list item with progress bar
+- Action buttons: pause, resume, cancel, delete
+- Status indicators with color coding
+
+**Downloads Page** (`src/routes/downloads/+page.svelte`):
+- Active/Completed tabs
+- Bulk actions: Pause All, Resume All, Clear Completed
+- Empty states with helpful instructions
+
+## Database Schema
+
+**downloads table**:
+
+```sql
+CREATE TABLE downloads (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id         TEXT NOT NULL,
+    user_id         TEXT NOT NULL,
+    file_path       TEXT,
+    file_size       INTEGER,
+    mime_type       TEXT,
+    status          TEXT DEFAULT 'pending',  -- pending, downloading, completed, failed, paused
+    progress        REAL DEFAULT 0.0,
+    bytes_downloaded INTEGER DEFAULT 0,
+    priority        INTEGER DEFAULT 0,
+    error_message   TEXT,
+    retry_count     INTEGER DEFAULT 0,
+    queued_at       TEXT DEFAULT CURRENT_TIMESTAMP,
+    started_at      TEXT,
+    completed_at    TEXT
+);
+
+CREATE INDEX idx_downloads_queue
+  ON downloads(status, priority DESC, queued_at ASC)
+  WHERE status IN ('pending', 'downloading');
+```

docs/architecture/07-connectivity.md

@@ -0,0 +1,127 @@
+# Connectivity & Network Architecture
+
+## HTTP Client with Retry Logic
+
+**Location**: `src-tauri/src/jellyfin/http_client.rs`
+
+The HTTP client provides automatic retry with exponential backoff for network resilience:
+
+```rust
+pub struct HttpClient {
+    client: reqwest::Client,
+    config: HttpConfig,
+}
+
+pub struct HttpConfig {
+    pub timeout: Duration,        // Default: 30s (large library queries can be slow)
+    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
+- No retry on: 4xx client errors, 401/403 authentication errors
+
+**Error Classification:**
+```rust
+pub enum ErrorKind {
+    Network,        // Connection failures, timeouts, DNS errors
+    Authentication, // 401/403 responses
+    Server,         // 5xx server errors
+    Client,         // Other 4xx errors
+}
+```
+
+## Connectivity Monitor
+
+**Location**: `src-tauri/src/connectivity/mod.rs`
+
+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
+    Repo["OnlineRepository"] -->|"success / RepoError"| Monitor["ConnectivityMonitor"]
+    Monitor --> State{"is_server_reachable?"}
+    State -->|"Online"| NoProbe["No background polling<br/>(real traffic is the signal)"]
+    State -->|"Offline"| Probe["5s /System/Info/Public probe<br/>(recovery detector)"]
+    Probe -->|"reachable again"| Monitor
+    Monitor -->|"on change"| Emit["Emit connectivity:changed<br/>+ connectivity:reconnected"]
+    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:**
+- **Traffic-driven**: Reachability follows the requests the user actually makes.
+- **Time-window debounce**: Offline declared only after `OFFLINE_CONFIRM_WINDOW` (5s) of sustained network failure; recovery is instant.
+- **Offline-only probe**: 5s `/System/Info/Public` probe runs only while offline.
+- **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 (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 the offline recovery probe |
+| `connectivity_stop_monitoring` | Stop the probe |
+| `connectivity_mark_reachable` | Mark reachable — driven by `OnlineRepository` on every server success |
+| `connectivity_mark_unreachable` | Mark unreachable — driven by `OnlineRepository` on `RepoError::Network` (subject to debounce) |
+
+**Frontend Integration:**
+```typescript
+// 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);
+});
+```
+
+## Network Resilience Architecture
+
+The connectivity system provides resilience through multiple layers:
+
+1. **HTTP Client Layer**: Automatic retry with exponential backoff
+2. **Connectivity Monitoring**: Reachability derived from real repository traffic, with an offline-only recovery probe
+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:**
+- **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 Fast**: Don't retry 4xx errors (client errors, authentication).
+- **Fail Slow**: Retry network and 5xx errors with increasing delays.
+- **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.

docs/architecture/08-database-design.md

@@ -0,0 +1,614 @@
+# Offline Database Design
+
+## Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    servers ||--o{ users : "has"
+    servers ||--o{ libraries : "has"
+    libraries ||--o{ items : "contains"
+    items ||--o{ items : "parent_of"
+    items ||--o{ user_data : "has"
+    items ||--o{ downloads : "has"
+    items ||--o{ media_streams : "has"
+    items ||--o{ thumbnails : "has"
+    users ||--o{ user_data : "owns"
+    users ||--o{ downloads : "owns"
+    users ||--o{ sync_queue : "owns"
+
+    servers {
+        int id PK
+        string jellyfin_id UK
+        string name
+        string url
+        string version
+        datetime last_sync
+    }
+
+    users {
+        int id PK
+        string jellyfin_id
+        int server_id FK
+        string name
+        boolean is_active
+    }
+
+    libraries {
+        int id PK
+        string jellyfin_id
+        int server_id FK
+        string name
+        string collection_type
+        string image_tag
+    }
+
+    items {
+        int id PK
+        string jellyfin_id
+        int server_id FK
+        int library_id FK
+        int parent_id FK
+        string type
+        string name
+        string sort_name
+        string overview
+        int production_year
+        float community_rating
+        string official_rating
+        int runtime_ticks
+        string primary_image_tag
+        string backdrop_image_tag
+        string album_id
+        string album_name
+        string album_artist
+        json artists
+        json genres
+        int index_number
+        int parent_index_number
+        string premiere_date
+        json metadata_json
+        datetime created_at
+        datetime updated_at
+        datetime last_sync
+    }
+
+    user_data {
+        int id PK
+        int item_id FK
+        int user_id FK
+        int position_ticks
+        int play_count
+        boolean is_favorite
+        boolean played
+        datetime last_played
+        datetime updated_at
+        datetime synced_at
+    }
+
+    downloads {
+        int id PK
+        int item_id FK
+        int user_id FK
+        string file_path
+        int file_size
+        string status
+        float progress
+        int priority
+        string error_message
+        datetime created_at
+        datetime completed_at
+    }
+
+    media_streams {
+        int id PK
+        int item_id FK
+        int stream_index
+        string type
+        string codec
+        string language
+        string display_title
+        boolean is_default
+        boolean is_forced
+        boolean is_external
+    }
+
+    sync_queue {
+        int id PK
+        int user_id FK
+        string operation
+        string entity_type
+        string entity_id
+        json payload
+        datetime created_at
+        int attempts
+        datetime last_attempt
+        string status
+    }
+
+    thumbnails {
+        int id PK
+        int item_id FK
+        string image_type
+        string image_tag
+        string file_path
+        int width
+        int height
+        datetime cached_at
+    }
+```
+
+## Table Definitions
+
+### servers
+Stores connected Jellyfin server information.
+
+```sql
+CREATE TABLE servers (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    jellyfin_id     TEXT NOT NULL UNIQUE,
+    name            TEXT NOT NULL,
+    url             TEXT NOT NULL,
+    version         TEXT,
+    last_sync       DATETIME,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### users
+Stores user accounts per server. Access tokens are stored separately in secure storage (see [09-security.md](09-security.md)).
+
+```sql
+CREATE TABLE users (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    jellyfin_id     TEXT NOT NULL,
+    server_id       INTEGER NOT NULL REFERENCES servers(id) ON DELETE CASCADE,
+    name            TEXT NOT NULL,
+    is_active       BOOLEAN DEFAULT 0,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(jellyfin_id, server_id)
+);
+```
+
+### libraries
+Stores library/collection metadata.
+
+```sql
+CREATE TABLE libraries (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    jellyfin_id     TEXT NOT NULL,
+    server_id       INTEGER NOT NULL REFERENCES servers(id) ON DELETE CASCADE,
+    name            TEXT NOT NULL,
+    collection_type TEXT,
+    image_tag       TEXT,
+    sort_order      INTEGER DEFAULT 0,
+    last_sync       DATETIME,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(jellyfin_id, server_id)
+);
+
+CREATE INDEX idx_libraries_server ON libraries(server_id);
+```
+
+### items
+Main table for all media items (movies, episodes, albums, songs, etc.).
+
+```sql
+CREATE TABLE items (
+    id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+    jellyfin_id          TEXT NOT NULL,
+    server_id            INTEGER NOT NULL REFERENCES servers(id) ON DELETE CASCADE,
+    library_id           INTEGER REFERENCES libraries(id) ON DELETE SET NULL,
+    parent_id            INTEGER REFERENCES items(id) ON DELETE CASCADE,
+
+    -- Basic metadata
+    type                 TEXT NOT NULL,
+    name                 TEXT NOT NULL,
+    sort_name            TEXT,
+    overview             TEXT,
+
+    -- Media info
+    production_year      INTEGER,
+    community_rating     REAL,
+    official_rating      TEXT,
+    runtime_ticks        INTEGER,
+
+    -- Images
+    primary_image_tag    TEXT,
+    backdrop_image_tag   TEXT,
+
+    -- Audio-specific
+    album_id             TEXT,
+    album_name           TEXT,
+    album_artist         TEXT,
+    artists              TEXT,                   -- JSON array
+
+    -- Series/Season-specific
+    index_number         INTEGER,
+    parent_index_number  INTEGER,
+    series_id            TEXT,
+    series_name          TEXT,
+    season_id            TEXT,
+
+    -- Additional
+    genres               TEXT,                   -- JSON array
+    premiere_date        TEXT,
+    metadata_json        TEXT,
+
+    -- Sync tracking
+    created_at           DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at           DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_sync            DATETIME,
+
+    UNIQUE(jellyfin_id, server_id)
+);
+
+-- Performance indexes
+CREATE INDEX idx_items_server ON items(server_id);
+CREATE INDEX idx_items_library ON items(library_id);
+CREATE INDEX idx_items_parent ON items(parent_id);
+CREATE INDEX idx_items_type ON items(type);
+CREATE INDEX idx_items_album ON items(album_id);
+CREATE INDEX idx_items_series ON items(series_id);
+CREATE INDEX idx_items_name ON items(name COLLATE NOCASE);
+
+-- Full-text search
+CREATE VIRTUAL TABLE items_fts USING fts5(
+    name,
+    overview,
+    artists,
+    album_name,
+    album_artist,
+    content='items',
+    content_rowid='id'
+);
+
+-- Triggers to keep FTS in sync
+CREATE TRIGGER items_ai AFTER INSERT ON items BEGIN
+    INSERT INTO items_fts(rowid, name, overview, artists, album_name, album_artist)
+    VALUES (new.id, new.name, new.overview, new.artists, new.album_name, new.album_artist);
+END;
+
+CREATE TRIGGER items_ad AFTER DELETE ON items BEGIN
+    INSERT INTO items_fts(items_fts, rowid, name, overview, artists, album_name, album_artist)
+    VALUES ('delete', old.id, old.name, old.overview, old.artists, old.album_name, old.album_artist);
+END;
+
+CREATE TRIGGER items_au AFTER UPDATE ON items BEGIN
+    INSERT INTO items_fts(items_fts, rowid, name, overview, artists, album_name, album_artist)
+    VALUES ('delete', old.id, old.name, old.overview, old.artists, old.album_name, old.album_artist);
+    INSERT INTO items_fts(rowid, name, overview, artists, album_name, album_artist)
+    VALUES (new.id, new.name, new.overview, new.artists, new.album_name, new.album_artist);
+END;
+```
+
+### media_streams
+Stores subtitle and audio track information for items.
+
+```sql
+CREATE TABLE media_streams (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id         INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+    stream_index    INTEGER NOT NULL,
+    type            TEXT NOT NULL,
+    codec           TEXT,
+    language        TEXT,
+    display_title   TEXT,
+    is_default      BOOLEAN DEFAULT 0,
+    is_forced       BOOLEAN DEFAULT 0,
+    is_external     BOOLEAN DEFAULT 0,
+    path            TEXT,
+    UNIQUE(item_id, stream_index)
+);
+
+CREATE INDEX idx_media_streams_item ON media_streams(item_id);
+```
+
+### user_data
+Stores per-user data for items (favorites, progress, play count).
+
+```sql
+CREATE TABLE user_data (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id         INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+    user_id         INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+
+    -- Playback state
+    position_ticks  INTEGER DEFAULT 0,
+    play_count      INTEGER DEFAULT 0,
+    played          BOOLEAN DEFAULT 0,
+    last_played     DATETIME,
+
+    -- User preferences
+    is_favorite     BOOLEAN DEFAULT 0,
+    user_rating     REAL,
+
+    -- Sync tracking
+    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    synced_at       DATETIME,
+    needs_sync      BOOLEAN DEFAULT 0,
+
+    UNIQUE(item_id, user_id)
+);
+
+CREATE INDEX idx_user_data_item ON user_data(item_id);
+CREATE INDEX idx_user_data_user ON user_data(user_id);
+CREATE INDEX idx_user_data_needs_sync ON user_data(needs_sync) WHERE needs_sync = 1;
+CREATE INDEX idx_user_data_favorites ON user_data(user_id, is_favorite) WHERE is_favorite = 1;
+CREATE INDEX idx_user_data_in_progress ON user_data(user_id, position_ticks)
+    WHERE position_ticks > 0 AND played = 0;
+```
+
+### downloads
+Tracks downloaded media files.
+
+```sql
+CREATE TABLE downloads (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id         INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+    user_id         INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+
+    file_path       TEXT,
+    file_size       INTEGER,
+    file_hash       TEXT,
+
+    status          TEXT NOT NULL DEFAULT 'pending',
+    progress        REAL DEFAULT 0,
+    bytes_downloaded INTEGER DEFAULT 0,
+
+    transcode_profile TEXT,
+
+    priority        INTEGER DEFAULT 0,
+    error_message   TEXT,
+    retry_count     INTEGER DEFAULT 0,
+
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    started_at      DATETIME,
+    completed_at    DATETIME,
+    expires_at      DATETIME,
+
+    UNIQUE(item_id, user_id)
+);
+
+CREATE INDEX idx_downloads_status ON downloads(status);
+CREATE INDEX idx_downloads_user ON downloads(user_id);
+CREATE INDEX idx_downloads_queue ON downloads(status, priority DESC, created_at ASC)
+    WHERE status IN ('pending', 'downloading');
+```
+
+### sync_queue
+Stores mutations to sync back to server when online.
+
+```sql
+CREATE TABLE sync_queue (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id         INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+
+    operation       TEXT NOT NULL,
+    entity_type     TEXT NOT NULL,
+    entity_id       TEXT NOT NULL,
+    payload         TEXT,
+
+    status          TEXT DEFAULT 'pending',
+    attempts        INTEGER DEFAULT 0,
+    max_attempts    INTEGER DEFAULT 5,
+    last_attempt    DATETIME,
+    error_message   TEXT,
+
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    completed_at    DATETIME
+);
+
+CREATE INDEX idx_sync_queue_status ON sync_queue(status, created_at ASC)
+    WHERE status = 'pending';
+CREATE INDEX idx_sync_queue_user ON sync_queue(user_id);
+```
+
+### thumbnails
+Caches downloaded artwork.
+
+```sql
+CREATE TABLE thumbnails (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id         INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+    image_type      TEXT NOT NULL,
+    image_tag       TEXT,
+    file_path       TEXT NOT NULL,
+    width           INTEGER,
+    height          INTEGER,
+    file_size       INTEGER,
+    cached_at       DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_accessed   DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(item_id, image_type, width)
+);
+
+CREATE INDEX idx_thumbnails_item ON thumbnails(item_id);
+CREATE INDEX idx_thumbnails_lru ON thumbnails(last_accessed ASC);
+```
+
+### playlists (for local/synced playlists)
+
+```sql
+CREATE TABLE playlists (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    jellyfin_id     TEXT,
+    user_id         INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name            TEXT NOT NULL,
+    description     TEXT,
+    is_local_only   BOOLEAN DEFAULT 0,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    synced_at       DATETIME,
+    needs_sync      BOOLEAN DEFAULT 0
+);
+
+CREATE TABLE playlist_items (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    playlist_id     INTEGER NOT NULL REFERENCES playlists(id) ON DELETE CASCADE,
+    item_id         INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+    sort_order      INTEGER NOT NULL,
+    added_at        DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(playlist_id, item_id)
+);
+
+CREATE INDEX idx_playlist_items_playlist ON playlist_items(playlist_id, sort_order);
+```
+
+## Key Queries
+
+### Get items for offline library browsing
+```sql
+-- Get all albums in a music library
+SELECT * FROM items
+WHERE library_id = ? AND type = 'MusicAlbum'
+ORDER BY sort_name;
+
+-- Get tracks for an album
+SELECT * FROM items
+WHERE album_id = ? AND type = 'Audio'
+ORDER BY parent_index_number, index_number;
+```
+
+### Resume / Continue Watching
+```sql
+SELECT i.*, ud.position_ticks, ud.last_played
+FROM items i
+JOIN user_data ud ON ud.item_id = i.id
+WHERE ud.user_id = ?
+  AND ud.position_ticks > 0
+  AND ud.played = 0
+ORDER BY ud.last_played DESC
+LIMIT 20;
+```
+
+### Offline search
+```sql
+SELECT i.* FROM items i
+JOIN items_fts fts ON fts.rowid = i.id
+WHERE items_fts MATCH ?
+ORDER BY rank;
+```
+
+### Download queue management
+```sql
+-- Get next item to download
+SELECT d.*, i.name, i.type
+FROM downloads d
+JOIN items i ON i.id = d.item_id
+WHERE d.status = 'pending'
+ORDER BY d.priority DESC, d.created_at ASC
+LIMIT 1;
+
+-- Get download progress for UI
+SELECT
+    d.status,
+    COUNT(*) as count,
+    SUM(d.file_size) as total_size,
+    SUM(d.bytes_downloaded) as downloaded
+FROM downloads d
+WHERE d.user_id = ?
+GROUP BY d.status;
+```
+
+### Sync queue processing
+```sql
+-- Get pending sync operations (oldest first)
+SELECT * FROM sync_queue
+WHERE status = 'pending'
+  AND attempts < max_attempts
+ORDER BY created_at ASC
+LIMIT 10;
+
+-- Mark operation complete
+UPDATE sync_queue
+SET status = 'completed', completed_at = CURRENT_TIMESTAMP
+WHERE id = ?;
+```
+
+## Data Flow
+
+### Online Mode
+
+```mermaid
+flowchart TB
+    subgraph OnlineMode["Online Mode"]
+        JellyfinServer["Jellyfin Server"]
+        OnlineRepo["OnlineRepo"]
+        SQLite["SQLite"]
+        HybridRepo["HybridRepository"]
+        UI["UI / Stores"]
+
+        JellyfinServer -->|"API Response"| OnlineRepo
+        OnlineRepo -->|"Cache"| SQLite
+        SQLite -->|"Sync"| JellyfinServer
+        OnlineRepo -->|"Response"| HybridRepo
+        SQLite -->|"Fallback"| HybridRepo
+        HybridRepo --> UI
+    end
+```
+
+### Offline Mode
+
+```mermaid
+flowchart TB
+    subgraph OfflineMode["Offline Mode"]
+        OfflineRepo["OfflineRepo"]
+        SQLite2["SQLite"]
+        SyncQueue["sync_queue<br/>(Queued for later)"]
+        HybridRepo2["HybridRepository"]
+        UI2["UI / Stores"]
+
+        OfflineRepo <-->|"Query"| SQLite2
+        SQLite2 -->|"Mutations"| SyncQueue
+        OfflineRepo --> HybridRepo2
+        HybridRepo2 --> UI2
+    end
+```
+
+### Sync on Reconnect
+
+```mermaid
+flowchart LR
+    NetworkRestored["Network restored"]
+    SyncService["SyncService"]
+    SyncQueue2["sync_queue"]
+    JellyfinAPI["Jellyfin API"]
+    MarkSynced["Mark synced"]
+
+    NetworkRestored --> SyncService
+    SyncService -->|"Read"| SyncQueue2
+    SyncQueue2 -->|"Send"| JellyfinAPI
+    JellyfinAPI -->|"Success"| MarkSynced
+    MarkSynced --> SyncService
+```
+
+## Storage Estimates
+
+| Content Type | Metadata Size | Thumbnail Size | Media Size |
+|--------------|---------------|----------------|------------|
+| Song | ~2 KB | ~50 KB (300px) | 5-15 MB |
+| Album (12 tracks) | ~30 KB | ~100 KB | 60-180 MB |
+| Movie | ~5 KB | ~200 KB | 1-8 GB |
+| Episode | ~3 KB | ~100 KB | 300 MB - 2 GB |
+| Full music library (5000 songs) | ~10 MB | ~250 MB | 25-75 GB |
+
+## Rust Module Structure
+
+```
+src-tauri/src/storage/
+├── mod.rs              # Module exports, Database struct
+├── schema.rs           # Table definitions, migrations
+├── models.rs           # Rust structs matching tables
+├── queries/
+│   ├── mod.rs
+│   ├── items.rs        # Item CRUD operations
+│   ├── user_data.rs    # User data operations
+│   ├── downloads.rs    # Download queue operations
+│   └── sync.rs         # Sync queue operations
+└── sync/
+    ├── mod.rs          # SyncService
+    ├── manager.rs      # Background sync manager
+    └── operations.rs   # Individual sync operation handlers
+```

docs/architecture/09-security.md

@@ -0,0 +1,69 @@
+# Security
+
+## Authentication Token Storage
+
+Access tokens are **not** stored in the SQLite database. Instead, they are stored using platform-native secure storage:
+
+```mermaid
+flowchart TB
+    LoginSuccess["Login Success"]
+    KeyringCheck{"System Keyring<br/>Available?"}
+    OSCredential["Store in OS Credential Manager<br/>- Linux: libsecret/GNOME Keyring<br/>- macOS: Keychain<br/>- Windows: Credential Manager<br/>- Android: EncryptedSharedPrefs"]
+    EncryptedFallback["Encrypted File Fallback<br/>(AES-256-GCM)"]
+
+    LoginSuccess --> KeyringCheck
+    KeyringCheck -->|"Yes"| OSCredential
+    KeyringCheck -->|"No"| EncryptedFallback
+```
+
+**Key Format:**
+```
+jellytau::{server_id}::{user_id}::access_token
+```
+
+**Rationale:**
+- Tokens in SQLite would be readable if the database file is accessed
+- System keyrings provide OS-level encryption and access control
+- Fallback ensures functionality on minimal systems without a keyring daemon
+
+## Secure Storage Module
+
+**Location**: `src-tauri/src/secure_storage/` (planned)
+
+```rust
+pub trait SecureStorage: Send + Sync {
+    fn store(&self, key: &str, value: &str) -> Result<(), SecureStorageError>;
+    fn retrieve(&self, key: &str) -> Result<Option<String>, SecureStorageError>;
+    fn delete(&self, key: &str) -> Result<(), SecureStorageError>;
+}
+
+// Platform implementations
+pub struct KeyringStorage;      // Uses keyring crate
+pub struct EncryptedFileStorage; // AES-256-GCM fallback
+```
+
+## Network Security
+
+| Aspect | Implementation |
+|--------|----------------|
+| Transport | HTTPS required for all Jellyfin API calls |
+| Certificate Validation | System CA store (configurable for self-signed) |
+| Token Transmission | Bearer token in `Authorization` header only |
+| Token Refresh | Handled by Jellyfin server (long-lived tokens) |
+
+## Local Data Protection
+
+| Data Type | Protection |
+|-----------|------------|
+| Access Tokens | System keyring or encrypted file |
+| Database (SQLite) | Plaintext (metadata only, no secrets) |
+| Downloaded Media | Filesystem permissions only |
+| Cached Thumbnails | Filesystem permissions only |
+
+## Security Considerations
+
+1. **No Secrets in SQLite**: The database contains only non-sensitive metadata
+2. **Token Isolation**: Each user/server combination has a separate token entry
+3. **Logout Cleanup**: Token deletion from secure storage on logout
+4. **No Token Logging**: Tokens are never written to logs or debug output
+5. **IPC Security**: Tauri's IPC uses structured commands, not arbitrary code execution

docs/architecture/README.md

@@ -0,0 +1,210 @@
+# JellyTau Software Architecture
+
+This document describes the current architecture of JellyTau, a cross-platform Jellyfin client built with Tauri, SvelteKit, and Rust.
+
+**Last Updated:** 2026-06-20
+
+## Architecture Overview
+
+JellyTau uses a client-server architecture: business logic lives in a comprehensive Rust backend, while a UI-rich Svelte frontend handles presentation and interaction.
+
+### Architecture Principles
+
+- **Business Logic in Rust**: Core logic — playback, repository, sync, downloads, connectivity — lives in Rust for performance, reliability, and type safety.
+- **Presentation in Svelte**: The frontend (~20.5k non-test lines) owns UI, layout, navigation, and interaction state and invokes Rust commands. It is intentionally UI-heavy, **not** a thin wrapper. Largest pieces: components + routes (~14.6k lines), stores (~3.4k), api/services/utils (~2.4k); `VideoPlayer.svelte` alone is ~1.6k lines.
+- **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`).
+- **Unified player boundary**: UI components control playback only through the frontend facade `src/lib/player/index.ts` (`playerController`), never by calling `commands.player*` directly. Webview-rendered HTML5 video reports its state back into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*` commands, so the `PlayerController` stays the single source of truth in both native (MPV/ExoPlayer) and HTML5 modes (see [05-platform-backends.md](05-platform-backends.md)).
+- **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.
+
+```mermaid
+flowchart TB
+    subgraph Frontend["Svelte Frontend"]
+        subgraph Stores["Stores (Thin Wrappers)"]
+            auth["auth"]
+            player["player"]
+            queue["queue"]
+            library["library"]
+            connectivity["connectivity"]
+            playbackMode["playbackMode"]
+        end
+        subgraph Components
+            playerComp["player/"]
+            libraryComp["library/"]
+            Search["Search"]
+        end
+        subgraph Routes
+            routeLibrary["/library"]
+            routePlayer["/player"]
+            routeRoot["/"]
+        end
+        subgraph API["API Layer (Thin Client)"]
+            RepositoryClient["RepositoryClient<br/>(Handle-based)"]
+            JellyfinClient["JellyfinClient<br/>(Helper)"]
+        end
+    end
+
+    Frontend -->|"Tauri IPC (invoke)"| Backend
+
+    subgraph Backend["Rust Backend (Business Logic)"]
+        subgraph Commands["Tauri Commands (90+)"]
+            PlayerCmds["player.rs"]
+            RepoCmds["repository.rs (27)"]
+            PlaybackModeCmds["playback_mode.rs (5)"]
+            StorageCmds["storage.rs"]
+            ConnectivityCmds["connectivity.rs (7)"]
+        end
+
+        subgraph Core["Core Modules"]
+            MediaSessionManager["MediaSessionManager<br/>(Audio/Movie/TvShow/Idle)"]
+
+            PlayerController["PlayerController<br/>+ PlayerBackend<br/>+ QueueManager"]
+
+            Repository["Repository Layer<br/>HybridRepository (cache-first)<br/>OnlineRepository (HTTP)<br/>OfflineRepository (SQLite)"]
+
+            PlaybackModeManager["PlaybackModeManager<br/>(Local/Remote/Idle)"]
+
+            ConnectivityMonitor["ConnectivityMonitor<br/>(Adaptive polling)"]
+
+            HttpClient["HttpClient<br/>(Exponential backoff retry)"]
+        end
+
+        subgraph Storage["Storage Layer"]
+            DatabaseService["DatabaseService<br/>(Async trait)"]
+            SQLite["SQLite Database<br/>(13 tables)"]
+        end
+
+        Commands --> Core
+        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 in this directory:
+
+| Document | Contents |
+|----------|----------|
+| [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](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](03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
+| [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](05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
+| [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](07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
+| [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](09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
+
+---
+
+## File Structure Summary
+
+```
+src-tauri/src/
+├── lib.rs                    # Tauri app setup, state initialization
+├── commands/                 # Tauri command handlers (90+ commands)
+│   ├── mod.rs               # Command exports
+│   ├── player.rs            # 16 player commands
+│   ├── repository.rs        # 27 repository commands
+│   ├── playlist.rs          # 7 playlist commands
+│   ├── playback_mode.rs     # 5 playback mode commands
+│   ├── connectivity.rs      # 7 connectivity commands
+│   ├── storage.rs           # Storage & database commands
+│   ├── download.rs          # 7 download commands
+│   ├── offline.rs           # 3 offline commands
+│   └── sync.rs              # Sync queue commands
+├── repository/              # Repository pattern implementation
+│   ├── mod.rs               # MediaRepository trait, handle management
+│   ├── types.rs             # RepoError, Library, MediaItem, etc.
+│   ├── hybrid.rs            # HybridRepository with cache-first racing
+│   ├── online.rs            # OnlineRepository (HTTP API)
+│   └── offline.rs           # OfflineRepository (SQLite queries)
+├── playback_mode/           # Playback mode manager
+│   └── mod.rs               # PlaybackMode enum, transfer logic
+├── connectivity/            # Connectivity monitoring
+│   └── mod.rs               # ConnectivityMonitor, adaptive polling
+├── jellyfin/                # Jellyfin API client
+│   ├── mod.rs               # Module exports
+│   ├── http_client.rs       # HTTP client with retry logic
+│   └── client.rs            # JellyfinClient for API calls
+├── storage/                 # Database layer
+│   ├── mod.rs               # Database struct, migrations
+│   ├── db_service.rs        # DatabaseService trait (async wrapper)
+│   ├── schema.rs            # Table definitions
+│   └── queries/             # Query modules
+├── download/                # Download manager module
+│   ├── mod.rs               # DownloadManager, DownloadInfo, DownloadTask
+│   ├── worker.rs            # DownloadWorker, HTTP streaming, retry logic
+│   ├── events.rs            # DownloadEvent enum
+│   └── cache.rs             # SmartCache, CacheConfig, LRU eviction
+└── player/                  # Player subsystem
+    ├── mod.rs               # PlayerController
+    ├── session.rs           # MediaSessionManager, MediaSessionType
+    ├── state.rs             # PlayerState, PlayerEvent
+    ├── media.rs             # MediaItem, MediaSource, MediaType
+    ├── queue.rs             # QueueManager, RepeatMode
+    ├── backend.rs           # PlayerBackend trait, NullBackend
+    ├── events.rs            # PlayerStatusEvent, TauriEventEmitter
+    ├── mpv/                 # Linux MPV backend
+    │   ├── mod.rs           # MpvBackend implementation
+    │   └── event_loop.rs    # Dedicated thread for MPV operations
+    └── android/             # Android ExoPlayer backend
+        └── mod.rs           # ExoPlayerBackend + JNI bindings
+
+src/lib/
+├── api/                     # Thin API layer (~200 lines total)
+│   ├── types.ts             # TypeScript type definitions
+│   ├── repository-client.ts # RepositoryClient wrapper (~100 lines)
+│   ├── client.ts            # JellyfinClient (helper for streaming)
+│   └── sessions.ts          # SessionsApi (remote session control)
+├── player/                  # Unified player boundary (frontend)
+│   ├── index.ts             # playerController facade — the only write-side entry point for playback
+│   └── html5Adapter.ts      # Reports webview <video> DOM events back into Rust (player_report_*)
+├── services/
+│   ├── playerEvents.ts      # Tauri event listener for player events
+│   └── playbackReporting.ts # Thin wrapper (~50 lines)
+├── stores/                  # Thin reactive wrappers over Rust commands
+│   ├── index.ts             # Re-exports
+│   ├── auth.ts              # Auth store (calls Rust commands)
+│   ├── player.ts            # Player store
+│   ├── queue.ts             # Queue store
+│   ├── library.ts           # Library store
+│   ├── playbackMode.ts      # Playback mode store (~150 lines)
+│   ├── connectivity.ts      # Connectivity store (~250 lines)
+│   └── downloads.ts         # Downloads store with event listeners
+└── components/
+    ├── Search.svelte
+    ├── player/              # Player UI components
+    ├── playlist/            # Playlist modals (Create, AddTo)
+    ├── sessions/            # Remote session control UI
+    ├── downloads/           # Download UI components
+    └── library/             # Library UI components + PlaylistDetailView
+```
+
+## Key Architecture Changes
+
+**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) - 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
+
+**Svelte/TypeScript frontend (~20.5k non-test lines, plus ~9.6k test lines):**
+- Components + routes (~14.6k lines) — UI and presentation
+- Stores (~3.4k lines) — reactive state that invokes Rust commands and listens for events
+- api / services / utils (~2.4k lines) — typed clients, event listeners, conversion helpers
+
+The frontend is genuinely UI-heavy; business decisions live in Rust, but the UI owns layout, navigation, and interaction state.
+
+**Total Commands:** 90+ Tauri commands across 14 command modules

docs/build/docker.md

@@ -13,7 +13,7 @@ The setup includes:
 ### Quick Start
 
 **For CI/CD (Gitea Actions)**:
-1. Build and push builder image (see [BUILD-BUILDER-IMAGE.md](BUILD-BUILDER-IMAGE.md))
+1. Build and push builder image (see [build-builder-image.md](build-builder-image.md))
 2. Push to master branch - workflow runs automatically
 3. Check Actions tab for results and APK artifacts
 
@@ -133,7 +133,7 @@ docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-build
 docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 ```
 
-See [BUILD-BUILDER-IMAGE.md](BUILD-BUILDER-IMAGE.md) for detailed instructions.
+See [build-builder-image.md](build-builder-image.md) for detailed instructions.
 
 ### Setting Up Gitea Act
 

docs/release-checklist.md

@@ -0,0 +1,300 @@
+# Release Checklist
+
+Quick reference for creating a JellyTau release.
+
+## Pre-Release (1-2 days before)
+
+- [ ] Code is on `master`/`main` branch
+- [ ] All feature branches are merged and tested
+- [ ] No failing tests locally: `bun run test` and `bun run test:rust`
+- [ ] Requirement traceability check passes: `bun run traces:json`
+- [ ] Type checking passes: `bun run check`
+
+## Update Version (Day before)
+
+- [ ] Decide on version number (semantic versioning)
+  - Example: `v1.2.0` (major.minor.patch)
+  - Example: `v1.0.0-rc1` (release candidate)
+  - Example: `v1.0.0-beta` (beta)
+
+- [ ] Update version in files:
+  ```bash
+  # Check these files for version numbers
+  cat package.json | grep version
+  cat src-tauri/tauri.conf.json | grep version
+  cat src-tauri/Cargo.toml | grep version
+  ```
+
+- [ ] Update `CHANGELOG.md`:
+  - [ ] Add section for new version
+  - [ ] List all features added
+  - [ ] List all bugs fixed
+  - [ ] List breaking changes (if any)
+  - [ ] Add upgrade instructions (if needed)
+  - [ ] Format: Markdown with clear sections
+
+- [ ] Update `README.md`:
+  - [ ] Update any version references
+  - [ ] Update feature list if applicable
+  - [ ] Update requirements if changed
+
+- [ ] Commit changes:
+  ```bash
+  git add .
+  git commit -m "Bump version to v1.2.0"
+  git push origin master
+  ```
+
+## Final Check Before Release
+
+- [ ] Run full test suite:
+  ```bash
+  bun run test          # Frontend tests
+  bun run test:rust     # Rust tests
+  bun run check         # Type checking
+  ```
+
+- [ ] Build locally (optional but recommended):
+  ```bash
+  # Test Linux build
+  bun run tauri build
+
+  # Test Android build
+  bun run tauri android build
+  ```
+
+- [ ] No uncommitted changes:
+  ```bash
+  git status  # Should show clean working directory
+  ```
+
+## Release (Tag & Push)
+
+```bash
+# 1. Create annotated tag with release notes
+git tag -a v1.2.0 -m "Release version 1.2.0
+
+Features:
+- New feature 1
+- New feature 2
+
+Fixes:
+- Fixed bug 1
+- Fixed bug 2
+
+Improvements:
+- Performance improvement 1
+- UI improvement 1
+
+Breaking Changes:
+- None (or list if applicable)
+
+Migration:
+- No action required (or include steps if applicable)"
+
+# 2. Push tag to trigger workflow
+git push origin v1.2.0
+
+# 3. Monitor in Gitea Actions
+# Go to Actions tab and watch the workflow run
+```
+
+## During Release (While Workflow Runs)
+
+- [ ] Watch workflow progress in Gitea Actions
+- [ ] Monitor for test failures
+- [ ] Monitor for build failures
+- [ ] Check build logs if any step fails
+
+## After Release (Workflow Complete)
+
+- [ ] Download artifacts from release page:
+  - [ ] `jellytau_*.AppImage` (Linux)
+  - [ ] `jellytau_*.deb` (Linux)
+  - [ ] `jellytau-release.apk` (Android)
+  - [ ] `jellytau-release.aab` (Android)
+
+- [ ] Basic testing of artifacts:
+  - [ ] Linux AppImage runs
+  - [ ] Linux DEB installs and runs
+  - [ ] Android APK installs (via `adb` or sideload)
+
+- [ ] Verify release page:
+  - [ ] Title is correct: "JellyTau vX.Y.Z"
+  - [ ] Release notes are formatted correctly
+  - [ ] All artifacts are uploaded
+  - [ ] Release type is correct (prerelease vs release)
+
+- [ ] Announce release:
+  - [ ] Post to relevant channels/communities
+  - [ ] Update website/docs
+  - [ ] Tag contributors if applicable
+
+## Rollback (If Issues Found)
+
+If critical issues are found after release:
+
+```bash
+# Option 1: Delete tag locally and remotely
+git tag -d v1.2.0
+git push origin :refs/tags/v1.2.0
+
+# Option 2: Mark as prerelease in release page
+# Then plan immediate patch release (v1.2.1)
+
+# Option 3: Create hotfix branch and release v1.2.1
+git checkout -b hotfix/v1.2.1
+# Fix issues
+git commit -m "Fix critical issue"
+git tag v1.2.1
+git push origin hotfix/v1.2.1 v1.2.1
+```
+
+## Version Examples
+
+### Major Release
+```
+v2.0.0 - Major version bump
+- Significant new features
+- Breaking API changes
+- Major UI redesign
+```
+
+### Minor Release
+```
+v1.2.0 - Feature release
+- New features
+- Backward compatible
+- Bug fixes
+```
+
+### Patch Release
+```
+v1.1.1 - Bug fix/patch
+- Bug fixes only
+- No new features
+- Backward compatible
+```
+
+### Pre-releases
+```
+v1.2.0-alpha    - Early development
+v1.2.0-beta     - Late development, feature complete
+v1.2.0-rc1      - Release candidate, minimal fixes only
+```
+
+## File Locations
+
+Key files for versioning:
+- `package.json` - Frontend version
+- `src-tauri/tauri.conf.json` - Tauri config version
+- `src-tauri/Cargo.toml` - Rust version
+- `CHANGELOG.md` - Release history
+- `README.md` - Project documentation
+
+## Troubleshooting
+
+### Tests Fail Before Release
+1. Don't push tag yet
+2. Fix failing tests locally
+3. Push fixes to master
+4. Re-run test suite
+5. Then tag and push
+
+### Build Fails in CI
+1. Check detailed logs in Gitea Actions
+2. Fix issue locally
+3. Delete tag: `git tag -d v1.2.0 && git push origin :refs/tags/v1.2.0`
+4. Push fix to master
+5. Create new tag with fix
+
+### Release Already Exists
+1. If workflow runs twice, artifacts may conflict
+2. Check release page
+3. If duplicates exist, delete and re-release
+
+### Artifacts Missing
+1. Check build logs for errors
+2. Verify platform-specific dependencies
+3. Delete tag and retry after fixes
+
+## Performance Tips
+
+- Tests: ~5-10 minutes
+- Linux build: ~10-15 minutes
+- Android build: ~15-20 minutes
+- Total release time: ~30-45 minutes
+
+First build takes longer (cache warming). Subsequent releases are faster due to caching.
+
+## Template: Release Notes
+
+```
+## 🎉 JellyTau vX.Y.Z
+
+### ✨ Features
+- New feature 1
+- New feature 2
+
+### 🐛 Bug Fixes
+- Fixed issue #123
+- Fixed issue #456
+
+### 🚀 Performance
+- Improvement 1
+- Improvement 2
+
+### 📱 Downloads
+- [Linux AppImage](#) - Run on any Linux
+- [Linux DEB](#) - Install on Ubuntu/Debian
+- [Android APK](#) - Install on Android devices
+- [Android AAB](#) - For Google Play Store
+
+### 📋 Requirements
+**Linux:** 64-bit, GLIBC 2.29+
+**Android:** 8.0+
+
+### 🔗 Links
+- [Changelog](../../CHANGELOG.md)
+- [Issues](../../issues)
+- [Discussion](../../discussions)
+
+---
+Built with Tauri, SvelteKit, and Rust 🦀
+```
+
+## Quick Commands
+
+```bash
+# View existing tags
+git tag -l
+
+# Create release locally (dry run)
+git tag -a v1.2.0 -m "Release v1.2.0" --dry-run
+
+# List commits since last tag
+git log v1.1.0..HEAD --oneline
+
+# Show tag details
+git show v1.2.0
+
+# Rename tag (if needed)
+git tag v1.2.0_old v1.2.0
+git tag -d v1.2.0
+git push origin v1.2.0_old v1.2.0
+
+# Delete tag locally and remotely
+git tag -d v1.2.0
+git push origin :refs/tags/v1.2.0
+```
+
+---
+
+**Tips:**
+- ✅ Always test locally before release
+- ✅ Use semantic versioning consistently
+- ✅ Document changes in CHANGELOG
+- ✅ Wait for full workflow completion
+- ✅ Test release artifacts before announcing
+
+**Remember:** A good release is a tested release! 🚀

docs/requirements.md

@@ -0,0 +1,489 @@
+# 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 |
+| UR-040 | Keep a video's audio playing when the app is backgrounded or the screen is locked, stopping video decode until the app returns to the foreground (per-player toggle; Android) | Medium | Done (pending device verification) |
+| UR-041 | Continue watching *locally-playing video* in a floating picture-in-picture window when leaving the app (Android) — PiP applies to video only, never to audio playback, library/menu browsing, or remote/cast sessions | Medium | Done |
+| UR-042 | Authenticate to a server and manage the session lifecycle (connect, log in, Quick Connect, background session verification, re-authenticate, log out) | High | Done |
+| UR-043 | Automatically detect server reachability and switch between online and offline operation without user intervention | High | Done |
+| UR-044 | Pin downloaded media so it is protected from automatic cache eviction | Low | Done |
+| UR-045 | Predictively pre-cache likely-next media (queue lookahead and album affinity) within a storage budget | Low | Done |
+| UR-046 | Group multiple remote players into a synchronized playback group (LMS SyncGroups) | Low | Done |
+| UR-047 | Manage multiple Jellyfin servers (add, list, remove) and switch the active server/account | Medium | Planned (backend store done; switcher UI pending) |
+
+---
+
+## 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 |
+| IR-025 | Android background-audio handoff: WebView `<video>` → native ExoPlayer foreground service on background/lock, and back on foreground (audio continues, video decode stops) | Platform | UR-040 | Done (pending device verification) |
+| IR-026 | Android picture-in-picture: auto-enter on user-leave-hint via `enterPictureInPictureMode`, **only while a local video surface is actively rendering** (never for audio-only playback, menu/library browsing, or remote/cast sessions — enforced by the native `canEnterPip` guard, re-checked at leave time); aspect-ratio sizing; a play/pause RemoteAction that **reflects live player play/pause state** (updated whenever playback state changes, not only on button press); WebView hide/restore on mode change | Platform | UR-041 | Done |
+| IR-027 | Jellyfin `/System/Info/Public` reachability probe used as an offline→online recovery detector | API | UR-043 | Done |
+| IR-028 | Jellyfin/LMS SyncGroups API client (list, create, join, unsync, dissolve sync groups) | API | UR-046 | Done |
+
+### 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 |
+| JA-032 | Get audio-only stream URL for a video item (selected audio-stream index) | MediaInfo | UR-040 | 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 |
+| DR-051 | Background-audio toggle button in the video player controls (suppresses auto-PiP while enabled) | UI | UR-040 | Done (pending device verification) |
+| DR-052 | Background-audio handoff state machine: on background/lock tear down the WebView `<video>`/HLS decode and start native audio-only playback at the current position; on foreground return position and resume `<video>`; exactly one audio source active at every transition (no dual audio) | Player | UR-040 | Done (pending device verification) |
+| DR-053 | PictureInPictureManager: `canEnterPip` gate (local video surface actively rendering — false for audio, browsing, and remote/cast), aspect-ratio clamp, a RemoteAction play/pause receiver whose icon reflects live player state (refreshed on every playback-state change while in PiP, not only on button press), WebView hide/restore, surface re-fit on exit; plus the `AndroidPictureInPicture` JS bridge and the PiP button (shown only when PiP is supported) in the video player | UI | UR-041 | Done |
+| DR-054 | Auth manager and session lifecycle: connect-to-server, login, Quick Connect verification poll (start/stop), session get/set, background session verifier, re-authenticate, logout | Auth | UR-042 | Done |
+| DR-055 | ConnectivityMonitor deriving reachability from real repository traffic, with online/offline state, mark-reachable/unreachable reporting, and a probe-based recovery poller active only while offline | Connectivity | UR-043 | Done |
+| DR-056 | Download pinning (pin/unpin/is-pinned) that excludes an item from smart-cache eviction | Storage | UR-044 | Done |
+| DR-057 | Smart cache manager: album-affinity tracking, queue-lookahead pre-cache, storage-limit enforcement, config, stats, and recommendations | Storage | UR-045 | Done |
+| DR-058 | Remote sync-group control (LMS SyncGroups): list, create, unsync a player, dissolve a group | Player | UR-046 | Done |
+| DR-059 | Playback-mode transfer state machine: get/set current mode, transferring guard, transfer-to-remote / transfer-to-local, remote session status | Player | UR-010 | Done |
+| DR-060 | Multi-server store and active-account selection: save/get/delete server, save/get user, set/get active user (per-server), active-session resolution | Storage | UR-047 | Partial (store done; server-switcher UI pending) |
+
+---
+
+## 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, DR-059 |
+| 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 |
+| UR-040 | IR-025 | DR-051, DR-052 |
+| UR-041 | IR-026 | DR-053 |
+| UR-042 | IR-009, IR-014 | DR-054 |
+| UR-043 | IR-027 | DR-055 |
+| UR-044 | - | DR-056 |
+| UR-045 | - | DR-057 |
+| UR-046 | IR-028 | DR-058 |
+| UR-047 | IR-013 | DR-060 |
+
+---
+
+## 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 |
+| UT-059 | Audio-only stream URL builder for a video item (selected audio-stream index) | JA-032, DR-052 | Pending |
+| UT-060 | Background-audio handoff state machine (background→audio, foreground→video; no dual audio) | DR-052 | Pending |
+| UT-061 | Background-audio Tauri command param naming (camelCase) | DR-052 | Pending |
+
+### 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 |
+| IT-013 | Background-audio handoff on Android: background/lock continues audio via native service and stops video decode; foreground resumes video at position | IR-025, UR-040 | 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

docs/specs/video-background-audio.md

@@ -0,0 +1,233 @@
+# Spec: Background audio for video playback (Android)
+
+**Status:** Draft
+**Scope:** Android only (v1). Linux noted as future work.
+**Branch base:** `android-picture-in-picture`
+**Requirements:** UR-040 → IR-025, JA-032, DR-051, DR-052 (see
+[requirements.md](../requirements.md)). Tests: UT-059, UT-060, UT-061, IT-013.
+
+## Summary
+
+Add a per-player toggle that lets the **audio** of a video keep playing when the
+app is backgrounded or the screen is locked, while **video decoding stops**.
+When the app returns to the foreground, video decoding resumes from the current
+audio position.
+
+This is the audio-first counterpart to the existing Picture-in-Picture feature
+(which keeps the *whole video* decoding in a floating window). The two are
+mutually exclusive: enabling background audio suppresses auto-PiP.
+
+## Motivation
+
+Users watching talk-heavy content (podcasts-as-video, lectures, music videos,
+concert films) want to lock the phone or switch apps and keep listening without
+draining battery on video decode or needing a visible floating window.
+
+## Background: how playback actually works here
+
+Two facts drive the entire design (verified in code, not assumed):
+
+1. **Video renders through the HTML5 `<video>` element in the WebView on both
+   platforms.** The native ExoPlayer *video* surface path is disabled — see the
+   INTERIM override in
+   [VideoPlayer.svelte](../../src/lib/components/player/VideoPlayer.svelte)
+   around the `playerPlayItem` response handling (`useHtml5Element` is forced
+   `true`, native backend is stopped). So "video decoding" == the WebView
+   `<video>` element, and the WebView is what Android suspends on background.
+
+2. **An Android WebView `<video>` element does not keep playing audio when the
+   app is backgrounded / locked.** The system throttles the WebView and media
+   pauses. Keeping audio alive in the background requires a **native foreground
+   media service**, which already exists for music:
+   [`JellyTauPlaybackService`](../../src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt)
+   +
+   [`JellyTauPlayer`](../../src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt)
+   (ExoPlayer) + `MediaSessionCompat`.
+
+**Therefore the design is a handoff**, not "keep the WebView alive": on
+background, stop the WebView `<video>` and start audio-only playback of the same
+item through the existing native ExoPlayer audio service; on foreground, hand
+back to the WebView `<video>`.
+
+This also aligns with the project's one-directional playback rule
+(`CLAUDE.md` → "Playback state is one-directional"): the currently-authoritative
+player (WebView element **or** native audio service) drives position; the UI and
+MediaSession consume it. The handoff is a change of *which* player is
+authoritative, and must transfer position cleanly.
+
+## User-facing behavior
+
+### The toggle
+
+- A toggle button in the video player controls (next to the existing PiP /
+  fullscreen buttons in
+  [VideoPlayer.svelte](../../src/lib/components/player/VideoPlayer.svelte)).
+- Icon: headphones / "audio-only" glyph. Two visual states (on/off).
+- **Visible only when** `isPipSupported()`-equivalent conditions hold — i.e.
+  Android with a native audio service available. Hidden on Linux in v1.
+- State is a UI preference on the player. Consider persisting the last choice
+  per user (see Open Questions) — v1 may default OFF each session.
+
+### When toggle is ON and the app goes to background / screen locks
+
+1. Auto-PiP is suppressed (see "Interaction with PiP").
+2. The WebView `<video>` is paused and its decode stopped (release the media
+   source so the decoder is freed, not merely `pause()`).
+3. Native audio-only playback of the same item starts at the current position,
+   through `JellyTauPlaybackService` (foreground notification + lockscreen
+   controls via the existing `MediaSessionCompat`).
+4. Lockscreen / notification shows the item with play/pause/seek, driven by the
+   native player (existing music behavior — reused, not rebuilt).
+
+### When toggle is ON and the app returns to foreground
+
+1. Native audio playback stops; its final position is captured.
+2. WebView `<video>` reloads/resumes at that position and continues as normal
+   audiovisual playback.
+3. Playback state (playing/paused) is preserved across the handoff.
+
+### When toggle is OFF (default)
+
+Current behavior is unchanged: backgrounding video auto-enters PiP
+(`onUserLeaveHint` → `PictureInPictureManager.enterPip`).
+
+## Interaction with PiP
+
+The toggle chooses one behavior or the other:
+
+- Toggle **ON** → call `AndroidPictureInPicture.setAutoEnterEnabled(false)` (the
+  bridge already exists,
+  [pictureInPicture.ts](../../src/lib/utils/pictureInPicture.ts) →
+  `setAutoEnterEnabled`). Background → audio handoff instead of PiP.
+- Toggle **OFF** → `setAutoEnterEnabled(true)`. Background → PiP (status quo).
+
+The frontend must also call `setAutoEnterEnabled(false)` on unmount if it left
+it enabled, and re-assert the correct value whenever the toggle changes, so a
+stale setting can't leak into the next player.
+
+> Note: `canEnterPip()` today requires `isPlayingVideo()` on the *native*
+> ExoPlayer, but video plays via the WebView, so native `isPlayingVideo()` is
+> false during normal playback. Confirm during implementation how auto-PiP is
+> actually triggering today (it may rely on a different signal), because the
+> background-audio handoff needs the same "is a local video active" signal to
+> know it should fire. **This is a load-bearing unknown — resolve it first
+> (Phase 0).**
+
+## Technical design
+
+### The audio-only stream
+
+Jellyfin can transcode/stream a video item as audio-only. Add a repository
+method (mirroring
+[`get_video_stream_url`](../../src-tauri/src/repository/online.rs) and
+[`get_audio_stream_url`](../../src-tauri/src/repository/mod.rs)) that returns an
+**audio-only stream URL for a video item** at a given audio-stream index — so
+the currently-selected audio track (`selectedAudioTrackIndex` in the player)
+carries over. Prefer direct-play of the audio stream where the container/codec
+allows; transcode to a broadly-supported audio codec otherwise.
+
+Position semantics must match between the WebView `<video>` timeline and the
+audio stream (account for the transcoded-HLS `seekOffset` model already in the
+player — see the `seekOffset` handling in `VideoPlayer.svelte`).
+
+### Backend command surface (Rust)
+
+New/extended `#[tauri::command]`s in `src-tauri/src/commands/player/` (follow the
+camelCase param rule and `Result<T, String>` convention):
+
+- `player_enter_background_audio(item_id, position_seconds, audio_stream_index)`
+  — stop WebView authority, start native audio-only playback at position; makes
+  the native player authoritative. Emits state via the existing player-event
+  channel so MediaSession/UI stay consumers.
+- `player_exit_background_audio() -> position_seconds` — stop native audio,
+  return final position for the WebView to resume from; restores WebView
+  authority.
+
+Reuse existing `player_play_*` / `player_stop` plumbing where possible rather
+than adding a parallel path.
+
+### Android native
+
+- Reuse `JellyTauPlaybackService` + `JellyTauPlayer` audio path
+  (`MediaSessionCompat`, foreground notification, audio-becoming-noisy, etc. —
+  all already implemented for music).
+- Add a bridge method (alongside `AndroidPictureInPicture`) or reuse an existing
+  one so the frontend can signal "prepare for background audio handoff" tied to
+  the Activity lifecycle (`onPause`/`onStop`/`onUserLeaveHint`).
+- On `onUserLeaveHint` / screen-off with background-audio enabled: **do not**
+  enter PiP; instead trigger the handoff command.
+- Respect the deadlock gotchas in `CLAUDE.md` (no sync/blocking calls from
+  player event callbacks; bind locked `AutoplayDecision` to a `let` before
+  matching).
+
+### Frontend (VideoPlayer.svelte)
+
+- Add toggle state + button. On change, call `setAutoEnterEnabled(!on)`.
+- Listen for Android lifecycle background/foreground signals (via a bridge event
+  or existing visibility hooks) and:
+  - background + ON → `player_enter_background_audio(...)`, pause + tear down the
+    `<video>`/HLS decode (reuse the existing HLS teardown sequence to avoid dual
+    audio).
+  - foreground + ON → `player_exit_background_audio()`, reload `<video>` at the
+    returned position, restore play/pause state.
+- **Follow the native-mode pitfall** (memory:
+  `videoplayer-native-mode-pitfalls`): no lifecycle calls after an `await` in
+  `onMount`. Keep the handoff logic out of that window.
+- Dual-audio is the key regression risk: at every handoff exactly one of
+  {WebView `<video>`, native ExoPlayer} produces audio. Tear the other down
+  *before* starting the next, mirroring the existing HLS cleanup discipline.
+
+## Phasing
+
+- **Phase 0 — De-risk (do first):**
+  - Confirm what actually triggers today's auto-PiP given video is on the
+    WebView (resolve the `canEnterPip`/`isPlayingVideo` question).
+  - Spike: obtain an audio-only stream URL for a video item and play it through
+    the native audio service; measure position accuracy and that WebView audio
+    is fully silenced (no dual audio).
+- **Phase 1 — Backend:** repository audio-only-URL method + the two player
+  commands + events.
+- **Phase 2 — Native:** lifecycle wiring, PiP suppression, handoff trigger.
+- **Phase 3 — Frontend:** toggle UI, lifecycle listeners, handoff calls,
+  teardown discipline.
+- **Phase 4 — Polish:** persist toggle preference, subtitle/audio-track
+  carry-over, edge cases (calls, headphone unplug, autoplay-next during
+  background audio).
+
+## Testing
+
+- Rust: unit tests for the audio-only URL builder and the two commands
+  (`cargo test`, `bun run test:rust`).
+- IPC param-naming integration tests for any new commands
+  (`bun run test -- tauriIntegration.test.ts`).
+- Frontend: `bun run check`, `bun run test`, plus a VideoPlayer logic test for
+  the handoff state machine (mirror the existing
+  `VideoPlayer.logic.test.ts`).
+- Manual on-device matrix:
+  - toggle ON: home button → audio continues, video stops decoding; return →
+    video resumes at position; playing/paused preserved.
+  - toggle ON: screen lock → audio continues; lockscreen controls work; unlock →
+    resumes.
+  - toggle OFF: background → PiP (unchanged).
+  - No dual audio at any transition. No audio leak after leaving the player.
+  - Transcoded (HEVC/10-bit) item — verify position with `seekOffset`.
+  - Autoplay-next fires correctly if an episode ends during background audio.
+
+## Open questions
+
+1. **Persist the toggle per user/series, or default OFF each session?**
+   (Recommend: remember last choice; series-level like the audio-track
+   preference is a nice-to-have.)
+2. **Autoplay-next during background audio** — should the next episode start as
+   audio-only and stay audio until foreground, or pause at episode end? (Recommend:
+   continue as audio-only.)
+3. **Subtitles** are irrelevant in audio-only mode but must restore on
+   foreground — confirm they survive the `<video>` teardown/reload.
+4. Exact **Android lifecycle signal** for "screen locked" vs "app backgrounded"
+   — `onUserLeaveHint` covers Home but not lock; may need a screen-off receiver.
+
+## Non-goals (v1)
+
+- Linux background audio (desktop windows keep running unfocused; low value).
+- Replacing or removing PiP — it stays as the toggle-OFF behavior.
+- Re-enabling the native ExoPlayer *video* surface path.

docs/traceability-ci.md

@@ -138,7 +138,7 @@ The workflow **warns** (but doesn't block) if:
 3. Download **traceability-reports** artifact
 4. View:
    - `traces-report.json` - Raw trace data
-   - `docs/TRACEABILITY.md` - Formatted report
+   - `docs/traceability.md` - Formatted report
 
 ### Locally
 ```bash
@@ -147,7 +147,7 @@ bun run traces:json | jq '.byType'
 
 # Generate full report
 bun run traces:markdown
-cat docs/TRACEABILITY.md
+cat docs/traceability.md
 ```
 
 ## Coverage Goals
@@ -272,7 +272,7 @@ fi
 
 - [Extract Traces Script](../scripts/README.md#extract-tracests)
 - [Requirements Specification](../README.md#requirements-specification)
-- [Traceability Matrix](./TRACEABILITY.md)
+- [Traceability Matrix](./traceability.md)
 - [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
 
 ## Support

docs/traces-quick-ref.md

@@ -0,0 +1,212 @@
+# TRACES Quick Reference Guide
+
+## What are TRACES?
+
+TRACES are requirement identifiers embedded in code comments to track which requirements are implemented where.
+
+Format: `// TRACES: UR-001, UR-002 | DR-003`
+
+## Quick Examples
+
+### TypeScript
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+export function handlePlayback() { }
+
+/**
+ * Resume playback from saved position
+ * TRACES: UR-019 | DR-022
+ */
+export async function resumePlayback(itemId: string) { }
+```
+
+### Svelte
+```svelte
+<!-- TRACES: UR-007, UR-008 | DR-007 -->
+<script>
+  export let items = [];
+</script>
+```
+
+### Rust
+```rust
+/// TRACES: UR-005 | DR-001
+pub enum PlayerState { ... }
+
+#[test]
+fn test_queue_next() {
+    // TRACES: UR-005 | DR-005 | UT-003
+}
+```
+
+## Requirement Types
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| **UR** | User Requirement | UR-005: Control media playback |
+| **IR** | Integration Requirement | IR-003: LibMPV integration |
+| **DR** | Development Requirement | DR-001: Player state machine |
+| **JA** | Jellyfin API Requirement | JA-007: Get playback info |
+| **UT** | Unit Test | UT-001: Player state transitions |
+| **IT** | Integration Test | IT-003: Audio playback via libmpv |
+
+## Where to Find Requirements
+
+1. **User Requirements (UR):** [README.md](README.md#1-user-requirements)
+2. **Integration Requirements (IR):** [README.md](README.md#21-integration-requirements)
+3. **Development Requirements (DR):** [README.md](README.md#23-development-requirements)
+4. **Jellyfin API (JA):** [README.md](README.md#22-jellyfin-api-requirements)
+
+## How to Add TRACES
+
+### Step 1: Find the Requirement
+Look up the requirement in README.md or the traceability matrix.
+
+Example: `UR-005: Control media playback (pause, play, skip, scrub)`
+
+### Step 2: Add Comment
+Add TRACES comment at the top of the function/type/module:
+
+```typescript
+// TRACES: UR-005
+export async function playMedia(itemId: string) {
+  // Implementation
+}
+```
+
+### Step 3: Run Extraction
+Verify the trace is captured:
+
+```bash
+bun run traces:json | jq '.requirements | keys | grep "UR-005"'
+```
+
+## Common Patterns
+
+### Single Requirement
+```typescript
+// TRACES: UR-005
+function handlePlay() { }
+```
+
+### Multiple Requirements, Same Type
+```typescript
+// TRACES: UR-005, UR-026, UR-019
+function handlePlaybackState() { }
+```
+
+### Multiple Types
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+function autoplayNextEpisode() { }
+```
+
+### Test Coverage
+```typescript
+// TRACES: UR-005 | UT-001
+#[test]
+fn test_player_state_transition() { }
+```
+
+### Modules/Files
+```typescript
+/**
+ * Player event handling
+ * TRACES: UR-005, UR-019, UR-023 | DR-001, DR-028
+ */
+```
+
+## Validation
+
+### Check Your Changes
+```bash
+# View current coverage
+bun run traces:json | jq '.byType'
+
+# Generate full report
+bun run traces:markdown
+
+# Check specific requirement
+bun run traces:json | jq '.requirements."UR-005"'
+```
+
+### Before Committing
+1. Ensure all new code has TRACES
+2. Format is correct: `// TRACES: ...`
+3. Requirements exist in README.md
+4. No typos in requirement IDs
+
+## CI/CD Validation
+
+The workflow automatically checks:
+- ✅ Coverage stays >= 50%
+- ✅ New files have TRACES
+- ✅ JSON format is valid
+- ✅ Reports are generated
+
+See [traceability-ci.md](docs/traceability-ci.md) for details.
+
+## Tips & Tricks
+
+### Find Related Code
+```bash
+# Find all code tracing to UR-005
+bun run traces:json | jq '.requirements."UR-005"'
+
+# List all tests
+bun run traces:json | jq '.requirements | keys | map(select(startswith("UT")))'
+```
+
+### Update Your Editor
+
+**VS Code:**
+```json
+{
+  "editor.wordBasedSuggestions": false,
+  "editor.suggest.custom": [
+    {
+      "name": "TRACES Format",
+      "insertText": "// TRACES: $1",
+      "insertTextRules": "InsertAsSnippet"
+    }
+  ]
+}
+```
+
+### Find Untraced Code
+```bash
+# Files modified without TRACES
+git diff --name-only | xargs grep -L "TRACES:" | head -10
+```
+
+## FAQ
+
+**Q: Do I need TRACES on every function?**
+A: Only for code that implements requirements. Internal helpers don't need TRACES.
+
+**Q: Can I use TRACES on multiple related functions?**
+A: Yes! Add at the file/module level or on individual functions.
+
+**Q: What if code doesn't relate to any requirement?**
+A: Leave it untraced. TRACES are for requirement-driven development.
+
+**Q: How often should I regenerate reports?**
+A: Automatically on push (CI/CD). Manually after changes: `bun run traces:markdown`
+
+**Q: Can I trace to requirements that aren't implemented yet?**
+A: Yes! TRACES show your implementation plan.
+
+## See Also
+
+- [Full Traceability Matrix](docs/traceability.md)
+- [CI/CD Pipeline Guide](docs/traceability-ci.md)
+- [Requirements Specification](README.md)
+- [Extraction Script](scripts/README.md#extract-tracests)
+
+---
+
+**Quick Start:**
+1. Add `// TRACES: UR-XXX` to new code
+2. Run `bun run traces:markdown`
+3. Check `docs/traceability.md`
+4. Submit PR - workflow validates automatically!

docs/ux-flows.md

@@ -690,24 +690,59 @@ flowchart TB
 └─────────────────────────────────────────┘
 ```
 
-### 9.2 Video Playback in Background
+### 9.2 Video Playback in Background (Android — PiP & Background Audio)
+
+Leaving the app while a **local video** is playing does not simply pause it.
+What happens depends on which background behaviour is active. The two are
+**mutually exclusive**, and both apply **only to locally-rendering video** —
+audio-only playback, library/menu browsing, and remote/cast sessions never
+trigger PiP (see decision gate below).
 
 ```mermaid
 flowchart TB
-    VideoPlaying[Video Playing] --> Background{User Action}
+    Leave[User leaves app<br/>Home / gesture / screen lock] --> Gate{Local video surface<br/>actively rendering?<br/>canEnterPip}
 
-    Background -->|Home Button| AutoPause[Automatically Pause]
-    Background -->|Screen Lock| AutoPause
+    Gate -->|No — audio, browsing,<br/>or remote/cast| Normal[App backgrounds normally<br/>audio, if any, continues via<br/>media notification &#40;§9.1&#41;]
 
-    AutoPause --> SaveProgress[Save Progress]
-    SaveProgress --> ShowNotification[Show Paused Notification:<br/>"Tap to Resume"]
+    Gate -->|Yes| Mode{Background mode armed?}
 
-    ShowNotification --> UserReturn{User Returns?}
+    Mode -->|Background-audio toggle ON<br/>UR-040| Handoff[Hand off to native audio service<br/>WebView &lt;video&gt; torn down,<br/>video decode stops, audio continues]
+    Mode -->|Default<br/>UR-041| PiP[Auto-enter Picture-in-Picture<br/>on onUserLeaveHint]
 
-    UserReturn -->|Tap Notification| ResumeVideo[Open App to Video Player]
-    UserReturn -->|Later| KeepPaused[Video Remains Paused]
+    PiP --> PiPWindow[Floating PiP window:<br/>- Video keeps rendering into surface<br/>- WebView hidden<br/>- Play/Pause RemoteAction<br/>  &#40;reflects live player state&#41;]
 
-    ResumeVideo --> AskResume[Resume from Saved Position]
+    PiPWindow --> PiPReturn{User action}
+    PiPReturn -->|Tap window| Restore[Return to full player<br/>WebView restored, surface re-fit]
+    PiPReturn -->|Close window| Stop[Playback stops]
+
+    Handoff --> Foreground[On return to foreground:<br/>resume WebView video at position]
+```
+
+**Key rules:**
+
+- **Video-only gate.** Auto-PiP is guarded by the native `canEnterPip` check
+  (local video surface actively rendering). Audio playback and menu/library
+  browsing background normally; remote/cast sessions render nothing locally, so
+  a PiP window would be an empty box and is refused. *(UR-041, IR-026)*
+- **Only one background behaviour at a time.** The background-audio toggle
+  (UR-040) disarms auto-PiP while it is on, so a video is either handed to the
+  audio service *or* floated in PiP, never both.
+- **PiP controls track the player.** The play/pause RemoteAction in the PiP
+  window reflects the live player state and updates on every playback-state
+  change, not only when the button is pressed. *(DR-053)*
+- **Non-disruptive transition.** ExoPlayer keeps rendering into the same
+  surface across enter/exit, so entering or leaving PiP never interrupts the
+  video; on exit the surface is re-fit to full-screen bounds. *(DR-053)*
+
+**PiP window (Android):**
+```
+        ┌───────────────────┐
+        │                   │
+        │   ▶ video frame   │
+        │                   │
+        │       [⏸]         │  ← play/pause RemoteAction
+        └───────────────────┘
+   sized to the video's aspect ratio
 ```
 
 ---

package.json

@@ -1,8 +1,9 @@
 {
   "name": "jellytau",
-  "version": "0.1.0",
+  "version": "0.0.16",
   "description": "",
   "type": "module",
+  "packageManager": "bun@1.3.5",
   "scripts": {
     "dev": "vite dev",
     "build": "vite build",
@@ -18,6 +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 && bun install && bun run build",
     "android:deploy": "./scripts/deploy-android.sh",
     "android:dev": "./scripts/build-and-deploy.sh",
     "android:check": "./scripts/check-android.sh",
@@ -26,7 +28,8 @@
     "tauri": "tauri",
     "traces": "bun run scripts/extract-traces.ts",
     "traces:json": "bun run scripts/extract-traces.ts --format json",
-    "traces:markdown": "bun run scripts/extract-traces.ts --format markdown > docs/TRACEABILITY.md"
+    "traces:markdown": "bun run scripts/extract-traces.ts --format markdown > docs/traceability.md",
+    "release:notes": "bun run scripts/release-notes.ts"
   },
   "license": "MIT",
   "dependencies": {
@@ -56,7 +59,7 @@
     "tailwindcss": "^4.1.18",
     "typescript": "~5.6.2",
     "vite": "^6.0.3",
-    "vitest": "^4.0.16",
+    "vitest": ">=1.0.0 <5.0.0",
     "webdriverio": "^9.5.0"
   }
 }

scripts/README.md

@@ -68,7 +68,7 @@ Extract requirement IDs (TRACES) from source code and generate a traceability ma
 ```bash
 bun run traces                    # Generate markdown report
 bun run traces:json              # Generate JSON report
-bun run traces:markdown           # Save to docs/TRACEABILITY.md
+bun run traces:markdown           # Save to docs/traceability.md
 ```
 
 The script scans all TypeScript, Svelte, and Rust files looking for `TRACES:` comments and generates a comprehensive mapping of:
@@ -82,7 +82,7 @@ Example TRACES comment in code:
 function handlePlayback() { ... }
 ```
 
-See [docs/TRACEABILITY.md](../docs/TRACEABILITY.md) for the latest generated mapping.
+See [docs/traceability.md](../docs/traceability.md) for the latest generated mapping.
 
 ### CI/CD Validation
 
@@ -93,8 +93,8 @@ The traceability system is integrated with Gitea Actions CI/CD:
 - Generates traceability reports automatically
 
 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
+- [Traceability CI Guide](../docs/traceability-ci.md) - Full CI/CD documentation
+- [TRACES Quick Reference](../docs/traces-quick-ref.md) - Quick guide for adding TRACES
 
 ## Utility Scripts
 

scripts/build-and-deploy.sh

@@ -3,15 +3,19 @@
 
 set -e
 
-BUILD_TYPE="${1:-debug}"
-
 echo "🚀 Build and Deploy Android APK"
 echo ""
 
-# Build APK
-./scripts/build-android.sh "$BUILD_TYPE"
+# Pass all args (build type and/or --clean) through to the build script.
+./scripts/build-android.sh "$@"
 
 echo ""
 
-# Deploy APK
+# Deploy APK — extract build type (default debug), ignoring flags like --clean.
+BUILD_TYPE="debug"
+for arg in "$@"; do
+    case "$arg" in
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
 ./scripts/deploy-android.sh "$BUILD_TYPE"

scripts/build-android.sh

@@ -15,8 +15,24 @@ echo "Android SDK: $ANDROID_HOME"
 echo "NDK: $NDK_HOME"
 echo ""
 
-# Build type: debug or release (default: debug)
-BUILD_TYPE="${1:-debug}"
+# Parse args: build type (debug/release) and optional --clean flag.
+# By default the build is INCREMENTAL — Cargo and Vite reuse their caches.
+# Pass --clean (or CLEAN=1) to wipe all caches for a from-scratch build.
+BUILD_TYPE="debug"
+CLEAN="${CLEAN:-0}"
+for arg in "$@"; do
+    case "$arg" in
+        --clean) CLEAN=1 ;;
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
+
+# Step 0: Optionally clear build caches for a fully fresh build.
+if [ "$CLEAN" = "1" ]; then
+    echo "🧹 Clearing build caches (clean build)..."
+    rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target 2>/dev/null || true
+    npm install > /dev/null 2>&1
+fi
 
 # Step 1: Sync Android source files
 echo "🔄 Syncing Android sources..."
@@ -28,6 +44,9 @@ bun run build
 
 # Step 2: Build Android APK
 if [ "$BUILD_TYPE" = "release" ]; then
+    # Configure release signing from .env (single source of truth). Must run
+    # after sync-android-sources.sh, since gen/android is (re)generated there.
+    ./scripts/write-keystore-properties.sh
     echo "📦 Building release APK..."
     bun run tauri android build --apk true
 else

scripts/extract-traces.ts

@@ -5,7 +5,7 @@
  * Usage:
  *   bun run scripts/extract-traces.ts
  *   bun run scripts/extract-traces.ts --format json
- *   bun run scripts/extract-traces.ts --format markdown > docs/TRACEABILITY.md
+ *   bun run scripts/extract-traces.ts --format markdown > docs/traceability.md
  */
 
 import * as fs from "fs";
@@ -36,6 +36,10 @@ interface TracesData {
   };
 }
 
+// Repo root, derived from this script's location (scripts/ -> repo root).
+// Must NOT be hardcoded to a developer's machine, or CI checkouts see no files.
+const BASE_DIR = path.resolve(import.meta.dir, "..");
+
 const TRACES_PATTERN = /TRACES:\s*([^\n]+)/gi;
 const REQ_ID_PATTERN = /([A-Z]{2})-(\d{3})/g;
 
@@ -45,7 +49,7 @@ function extractRequirementIds(tracesString: string): string[] {
 }
 
 function getAllSourceFiles(): string[] {
-  const baseDir = "/home/dtourolle/Development/JellyTau";
+  const baseDir = BASE_DIR;
   const patterns = ["src", "src-tauri/src"];
   const files: string[] = [];
 
@@ -101,7 +105,7 @@ function extractTraces(): TracesData {
   };
 
   let totalTraces = 0;
-  const baseDir = "/home/dtourolle/Development/JellyTau";
+  const baseDir = BASE_DIR;
 
   const files = getAllSourceFiles();
 

scripts/release-notes.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+/**
+ * release-notes.ts — turn a commit range into capability-level release notes
+ * using the TRACES graph instead of raw commit subjects.
+ *
+ * Usage:
+ *   bun run scripts/release-notes.ts [<range>]
+ *   bun run scripts/release-notes.ts v0.0.15..HEAD
+ *
+ * With no argument it uses <latest tag>..HEAD (or the whole history if untagged).
+ *
+ * How it works:
+ *   1. `git diff --name-only <range>` → files the range changed.
+ *   2. Read each changed file's `TRACES:` comments → requirement IDs.
+ *   3. Resolve IDs to descriptions from docs/requirements.md.
+ *   4. Group: UR → Features, DR/IR → Improvements. Deduped, so many commits
+ *      touching one requirement collapse to one line.
+ *
+ * This is a drafting aid for docs/release-checklist.md — review the output,
+ * it does not invent descriptions for untraced changes (those are listed
+ * separately so nothing is silently dropped).
+ */
+
+import { execSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+
+const TRACE_RE = /TRACES:\s*([^\n*]+)/g;
+const ID_RE = /\b(UR|IR|DR|JA|UT|IT)-\d+\b/g;
+const REQ_ROW_RE = /^\|\s*((?:UR|IR|DR|JA)-\d+)\s*\|\s*([^|]+?)\s*\|/;
+
+function sh(cmd: string): string {
+  return execSync(cmd, { encoding: "utf8" }).trim();
+}
+
+function defaultRange(): string {
+  try {
+    const tag = sh("git describe --tags --abbrev=0");
+    return `${tag}..HEAD`;
+  } catch {
+    return ""; // no tags: fall through to whole-history diff
+  }
+}
+
+/** Map requirement ID → human description, parsed from docs/requirements.md. */
+function loadRequirementDescriptions(): Map<string, string> {
+  const map = new Map<string, string>();
+  const text = readFileSync("docs/requirements.md", "utf8");
+  for (const line of text.split("\n")) {
+    const m = line.match(REQ_ROW_RE);
+    // First definition wins: the descriptive tables come before the later
+    // cross-reference tables, whose cells hold linked IDs (or "-"), not prose.
+    if (m && !map.has(m[1])) map.set(m[1], m[2].trim());
+  }
+  return map;
+}
+
+function changedFiles(range: string): string[] {
+  const cmd = range
+    ? `git diff --name-only ${range}`
+    : "git ls-files"; // untagged repo: describe everything currently traced
+  return sh(cmd)
+    .split("\n")
+    .filter((f) => f && existsSync(f));
+}
+
+/** Collect requirement IDs referenced by TRACES comments in the given files. */
+function idsFromFiles(files: string[]): Set<string> {
+  const ids = new Set<string>();
+  for (const file of files) {
+    let content: string;
+    try {
+      content = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    for (const trace of content.matchAll(TRACE_RE)) {
+      for (const id of trace[1].matchAll(ID_RE)) ids.add(id[0]);
+    }
+  }
+  return ids;
+}
+
+function main() {
+  const range = process.argv[2] ?? defaultRange();
+  const descriptions = loadRequirementDescriptions();
+  const files = changedFiles(range);
+  const ids = idsFromFiles(files);
+
+  const features: string[] = []; // UR
+  const improvements: string[] = []; // DR / IR
+  const unknown: string[] = []; // traced but not in requirements.md
+
+  for (const id of [...ids].sort()) {
+    const desc = descriptions.get(id);
+    if (id.startsWith("UT") || id.startsWith("IT")) continue; // tests aren't notes
+    if (!desc) {
+      if (!id.startsWith("UT") && !id.startsWith("IT")) unknown.push(id);
+      continue;
+    }
+    const line = `- ${desc} (${id})`;
+    if (id.startsWith("UR")) features.push(line);
+    else improvements.push(line);
+  }
+
+  const header = range || "(entire history — no tags found)";
+  const out: string[] = [`## Release notes — ${header}`, ""];
+
+  if (features.length) out.push("### ✨ Features", ...features, "");
+  if (improvements.length) out.push("### 🚀 Improvements", ...improvements, "");
+  if (unknown.length)
+    out.push(
+      "### ⚠️ Traced IDs missing from requirements.md",
+      ...unknown.map((id) => `- ${id}`),
+      "",
+    );
+
+  const untraced = files.filter((f) => {
+    try {
+      return !/TRACES:/.test(readFileSync(f, "utf8"));
+    } catch {
+      return false;
+    }
+  });
+  if (untraced.length)
+    out.push(
+      `### 📝 Changed files without TRACES (${untraced.length}) — review manually`,
+      ...untraced.map((f) => `- ${f}`),
+      "",
+    );
+
+  if (!features.length && !improvements.length)
+    out.push("_No traced requirements in this range._", "");
+
+  console.log(out.join("\n"));
+}
+
+main();

scripts/sync-android-sources.sh

@@ -31,4 +31,81 @@ for kt_file in "$SOURCE_DIR"/*.kt; do
     fi
 done
 
+# Restore the app module build.gradle.kts (media3 deps + release signing config).
+# gen/android is regenerated by `tauri android init`, so this tracked template is
+# the source of truth and must be copied back after any (re)generation.
+APP_GRADLE_SRC="$PROJECT_ROOT/src-tauri/android/app/build.gradle.kts"
+APP_GRADLE_DST="$PROJECT_ROOT/src-tauri/gen/android/app/build.gradle.kts"
+if [ -f "$APP_GRADLE_SRC" ]; then
+    cp "$APP_GRADLE_SRC" "$APP_GRADLE_DST"
+    echo "  Copied: app/build.gradle.kts"
+fi
+
+# AndroidManifest.xml. `tauri android init` regenerates gen/android from
+# tauri.conf.json and would drop our hand-maintained entries (media playback
+# service + permissions, hardware acceleration, picture-in-picture attributes
+# on MainActivity), so this tracked copy is the source of truth and must be
+# restored after a regen. Gradle reads ONLY the gen/ copy - there is no
+# manifest-merger hook here, so this must be the complete manifest.
+MANIFEST_SRC="$PROJECT_ROOT/src-tauri/android/src/main/AndroidManifest.xml"
+MANIFEST_DST="$PROJECT_ROOT/src-tauri/gen/android/app/src/main/AndroidManifest.xml"
+if [ -f "$MANIFEST_SRC" ]; then
+    cp "$MANIFEST_SRC" "$MANIFEST_DST"
+    echo "  Copied: app/src/main/AndroidManifest.xml"
+fi
+
+# Custom ProGuard/R8 keep rules. Required for minified release builds:
+# the player/ and security/ Kotlin classes are loaded by name via JNI from
+# Rust, so R8 can't see the references and would strip them without this.
+# build.gradle.kts globs **/*.pro, so dropping it in app/ is enough.
+PROGUARD_SRC="$PROJECT_ROOT/src-tauri/android/app/proguard-jellytau.pro"
+PROGUARD_DST="$PROJECT_ROOT/src-tauri/gen/android/app/proguard-jellytau.pro"
+if [ -f "$PROGUARD_SRC" ]; then
+    cp "$PROGUARD_SRC" "$PROGUARD_DST"
+    echo "  Copied: app/proguard-jellytau.pro"
+fi
+
+# Launcher icons / adaptive-icon mipmaps. `tauri android init` generates
+# low-quality launcher icons from tauri.conf.json (which has no high-res
+# Android source), so overwrite them with the real committed mipmaps.
+RES_SRC="$PROJECT_ROOT/src-tauri/android/src/main/res"
+RES_DST="$PROJECT_ROOT/src-tauri/gen/android/app/src/main/res"
+if [ -d "$RES_SRC" ]; then
+    for dir in "$RES_SRC"/mipmap-*; do
+        [ -d "$dir" ] || continue
+        name="$(basename "$dir")"
+        mkdir -p "$RES_DST/$name"
+        cp "$dir"/* "$RES_DST/$name/"
+        echo "  Copied res: $name"
+    done
+
+    # values/ (themes.xml): status-bar styling that `tauri android init` does
+    # not generate. Previously this directory was tracked but never copied, so
+    # the theme customizations below never reached a build.
+    if [ -d "$RES_SRC/values" ]; then
+        mkdir -p "$RES_DST/values"
+        cp "$RES_SRC"/values/*.xml "$RES_DST/values/"
+        echo "  Copied res: values"
+    fi
+    # We ship only the color adaptive icon (background + foreground). Drop any
+    # monochrome layer Tauri may generate: the themed-icon monochrome doesn't
+    # render well, and our adaptive-icon xml no longer references it, so a stray
+    # ic_launcher_monochrome.png would just be dead weight.
+    rm -f "$RES_DST"/mipmap-*/ic_launcher_monochrome.png
+
+    # `tauri android init` also emits the Android Studio DEFAULT adaptive icon
+    # as API-qualified VECTOR drawables:
+    #   drawable/ic_launcher_background.xml      (solid #3DDC84 green)
+    #   drawable-v24/ic_launcher_foreground.xml  (the Android robot)
+    # Because drawable-v24 is a more specific match than our unqualified
+    # mipmap-*/ic_launcher_*.png, on API 24+ the vector WINS and the app ships
+    # the green square robot instead of our jellyfish. Remove them so the
+    # adaptive-icon xml resolves @mipmap/ic_launcher_{background,foreground}
+    # to the real committed PNGs.
+    rm -f "$RES_DST"/drawable/ic_launcher_background.xml \
+          "$RES_DST"/drawable-v24/ic_launcher_foreground.xml \
+          "$RES_DST"/drawable*/ic_launcher_foreground.xml \
+          "$RES_DST"/drawable*/ic_launcher_background.xml
+fi
+
 echo "✓ Android sources synced successfully"

scripts/test-all.sh

@@ -7,7 +7,7 @@ echo "🧪 Running all tests..."
 echo ""
 
 echo "📦 Running frontend tests..."
-bun test
+bun run test
 
 echo ""
 echo "🦀 Running Rust tests..."

scripts/test-frontend.sh

@@ -4,4 +4,4 @@
 set -e
 
 echo "📦 Running frontend tests..."
-bun test "$@"
+bun run test "$@"

scripts/write-keystore-properties.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Regenerate src-tauri/gen/android/keystore.properties from the gitignored .env.
+#
+# .env is the single source of truth for local release signing. `tauri android
+# init` wipes/regenerates gen/android, so keystore.properties must be rewritten
+# from .env before every release build (this is the local mirror of what the CI
+# workflow does from Gitea secrets).
+#
+# Required .env vars:
+#   ANDROID_KEY_ALIAS, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_PASSWORD,
+#   ANDROID_KEYSTORE_FILE (absolute path to the .jks)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+ENV_FILE="$PROJECT_ROOT/.env"
+PROPS="$PROJECT_ROOT/src-tauri/gen/android/keystore.properties"
+
+if [ ! -f "$ENV_FILE" ]; then
+    echo "❌ $ENV_FILE not found — cannot configure release signing." >&2
+    echo "   Create it with ANDROID_KEY_ALIAS / ANDROID_KEYSTORE_PASSWORD /" >&2
+    echo "   ANDROID_KEY_PASSWORD / ANDROID_KEYSTORE_FILE." >&2
+    exit 1
+fi
+
+# Load .env without leaking it into the caller's environment beyond what we need.
+set -a
+# shellcheck disable=SC1090
+. "$ENV_FILE"
+set +a
+
+: "${ANDROID_KEY_ALIAS:?ANDROID_KEY_ALIAS missing from .env}"
+: "${ANDROID_KEYSTORE_PASSWORD:?ANDROID_KEYSTORE_PASSWORD missing from .env}"
+: "${ANDROID_KEY_PASSWORD:?ANDROID_KEY_PASSWORD missing from .env}"
+: "${ANDROID_KEYSTORE_FILE:?ANDROID_KEYSTORE_FILE missing from .env}"
+
+if [ ! -f "$ANDROID_KEYSTORE_FILE" ]; then
+    echo "❌ Keystore not found at ANDROID_KEYSTORE_FILE=$ANDROID_KEYSTORE_FILE" >&2
+    exit 1
+fi
+
+mkdir -p "$(dirname "$PROPS")"
+umask 077
+cat > "$PROPS" <<EOF
+storeFile=$ANDROID_KEYSTORE_FILE
+storePassword=$ANDROID_KEYSTORE_PASSWORD
+keyAlias=$ANDROID_KEY_ALIAS
+keyPassword=$ANDROID_KEY_PASSWORD
+EOF
+
+echo "🔐 Wrote release signing config to keystore.properties (from .env)"

src-tauri/.cargo/config.toml

@@ -1,38 +0,0 @@
-[target.aarch64-linux-android]
-linker = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang"
-ar = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-[target.armv7-linux-androideabi]
-linker = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi34-clang"
-ar = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-[target.i686-linux-android]
-linker = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/i686-linux-android34-clang"
-ar = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-[target.x86_64-linux-android]
-linker = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/x86_64-linux-android34-clang"
-ar = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-[env]
-# Point to the NDK for the cc crate and other build scripts
-ANDROID_NDK_HOME = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006"
-NDK_HOME = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006"
-
-# Set CC/CXX for each Android target (cc crate looks for these)
-CC_aarch64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang"
-CXX_aarch64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang++"
-AR_aarch64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-CC_armv7-linux-androideabi = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi34-clang"
-CXX_armv7-linux-androideabi = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi34-clang++"
-AR_armv7-linux-androideabi = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-CC_i686-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/i686-linux-android34-clang"
-CXX_i686-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/i686-linux-android34-clang++"
-AR_i686-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-
-CC_x86_64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/x86_64-linux-android34-clang"
-CXX_x86_64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/x86_64-linux-android34-clang++"
-AR_x86_64-linux-android = "/home/dtourolle/Android/Sdk/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
-

src-tauri/Cargo.lock

@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "Inflector"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe438c63458706e03479442743baae6c88256498e6431708f6dfc520a26515d3"
+
 [[package]]
 name = "adler2"
 version = "2.0.1"
@@ -1745,7 +1751,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core 0.62.2",
+ "windows-core",
 ]
 
 [[package]]
@@ -2011,14 +2017,18 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2",
+ "specta",
+ "specta-typescript",
  "tauri",
  "tauri-build",
  "tauri-plugin-opener",
  "tauri-plugin-os",
+ "tauri-specta",
  "tempfile",
  "tokio",
  "tokio-rusqlite",
  "tokio-util",
+ "urlencoding",
  "uuid",
 ]
 
@@ -2795,6 +2805,12 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
 [[package]]
 name = "pathdiff"
 version = "0.2.3"
@@ -3933,6 +3949,51 @@ dependencies = [
  "system-deps",
 ]
 
+[[package]]
+name = "specta"
+version = "2.0.0-rc.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab7f01e9310a820edd31c80fde3cae445295adde21a3f9416517d7d65015b971"
+dependencies = [
+ "chrono",
+ "paste",
+ "specta-macros",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "specta-macros"
+version = "2.0.0-rc.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0074b9e30ed84c6924eb63ad8d2fe71cdc82628525d84b1fcb1f2fd40676517"
+dependencies = [
+ "Inflector",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.112",
+]
+
+[[package]]
+name = "specta-serde"
+version = "0.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77216504061374659e7245eac53d30c7b3e5fe64b88da97c753e7184b0781e63"
+dependencies = [
+ "specta",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "specta-typescript"
+version = "0.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3220a0c365e51e248ac98eab5a6a32f544ff6f961906f09d3ee10903a4f52b2d"
+dependencies = [
+ "specta",
+ "specta-serde",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -4092,7 +4153,7 @@ dependencies = [
  "unicode-segmentation",
  "url",
  "windows",
- "windows-core 0.61.2",
+ "windows-core",
  "windows-version",
  "x11-dl",
 ]
@@ -4149,6 +4210,7 @@ dependencies = [
  "serde_json",
  "serde_repr",
  "serialize-to-javascript",
+ "specta",
  "swift-rs",
  "tauri-build",
  "tauri-macros",
@@ -4337,6 +4399,34 @@ dependencies = [
  "wry",
 ]
 
+[[package]]
+name = "tauri-specta"
+version = "2.0.0-rc.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b23c0132dd3cf6064e5cd919b82b3f47780e9280e7b5910babfe139829b76655"
+dependencies = [
+ "heck 0.5.0",
+ "serde",
+ "serde_json",
+ "specta",
+ "specta-typescript",
+ "tauri",
+ "tauri-specta-macros",
+ "thiserror 2.0.17",
+]
+
+[[package]]
+name = "tauri-specta-macros"
+version = "2.0.0-rc.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a4aa93823e07859546aa796b8a5d608190cd8037a3a5dce3eb63d491c34bda8"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.112",
+]
+
 [[package]]
 name = "tauri-utils"
 version = "2.8.1"
@@ -4870,6 +4960,12 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "urlencoding"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
+
 [[package]]
 name = "urlpattern"
 version = "0.3.0"
@@ -5143,7 +5239,7 @@ dependencies = [
  "webview2-com-macros",
  "webview2-com-sys",
  "windows",
- "windows-core 0.61.2",
+ "windows-core",
  "windows-implement",
  "windows-interface",
 ]
@@ -5167,7 +5263,7 @@ checksum = "36695906a1b53a3bf5c4289621efedac12b73eeb0b89e7e1a89b517302d5d75c"
 dependencies = [
  "thiserror 2.0.17",
  "windows",
- "windows-core 0.61.2",
+ "windows-core",
 ]
 
 [[package]]
@@ -5223,7 +5319,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893"
 dependencies = [
  "windows-collections",
- "windows-core 0.61.2",
+ "windows-core",
  "windows-future",
  "windows-link 0.1.3",
  "windows-numerics",
@@ -5235,7 +5331,7 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3beeceb5e5cfd9eb1d76b381630e82c4241ccd0d27f1a39ed41b2760b255c5e8"
 dependencies = [
- "windows-core 0.61.2",
+ "windows-core",
 ]
 
 [[package]]
@@ -5247,21 +5343,8 @@ dependencies = [
  "windows-implement",
  "windows-interface",
  "windows-link 0.1.3",
- "windows-result 0.3.4",
- "windows-strings 0.4.2",
-]
-
-[[package]]
-name = "windows-core"
-version = "0.62.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
-dependencies = [
- "windows-implement",
- "windows-interface",
- "windows-link 0.2.1",
- "windows-result 0.4.1",
- "windows-strings 0.5.1",
+ "windows-result",
+ "windows-strings",
 ]
 
 [[package]]
@@ -5270,7 +5353,7 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e"
 dependencies = [
- "windows-core 0.61.2",
+ "windows-core",
  "windows-link 0.1.3",
  "windows-threading",
 ]
@@ -5315,7 +5398,7 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9150af68066c4c5c07ddc0ce30421554771e528bde427614c61038bc2c92c2b1"
 dependencies = [
- "windows-core 0.61.2",
+ "windows-core",
  "windows-link 0.1.3",
 ]
 
@@ -5328,15 +5411,6 @@ dependencies = [
  "windows-link 0.1.3",
 ]
 
-[[package]]
-name = "windows-result"
-version = "0.4.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
-dependencies = [
- "windows-link 0.2.1",
-]
-
 [[package]]
 name = "windows-strings"
 version = "0.4.2"
@@ -5346,15 +5420,6 @@ dependencies = [
  "windows-link 0.1.3",
 ]
 
-[[package]]
-name = "windows-strings"
-version = "0.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
-dependencies = [
- "windows-link 0.2.1",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.45.0"
@@ -5750,7 +5815,7 @@ dependencies = [
  "webkit2gtk-sys",
  "webview2-com",
  "windows",
- "windows-core 0.61.2",
+ "windows-core",
  "windows-version",
  "x11-dl",
 ]

src-tauri/Cargo.toml

@@ -14,6 +14,11 @@ edition = "2021"
 name = "jellytau_lib"
 crate-type = ["staticlib", "cdylib", "rlib"]
 
+# Keep debug info minimal to reduce target/ size in CI (line numbers in
+# backtraces are preserved; the bulky full debuginfo is dropped).
+[profile.dev]
+debug = "line-tables-only"
+
 [build-dependencies]
 tauri-build = { version = "2", features = [] }
 
@@ -28,6 +33,7 @@ rand = "0.8"
 tokio = { version = "1", features = ["sync", "rt-multi-thread", "time", "fs", "io-util", "macros"] }
 tokio-util = "0.7"
 reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream", "json"] }
+urlencoding = "2"
 futures-util = "0.3"
 async-trait = "0.1"
 
@@ -45,6 +51,9 @@ sha2 = "0.10"
 getrandom = "0.2"
 log = "0.4"
 env_logger = "0.11"
+tauri-specta = { version = "=2.0.0-rc.21", features = ["derive", "typescript"] }
+specta-typescript = "=0.0.9"
+specta = { version = "=2.0.0-rc.22", features = ["chrono", "derive"] }
 
 # Linux-specific dependencies
 [target.'cfg(target_os = "linux")'.dependencies]

src-tauri/android/app/build.gradle.kts

@@ -0,0 +1,103 @@
+import java.util.Properties
+
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("rust")
+}
+
+val tauriProperties = Properties().apply {
+    val propFile = file("tauri.properties")
+    if (propFile.exists()) {
+        propFile.inputStream().use { load(it) }
+    }
+}
+
+// Release signing: loaded from gen/android/keystore.properties if present.
+// Falls back to no signing config (debug-signed) when the file is absent.
+val keystoreProperties = Properties().apply {
+    val propFile = rootProject.file("keystore.properties")
+    if (propFile.exists()) {
+        propFile.inputStream().use { load(it) }
+    }
+}
+
+android {
+    compileSdk = 36
+    namespace = "com.dtourolle.jellytau"
+    defaultConfig {
+        manifestPlaceholders["usesCleartextTraffic"] = "false"
+        applicationId = "com.dtourolle.jellytau"
+        minSdk = 24
+        targetSdk = 36
+        versionCode = tauriProperties.getProperty("tauri.android.versionCode", "1").toInt()
+        versionName = tauriProperties.getProperty("tauri.android.versionName", "1.0")
+    }
+    signingConfigs {
+        create("release") {
+            keystoreProperties.getProperty("storeFile")?.let {
+                storeFile = file(it)
+                storePassword = keystoreProperties.getProperty("storePassword")
+                keyAlias = keystoreProperties.getProperty("keyAlias")
+                keyPassword = keystoreProperties.getProperty("keyPassword")
+            }
+        }
+    }
+    buildTypes {
+        getByName("debug") {
+            manifestPlaceholders["usesCleartextTraffic"] = "true"
+            isDebuggable = true
+            isJniDebuggable = true
+            isMinifyEnabled = false
+            packaging {                jniLibs.keepDebugSymbols.add("*/arm64-v8a/*.so")
+                jniLibs.keepDebugSymbols.add("*/armeabi-v7a/*.so")
+                jniLibs.keepDebugSymbols.add("*/x86/*.so")
+                jniLibs.keepDebugSymbols.add("*/x86_64/*.so")
+            }
+        }
+        getByName("release") {
+            if (keystoreProperties.getProperty("storeFile") != null) {
+                signingConfig = signingConfigs.getByName("release")
+            }
+            isMinifyEnabled = true
+            proguardFiles(
+                *fileTree(".") { include("**/*.pro") }
+                    .plus(getDefaultProguardFile("proguard-android-optimize.txt"))
+                    .toList().toTypedArray()
+            )
+        }
+    }
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+    buildFeatures {
+        buildConfig = true
+    }
+}
+
+rust {
+    rootDirRel = "../../../"
+}
+
+dependencies {
+    implementation("androidx.webkit:webkit:1.14.0")
+    implementation("androidx.appcompat:appcompat:1.7.1")
+    implementation("androidx.activity:activity-ktx:1.10.1")
+    implementation("com.google.android.material:material:1.12.0")
+
+    // Media3 dependencies for audio playback
+    implementation("androidx.media3:media3-exoplayer:1.5.0")
+    implementation("androidx.media3:media3-exoplayer-hls:1.5.0")
+    implementation("androidx.media3:media3-session:1.5.0")
+    implementation("androidx.media3:media3-common:1.5.0")
+    implementation("com.google.guava:guava:33.0.0-android")
+
+    // Media library for VolumeProviderCompat (remote volume control)
+    implementation("androidx.media:media:1.7.0")
+
+    testImplementation("junit:junit:4.13.2")
+    androidTestImplementation("androidx.test.ext:junit:1.1.4")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.0")
+}
+
+apply(from = "tauri.build.gradle.kts")

src-tauri/android/app/proguard-jellytau.pro

@@ -0,0 +1,24 @@
+# JellyTau custom keep rules.
+#
+# These classes are loaded by name from the Rust backend via JNI
+# (env.find_class / class-loader lookups), so R8 cannot see the
+# references and would otherwise strip or rename them in a minified
+# release build — causing an instant ClassNotFoundException crash on
+# startup. See src-tauri/src/player/android/mod.rs and
+# src-tauri/src/credentials.rs.
+-keep class com.dtourolle.jellytau.player.** { *; }
+-keep class com.dtourolle.jellytau.security.** { *; }
+
+# Picture-in-picture is driven from the WebView through an
+# @JavascriptInterface bridge, so the only references to these methods live
+# in JavaScript. R8 sees them as unused and would strip them, silently
+# breaking the PiP button in release builds only.
+-keep class com.dtourolle.jellytau.PictureInPictureManager { *; }
+-keep class com.dtourolle.jellytau.VideoOverlayManager { *; }
+-keepclassmembers class * {
+    @android.webkit.JavascriptInterface <methods>;
+}
+
+# Media3 / ExoPlayer is accessed reflectively in places; keep it intact.
+-keep class androidx.media3.** { *; }
+-dontwarn androidx.media3.**

src-tauri/android/build.gradle.kts

@@ -1,39 +0,0 @@
-plugins {
-    id("com.android.library")
-    id("org.jetbrains.kotlin.android")
-}
-
-android {
-    namespace = "com.dtourolle.jellytau.player"
-    compileSdk = 36
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    buildTypes {
-        getByName("debug") {
-        }
-        getByName("release") {
-            isMinifyEnabled = false
-        }
-    }
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_1_8
-        targetCompatibility = JavaVersion.VERSION_1_8
-    }
-
-    kotlinOptions {
-        jvmTarget = "1.8"
-    }
-}
-
-dependencies {
-    implementation("androidx.media3:media3-exoplayer:1.5.1")
-    implementation("androidx.media3:media3-exoplayer-hls:1.5.1")
-    implementation("androidx.media3:media3-common:1.5.1")
-    implementation("androidx.media3:media3-session:1.5.1")
-    implementation("androidx.media:media:1.7.0") // For MediaSessionCompat and VolumeProviderCompat
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
-}

src-tauri/android/src/main/AndroidManifest.xml

@@ -1,5 +1,67 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!--
+  Authoritative AndroidManifest for JellyTau.
+
+  NOTE: this is NOT a manifest-merger fragment. Gradle only ever reads
+  gen/android/app/src/main/AndroidManifest.xml, and `tauri android init`
+  regenerates that file from tauri.conf.json - dropping everything below.
+  scripts/sync-android-sources.sh copies this file over the generated one,
+  so this is the full manifest and the single source of truth.
+
+  (An earlier version of this file was a partial <application> fragment on the
+  assumption that Tauri merged it. It did not: the hardwareAccelerated flag it
+  declared never reached any built APK. It is folded in properly below.)
+-->
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <!-- Enable hardware acceleration for video playback performance -->
-    <application android:hardwareAccelerated="true" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <!-- AndroidTV support -->
+    <uses-feature android:name="android.software.leanback" android:required="false" />
+
+    <application
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:theme="@style/Theme.jellytau"
+        android:hardwareAccelerated="true"
+        android:usesCleartextTraffic="${usesCleartextTraffic}">
+        <activity
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|density"
+            android:launchMode="singleTask"
+            android:label="@string/main_activity_title"
+            android:name=".MainActivity"
+            android:exported="true"
+            android:supportsPictureInPicture="true"
+            android:resizeableActivity="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+                <!-- AndroidTV support -->
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <provider
+          android:name="androidx.core.content.FileProvider"
+          android:authorities="${applicationId}.fileprovider"
+          android:exported="false"
+          android:grantUriPermissions="true">
+          <meta-data
+            android:name="android.support.FILE_PROVIDER_PATHS"
+            android:resource="@xml/file_paths" />
+        </provider>
+
+        <!-- Media playback service for lockscreen controls -->
+        <service
+            android:name="com.dtourolle.jellytau.player.JellyTauPlaybackService"
+            android:foregroundServiceType="mediaPlayback"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="androidx.media3.session.MediaSessionService" />
+            </intent-filter>
+        </service>
+    </application>
 </manifest>

src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt

@@ -22,6 +22,34 @@ class MainActivity : TauriActivity() {
   private var audioFocusRequest: AudioFocusRequest? = null
   private val audioManager by lazy { getSystemService(Context.AUDIO_SERVICE) as AudioManager }
 
+  /**
+   * Coarse override for whether backgrounding the app should auto-enter PiP.
+   *
+   * This is NOT what excludes audio/browsing/cast from PiP — that is the
+   * PictureInPictureManager.canEnterPip guard, which requires a local video
+   * surface to be actively rendering and is re-checked in onUserLeaveHint. This
+   * flag is only toggled by the background-audio feature (via
+   * AndroidPictureInPicture.setAutoEnterEnabled) so background-audio mode and
+   * auto-PiP stay mutually exclusive.
+   */
+  @Volatile
+  private var autoEnterPipEnabled = true
+
+  /**
+   * Whether the user armed background-audio mode on the current video (UR-040).
+   * When true, leaving the app hands audio off to the native ExoPlayer audio
+   * service (frontend-driven) instead of entering PiP, and video decode stops.
+   * The frontend sets this via AndroidBackgroundAudio.setEnabled.
+   */
+  @Volatile
+  private var backgroundAudioEnabled = false
+
+  /**
+   * The WebView carrying the Svelte UI, cached once found so lifecycle overrides
+   * can dispatch DOM events into it (native → frontend signalling).
+   */
+  private var mediaWebView: WebView? = null
+
   override fun onCreate(savedInstanceState: Bundle?) {
     enableEdgeToEdge()
     super.onCreate(savedInstanceState)
@@ -37,6 +65,75 @@ class MainActivity : TauriActivity() {
     configureWebViewForMedia()
   }
 
+  /**
+   * Called when the user leaves the app via Home or the gesture equivalent
+   * (but NOT via Back). This is the standard hook for auto-entering PiP so
+   * video keeps playing in a floating window instead of being backgrounded.
+   *
+   * TRACES: UR-041 | IR-026 | DR-053
+   */
+  override fun onUserLeaveHint() {
+    super.onUserLeaveHint()
+    // Never enter PiP while background-audio mode is armed — the two are mutually
+    // exclusive (the handoff runs from onStop instead).
+    if (autoEnterPipEnabled && !backgroundAudioEnabled &&
+        PictureInPictureManager.canEnterPip(this)) {
+      android.util.Log.d("MainActivity", "User leaving with video active - entering PiP")
+      PictureInPictureManager.enterPip(this)
+    }
+  }
+
+  /**
+   * The app is no longer visible (Home, app switch, or screen lock). When
+   * background-audio mode is armed, tell the frontend to hand video playback off
+   * to the native audio service. onStop (rather than onUserLeaveHint) is used
+   * because it fires on screen-lock too, which is the primary use case (UR-040).
+   *
+   * TRACES: UR-040 | IR-025
+   */
+  override fun onStop() {
+    super.onStop()
+    if (backgroundAudioEnabled) {
+      dispatchWebEvent("jellytau-background")
+    }
+  }
+
+  /** The app is visible again — tell the frontend to resume WebView video. */
+  override fun onStart() {
+    super.onStart()
+    if (backgroundAudioEnabled) {
+      dispatchWebEvent("jellytau-foreground")
+    }
+  }
+
+  /**
+   * Dispatch a DOM CustomEvent into the WebView (native → frontend). Mirrors the
+   * evaluateJavascript pattern already used to unmute video elements. Posted to
+   * the WebView thread; safe no-op if the WebView isn't found yet.
+   */
+  private fun dispatchWebEvent(name: String) {
+    val webView = mediaWebView ?: run {
+      android.util.Log.w("MainActivity", "dispatchWebEvent('$name'): no WebView")
+      return
+    }
+    webView.post {
+      webView.evaluateJavascript(
+        "window.dispatchEvent(new CustomEvent('$name'));",
+        null
+      )
+      android.util.Log.d("MainActivity", "Dispatched web event: $name")
+    }
+  }
+
+  override fun onPictureInPictureModeChanged(
+    isInPictureInPictureMode: Boolean,
+    newConfig: android.content.res.Configuration
+  ) {
+    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
+    android.util.Log.d("MainActivity", "PiP mode changed: $isInPictureInPictureMode")
+    PictureInPictureManager.onPipModeChanged(this, isInPictureInPictureMode)
+  }
+
   private fun configureWebViewForMedia() {
     try {
       val webView = findWebView(window.decorView)
@@ -55,6 +152,7 @@ class MainActivity : TauriActivity() {
       }
 
       android.util.Log.d("MainActivity", "WebView found! Configuring settings...")
+      mediaWebView = webView
 
       // Add JavaScript interface for audio focus control
       webView.addJavascriptInterface(object : Any() {
@@ -70,6 +168,52 @@ class MainActivity : TauriActivity() {
       }, "AndroidAudioFocus")
       android.util.Log.d("MainActivity", "JavaScript interface 'AndroidAudioFocus' added")
 
+      // Add JavaScript interface for picture-in-picture control.
+      // enterPip/canEnterPip must run on the main thread; @JavascriptInterface
+      // methods are invoked on a WebView binder thread.
+      webView.addJavascriptInterface(object : Any() {
+        @JavascriptInterface
+        fun enterPip() {
+          handler.post { PictureInPictureManager.enterPip(this@MainActivity) }
+        }
+
+        /** Whether the PiP button should be offered in the player UI at all. */
+        @JavascriptInterface
+        fun isSupported(): Boolean {
+          return PictureInPictureManager.isPipSupported(this@MainActivity)
+        }
+
+        /** Whether entering PiP would work right now (local video playing). */
+        @JavascriptInterface
+        fun canEnterPip(): Boolean {
+          return PictureInPictureManager.canEnterPip(this@MainActivity)
+        }
+
+        /** Let the frontend opt out of auto-PiP (e.g. while casting). */
+        @JavascriptInterface
+        fun setAutoEnterEnabled(enabled: Boolean) {
+          autoEnterPipEnabled = enabled
+        }
+      }, "AndroidPictureInPicture")
+      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidPictureInPicture' added")
+
+      // Add JavaScript interface for background-audio mode (UR-040). The frontend
+      // arms/disarms it via the player toggle; the Activity uses the flag in its
+      // lifecycle overrides to decide between the audio handoff and PiP.
+      webView.addJavascriptInterface(object : Any() {
+        /** Frontend arms/disarms background-audio mode for the current video. */
+        @JavascriptInterface
+        fun setEnabled(enabled: Boolean) {
+          backgroundAudioEnabled = enabled
+          android.util.Log.d("MainActivity", "backgroundAudioEnabled = $enabled")
+        }
+
+        /** Whether background audio is available on this device (needs PiP-era APIs unnecessary; audio service always present on Android). */
+        @JavascriptInterface
+        fun isSupported(): Boolean = true
+      }, "AndroidBackgroundAudio")
+      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidBackgroundAudio' added")
+
       // Set WebChromeClient to handle video playback and audio focus
       webView.webChromeClient = object : WebChromeClient() {
         override fun onShowCustomView(view: View?, callback: CustomViewCallback?) {
@@ -93,7 +237,6 @@ class MainActivity : TauriActivity() {
         domStorageEnabled = true
         allowFileAccess = true
         allowContentAccess = true
-        setRenderPriority(WebSettings.RenderPriority.HIGH)
         mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
 
         android.util.Log.d("MainActivity", "WebView fully configured for media playback")

src-tauri/android/src/main/java/com/dtourolle/jellytau/PictureInPictureManager.kt

@@ -0,0 +1,312 @@
+package com.dtourolle.jellytau
+
+import android.app.Activity
+import android.app.PictureInPictureParams
+import android.app.RemoteAction
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.graphics.drawable.Icon
+import android.os.Build
+import android.util.Rational
+import android.view.ViewGroup
+import android.webkit.WebView
+import androidx.annotation.RequiresApi
+import com.dtourolle.jellytau.player.JellyTauPlayer
+
+/**
+ * Drives Android picture-in-picture for native (ExoPlayer) video playback.
+ *
+ * TRACES: UR-041 | IR-026 | DR-053
+ *
+ * PiP shrinks the whole Activity into a floating window, so the only thing that
+ * should remain visible is the video SurfaceView that [VideoOverlayManager]
+ * attached at the bottom of the z-order. The WebView carrying the Svelte UI is
+ * hidden for the duration - it is opaque and sits *above* the surface, so
+ * leaving it visible would occlude the video entirely.
+ *
+ * Playback itself is untouched: ExoPlayer keeps rendering into the same surface
+ * across the transition, so entering and leaving PiP never interrupts the video.
+ */
+object PictureInPictureManager {
+
+    private const val TAG = "PictureInPictureManager"
+
+    /** Action for the play/pause RemoteAction shown inside the PiP window. */
+    private const val ACTION_MEDIA_CONTROL = "com.dtourolle.jellytau.PIP_MEDIA_CONTROL"
+    private const val EXTRA_CONTROL_TYPE = "control_type"
+    private const val CONTROL_PLAY = 1
+    private const val CONTROL_PAUSE = 2
+
+    /** Request codes must differ per action or the PendingIntents collapse into one. */
+    private const val REQUEST_PLAY = 101
+    private const val REQUEST_PAUSE = 102
+
+    private var receiver: BroadcastReceiver? = null
+    private var hiddenWebView: WebView? = null
+
+    /**
+     * Whether this device/OS can do PiP at all. Android 8.0 introduced the API,
+     * and the user (or device manufacturer) can disable the feature per-app.
+     */
+    fun isPipSupported(activity: Activity): Boolean {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return false
+        return activity.packageManager.hasSystemFeature(
+            android.content.pm.PackageManager.FEATURE_PICTURE_IN_PICTURE
+        )
+    }
+
+    /**
+     * Whether entering PiP right now makes sense: a native video must actually
+     * be playing locally. Audio-only playback and remote/cast sessions render
+     * nothing on this device, so a PiP window would be an empty black box.
+     */
+    fun canEnterPip(activity: Activity): Boolean {
+        if (!isPipSupported(activity)) return false
+        return try {
+            val player = JellyTauPlayer.getInstance()
+            player.isPlayingVideo() &&
+                player.getSurfaceView() != null &&
+                VideoOverlayManager.isVideoSurfaceAttached()
+        } catch (e: Exception) {
+            android.util.Log.w(TAG, "canEnterPip check failed", e)
+            false
+        }
+    }
+
+    /**
+     * Enter picture-in-picture, sizing the window to the video's aspect ratio.
+     *
+     * @return true if the system accepted the transition.
+     */
+    fun enterPip(activity: Activity): Boolean {
+        if (!canEnterPip(activity)) {
+            android.util.Log.d(TAG, "Not entering PiP: no local video playing")
+            return false
+        }
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return false
+
+        return try {
+            val params = buildParams(activity)
+            val entered = activity.enterPictureInPictureMode(params)
+            android.util.Log.d(TAG, "enterPictureInPictureMode returned $entered")
+            entered
+        } catch (e: Exception) {
+            // IllegalStateException here means PiP is disallowed (e.g. the user
+            // turned it off in system settings). Never crash over it.
+            android.util.Log.e(TAG, "Failed to enter PiP", e)
+            false
+        }
+    }
+
+    /**
+     * Build PiP params: aspect ratio from the current video, plus a play/pause
+     * RemoteAction reflecting the live playback state.
+     */
+    @RequiresApi(Build.VERSION_CODES.O)
+    private fun buildParams(activity: Activity): PictureInPictureParams {
+        val builder = PictureInPictureParams.Builder()
+
+        aspectRatioFor()?.let { builder.setAspectRatio(it) }
+        builder.setActions(listOf(buildPlayPauseAction(activity)))
+
+        return builder.build()
+    }
+
+    /**
+     * The video's aspect ratio, clamped to the range Android accepts.
+     *
+     * The platform rejects ratios outside roughly 1:2.39 - 2.39:1 with an
+     * IllegalArgumentException, which would otherwise take down the Activity on
+     * unusually tall or wide content.
+     */
+    private fun aspectRatioFor(): Rational? {
+        val player = try {
+            JellyTauPlayer.getInstance()
+        } catch (e: Exception) {
+            return null
+        }
+
+        val surface = player.getSurfaceView() ?: return null
+        // The surface has already been letterboxed to the video's aspect ratio
+        // by fitSurfaceToScreen(), so its measured bounds are the video shape.
+        val width = surface.width
+        val height = surface.height
+        if (width <= 0 || height <= 0) return null
+
+        val ratio = width.toDouble() / height.toDouble()
+        val minRatio = 1.0 / 2.39
+        val maxRatio = 2.39
+        val clamped = ratio.coerceIn(minRatio, maxRatio)
+
+        // Scale to integers; Rational(width, height) directly can overflow for
+        // large surfaces, and the clamped value may not match the raw pixels.
+        return Rational((clamped * 1000).toInt(), 1000)
+    }
+
+    @RequiresApi(Build.VERSION_CODES.O)
+    private fun buildPlayPauseAction(activity: Activity): RemoteAction {
+        val isPlaying = try {
+            JellyTauPlayer.getInstance().getExoPlayer().isPlaying
+        } catch (e: Exception) {
+            false
+        }
+
+        val (iconRes, title, controlType, requestCode) = if (isPlaying) {
+            Quad(
+                android.R.drawable.ic_media_pause,
+                "Pause",
+                CONTROL_PAUSE,
+                REQUEST_PAUSE
+            )
+        } else {
+            Quad(
+                android.R.drawable.ic_media_play,
+                "Play",
+                CONTROL_PLAY,
+                REQUEST_PLAY
+            )
+        }
+
+        val intent = Intent(ACTION_MEDIA_CONTROL)
+            .putExtra(EXTRA_CONTROL_TYPE, controlType)
+            // Explicit package keeps the broadcast internal to the app.
+            .setPackage(activity.packageName)
+
+        val flags = android.app.PendingIntent.FLAG_UPDATE_CURRENT or
+            android.app.PendingIntent.FLAG_IMMUTABLE
+
+        val pendingIntent = android.app.PendingIntent.getBroadcast(
+            activity,
+            requestCode,
+            intent,
+            flags
+        )
+
+        return RemoteAction(
+            Icon.createWithResource(activity, iconRes),
+            title,
+            title,
+            pendingIntent
+        )
+    }
+
+    private data class Quad<A, B, C, D>(
+        val first: A,
+        val second: B,
+        val third: C,
+        val fourth: D
+    )
+
+    /**
+     * Refresh the PiP window's action button so it tracks play/pause state
+     * while the window is open. Safe to call when not in PiP (no-op).
+     */
+    fun updatePipActions(activity: Activity) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        if (!activity.isInPictureInPictureMode) return
+        try {
+            activity.setPictureInPictureParams(buildParams(activity))
+        } catch (e: Exception) {
+            android.util.Log.w(TAG, "Failed to update PiP actions", e)
+        }
+    }
+
+    /**
+     * Called from MainActivity.onPictureInPictureModeChanged.
+     *
+     * Entering: hide the WebView so only the video surface shows, and register
+     * the receiver backing the PiP play/pause button.
+     * Leaving: restore the WebView and unregister.
+     */
+    fun onPipModeChanged(activity: Activity, isInPipMode: Boolean) {
+        if (isInPipMode) {
+            hideWebView(activity)
+            registerReceiver(activity)
+        } else {
+            unregisterReceiver(activity)
+            showWebView()
+            // The surface was laid out against the tiny PiP bounds; re-fit it to
+            // the restored full-screen bounds or the video stays postage-stamp sized.
+            try {
+                JellyTauPlayer.getInstance().fitSurfaceToScreen()
+            } catch (e: Exception) {
+                android.util.Log.w(TAG, "Failed to re-fit surface after PiP", e)
+            }
+        }
+    }
+
+    private fun hideWebView(activity: Activity) {
+        val webView = findWebView(activity.window.decorView)
+        if (webView == null) {
+            android.util.Log.w(TAG, "No WebView found to hide for PiP")
+            return
+        }
+        // GONE rather than INVISIBLE: the WebView is opaque, and GONE also stops
+        // it from consuming layout space in the shrunken window.
+        webView.visibility = android.view.View.GONE
+        hiddenWebView = webView
+        android.util.Log.d(TAG, "WebView hidden for PiP")
+    }
+
+    private fun showWebView() {
+        hiddenWebView?.let {
+            it.visibility = android.view.View.VISIBLE
+            android.util.Log.d(TAG, "WebView restored after PiP")
+        }
+        hiddenWebView = null
+    }
+
+    private fun registerReceiver(activity: Activity) {
+        if (receiver != null) return
+
+        val r = object : BroadcastReceiver() {
+            override fun onReceive(context: Context?, intent: Intent?) {
+                if (intent?.action != ACTION_MEDIA_CONTROL) return
+                val player = try {
+                    JellyTauPlayer.getInstance()
+                } catch (e: Exception) {
+                    return
+                }
+                when (intent.getIntExtra(EXTRA_CONTROL_TYPE, 0)) {
+                    CONTROL_PLAY -> player.play()
+                    CONTROL_PAUSE -> player.pause()
+                }
+                // Swap the button to reflect the new state.
+                updatePipActions(activity)
+            }
+        }
+
+        val filter = IntentFilter(ACTION_MEDIA_CONTROL)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            activity.registerReceiver(r, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            activity.registerReceiver(r, filter)
+        }
+        receiver = r
+        android.util.Log.d(TAG, "PiP media control receiver registered")
+    }
+
+    private fun unregisterReceiver(activity: Activity) {
+        receiver?.let {
+            try {
+                activity.unregisterReceiver(it)
+            } catch (e: IllegalArgumentException) {
+                // Already unregistered - harmless.
+            }
+        }
+        receiver = null
+    }
+
+    private fun findWebView(view: android.view.View): WebView? {
+        if (view is WebView) return view
+        if (view is ViewGroup) {
+            for (i in 0 until view.childCount) {
+                findWebView(view.getChildAt(i))?.let { return it }
+            }
+        }
+        return null
+    }
+}

src-tauri/android/src/main/java/com/dtourolle/jellytau/VideoOverlayManager.kt

@@ -0,0 +1,114 @@
+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
+    private var contentLayoutListener: android.view.View.OnLayoutChangeListener? = null
+    private var listenerContentView: ViewGroup? = 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
+
+            // Re-fit the video whenever the content view's bounds change (e.g. on
+            // device rotation) so the video is letterboxed to fit instead of being
+            // stretched/cropped by the MATCH_PARENT surface.
+            removeLayoutListener()
+            val listener = android.view.View.OnLayoutChangeListener {
+                _, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom ->
+                if (right - left != oldRight - oldLeft || bottom - top != oldBottom - oldTop) {
+                    player.fitSurfaceToScreen()
+                }
+            }
+            contentView.addOnLayoutChangeListener(listener)
+            contentLayoutListener = listener
+            listenerContentView = contentView
+
+            // Fit once now that the surface is attached and the parent is sized.
+            player.fitSurfaceToScreen()
+
+            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 {
+            removeLayoutListener()
+            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
+    }
+
+    private fun removeLayoutListener() {
+        contentLayoutListener?.let { listener ->
+            listenerContentView?.removeOnLayoutChangeListener(listener)
+        }
+        contentLayoutListener = null
+        listenerContentView = null
+    }
+}

src-tauri/android/src/main/java/com/dtourolle/jellytau/player/AlbumArtCache.kt

@@ -0,0 +1,142 @@
+package com.dtourolle.jellytau.player
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.util.LruCache
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Memory cache for album artwork bitmaps with LRU eviction.
+ *
+ * Features:
+ * - LruCache for efficient memory usage (1/8 of heap, typically 12-16MB)
+ * - Automatic bitmap scaling to 512x512 max (lock screen optimal size)
+ * - Async HTTP downloads using Dispatchers.IO (non-blocking)
+ * - Graceful error handling for network failures and corrupted images
+ * - Singleton pattern for app-wide access
+ *
+ * Cache lifecycle: In-memory only, cleared on app termination.
+ */
+class AlbumArtCache(context: Context) {
+    private val maxMemory = (Runtime.getRuntime().maxMemory() / 1024).toInt()
+    private val cacheSize = maxMemory / 8  // Use 1/8 of available heap
+
+    private val memoryCache = object : LruCache<String, Bitmap>(cacheSize) {
+        override fun sizeOf(key: String, bitmap: Bitmap): Int {
+            return bitmap.byteCount / 1024  // Size in KB
+        }
+    }
+
+    /**
+     * Get artwork bitmap for the given URL.
+     *
+     * Checks memory cache first, then downloads from network if not cached.
+     * Scaling and error handling are done transparently.
+     *
+     * @param url The Jellyfin server artwork URL
+     * @return The bitmap, or null if download failed or URL is invalid
+     */
+    suspend fun getArtwork(url: String): Bitmap? {
+        // Check memory cache first
+        memoryCache.get(url)?.let { return it }
+
+        // Download from network if not cached
+        return downloadAndCache(url)
+    }
+
+    /**
+     * Download artwork from network and add to cache.
+     *
+     * Runs on IO dispatcher to avoid blocking the main thread.
+     * Automatically scales large images to 512x512 max.
+     * On failure, logs error and returns null.
+     *
+     * @param url The Jellyfin server artwork URL
+     * @return The cached bitmap, or null if download/decode failed
+     */
+    private suspend fun downloadAndCache(url: String): Bitmap? = withContext(Dispatchers.IO) {
+        try {
+            val connection = URL(url).openConnection() as HttpURLConnection
+            connection.doInput = true
+            connection.connectTimeout = 5000
+            connection.readTimeout = 5000
+            connection.connect()
+
+            if (connection.responseCode != HttpURLConnection.HTTP_OK) {
+                android.util.Log.w("AlbumArtCache", "Failed to download artwork: HTTP ${connection.responseCode}")
+                return@withContext null
+            }
+
+            val input = connection.inputStream
+            val bitmap = BitmapFactory.decodeStream(input)
+            input.close()
+            connection.disconnect()
+
+            bitmap?.let {
+                // Scale down if too large (lock screen doesn't need full resolution)
+                val scaled = scaleDownIfNeeded(it, MAX_ARTWORK_SIZE)
+                memoryCache.put(url, scaled)
+                android.util.Log.d("AlbumArtCache", "Cached artwork: ${scaled.width}x${scaled.height}")
+                scaled
+            }
+        } catch (e: Exception) {
+            android.util.Log.e("AlbumArtCache", "Failed to download artwork: ${e.message}", e)
+            null
+        }
+    }
+
+    /**
+     * Scale down bitmap if it exceeds max size while maintaining aspect ratio.
+     *
+     * @param bitmap The original bitmap
+     * @param maxSize Maximum width or height (e.g., 512)
+     * @return Original bitmap if smaller than maxSize, else scaled version
+     */
+    private fun scaleDownIfNeeded(bitmap: Bitmap, maxSize: Int): Bitmap {
+        if (bitmap.width <= maxSize && bitmap.height <= maxSize) return bitmap
+
+        val ratio = minOf(
+            maxSize.toFloat() / bitmap.width,
+            maxSize.toFloat() / bitmap.height
+        )
+
+        val newWidth = (bitmap.width * ratio).toInt()
+        val newHeight = (bitmap.height * ratio).toInt()
+
+        return Bitmap.createScaledBitmap(bitmap, newWidth, newHeight, true)
+    }
+
+    /**
+     * Clear all cached bitmaps from memory.
+     *
+     * Useful for memory-constrained situations or settings reset.
+     */
+    fun clear() {
+        memoryCache.evictAll()
+    }
+
+    companion object {
+        private const val MAX_ARTWORK_SIZE = 512  // 512x512 max for lock screen
+
+        @Volatile
+        private var instance: AlbumArtCache? = null
+
+        /**
+         * Get or create singleton instance.
+         *
+         * Thread-safe with double-checked locking pattern.
+         *
+         * @param context Android context for initialization
+         * @return The singleton AlbumArtCache instance
+         */
+        fun getInstance(context: Context): AlbumArtCache {
+            return instance ?: synchronized(this) {
+                instance ?: AlbumArtCache(context).also { instance = it }
+            }
+        }
+    }
+}

src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt

@@ -87,48 +87,39 @@ class JellyTauPlaybackService : MediaSessionService() {
         val jellyTauPlayer = JellyTauPlayer.getInstance()
         val exoPlayer = jellyTauPlayer.getExoPlayer()
 
-        // Wrap the ExoPlayer to intercept commands
+        // Wrap the ExoPlayer to intercept commands from Media3 controllers
+        // (e.g. Android Auto / Wear / system surfaces that bind to the Media3
+        // session rather than the MediaSessionCompat).
+        //
+        // We do NOT execute on ExoPlayer directly here. Every transport command
+        // is routed to Rust via nativeOnMediaCommand, which is the single decision
+        // point: in local mode Rust drives ExoPlayer, in remote (cast) mode Rust
+        // forwards to the remote Jellyfin session. Executing on ExoPlayer here too
+        // would double-handle local commands and incorrectly drive the local
+        // player while casting.
         wrappedPlayer = object : ForwardingPlayer(exoPlayer) {
             override fun play() {
-                // Execute immediately for instant lockscreen response
-                super.play()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("play")
             }
 
             override fun pause() {
-                // Execute immediately for instant lockscreen response
-                super.pause()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("pause")
             }
 
             override fun seekToNext() {
-                // Execute immediately for instant lockscreen response
-                super.seekToNext()
-                // Then notify Rust for queue management
                 nativeOnMediaCommand("next")
             }
 
             override fun seekToPrevious() {
-                // Execute immediately for instant lockscreen response
-                super.seekToPrevious()
-                // Then notify Rust for queue management
                 nativeOnMediaCommand("previous")
             }
 
             override fun seekTo(positionMs: Long) {
-                // Execute immediately for instant lockscreen response
-                super.seekTo(positionMs)
-                // Then notify Rust of seek
                 val positionSeconds = positionMs / 1000.0
                 nativeOnMediaCommand("seek:$positionSeconds")
             }
 
             override fun stop() {
-                // Execute immediately for instant lockscreen response
-                super.stop()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("stop")
             }
         }
@@ -160,36 +151,47 @@ class JellyTauPlaybackService : MediaSessionService() {
             )
             isActive = true
 
-            // Set callback to handle lock screen button presses
+            // Set callback to handle lock screen button presses.
+            //
+            // All transport commands are routed through Rust via nativeOnMediaCommand
+            // rather than directly to ExoPlayer. Rust is the single decision point:
+            // in local mode it drives ExoPlayer, in remote (cast) mode it forwards
+            // the command to the remote Jellyfin session. This keeps the lockscreen
+            // working identically for both, and avoids the ExoPlayer-only behaviour
+            // that left remote playback uncontrollable from the lockscreen.
             setCallback(object : MediaSessionCompat.Callback() {
                 override fun onPlay() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Play pressed")
-                    wrappedPlayer?.play()
+                    nativeOnMediaCommand("play")
                 }
 
                 override fun onPause() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Pause pressed")
-                    wrappedPlayer?.pause()
+                    nativeOnMediaCommand("pause")
                 }
 
                 override fun onSkipToNext() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Next pressed")
-                    wrappedPlayer?.seekToNext()
+                    nativeOnMediaCommand("next")
                 }
 
                 override fun onSkipToPrevious() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Previous pressed")
-                    wrappedPlayer?.seekToPrevious()
+                    nativeOnMediaCommand("previous")
                 }
 
                 override fun onStop() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Stop pressed")
-                    wrappedPlayer?.stop()
+                    nativeOnMediaCommand("stop")
                 }
 
                 override fun onSeekTo(position: Long) {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Seek to $position")
-                    wrappedPlayer?.seekTo(position)
+                    // The scrubber is absolute; Rust owns the seek in absolute terms
+                    // (in a background-audio handoff it rebuilds the stream at this
+                    // StartTimeTicks). Send the absolute position as-is.
+                    val positionSeconds = position / 1000.0
+                    nativeOnMediaCommand("seek:$positionSeconds")
                 }
             })
         }
@@ -253,9 +255,38 @@ class JellyTauPlaybackService : MediaSessionService() {
             .build()
     }
 
+    // Last-known metadata/state, retained so lightweight position ticks can
+    // rebuild a correct PlaybackState without re-sending the (heavier) metadata
+    // and notification. Kept in sync by updateMediaMetadata().
+    private var lastTitle: String = ""
+    private var lastArtist: String = ""
+    private var lastIsPlaying: Boolean = false
+
+    // Base offset (ms) added to every position reported to the lockscreen
+    // MediaSession. During a background-audio handoff the audio stream is
+    // requested with StartTimeTicks = the handoff point, so ExoPlayer reports
+    // position RELATIVE to that point (starting at 0). The metadata duration,
+    // however, is the full absolute length — so without this base the scrubber
+    // thumb sits near 0:00 on a full-length bar. Set from the known handoff
+    // position via setPositionOffset(); 0 for normal playback.
+    private var positionOffsetMs: Long = 0L
+
     /**
-     * Update the MediaSession metadata and playback state.
-     * This updates both the MediaSession and the notification.
+     * Set the base position offset (seconds) applied to lockscreen positions.
+     * Called by the native layer when entering/exiting a background-audio handoff.
+     * Pass 0 to clear (normal playback, where ExoPlayer's position is absolute).
+     */
+    fun setPositionOffset(offsetSeconds: Double) {
+        positionOffsetMs = (offsetSeconds * 1000.0).toLong().coerceAtLeast(0L)
+        android.util.Log.d("JellyTauPlaybackService", "Position offset set to ${positionOffsetMs}ms")
+    }
+
+    /**
+     * Update the MediaSession metadata and playback state, plus the notification.
+     *
+     * Call this when the track or play/pause state changes. For frequent position
+     * updates during playback, use [updatePlaybackPosition] instead, which is much
+     * cheaper (no metadata rebuild, no notification rebuild).
      */
     fun updateMediaMetadata(
         title: String,
@@ -267,6 +298,10 @@ class JellyTauPlaybackService : MediaSessionService() {
     ) {
         val session = mediaSessionCompat ?: return
 
+        lastTitle = title
+        lastArtist = artist
+        lastIsPlaying = isPlaying
+
         // Update MediaSession metadata
         val metadataBuilder = android.support.v4.media.MediaMetadataCompat.Builder()
             .putString(android.support.v4.media.MediaMetadataCompat.METADATA_KEY_TITLE, title)
@@ -279,8 +314,61 @@ class JellyTauPlaybackService : MediaSessionService() {
 
         session.setMetadata(metadataBuilder.build())
 
-        // Update MediaSession playback state
-        val stateBuilder = PlaybackStateCompat.Builder()
+        // Update MediaSession playback state (position made absolute via the base offset).
+        session.setPlaybackState(buildPlaybackState(isPlaying, position + positionOffsetMs))
+
+        // While casting, re-assert the remote volume provider. Metadata pushes
+        // arrive on the session poller thread and can race with (or arrive
+        // before) enableRemoteVolume(); this keeps the session routed to the
+        // remote (absolute) volume slider instead of the local media stream.
+        if (isRemoteVolumeEnabled) {
+            volumeProvider?.let { session.setPlaybackToRemote(it) }
+        }
+
+        // Update the notification
+        updateNotification(title, artist, isPlaying)
+    }
+
+    /**
+     * Update only the playback position (and play/pause state) on the MediaSession.
+     *
+     * This is the cheap path used for the periodic (250ms) position ticks: it
+     * refreshes the lockscreen scrubber without rebuilding metadata or the
+     * notification. Without this, the lockscreen scrubber freezes at the position
+     * from the last play/pause and drifts out of sync with actual playback.
+     *
+     * @param position Position in milliseconds
+     * @param isPlaying Whether playback is currently active
+     */
+    fun updatePlaybackPosition(position: Long, isPlaying: Boolean) {
+        val session = mediaSessionCompat ?: return
+        val notificationStateChanged = isPlaying != lastIsPlaying
+        lastIsPlaying = isPlaying
+        // Absolute position for the scrubber = relative ExoPlayer position + base offset.
+        session.setPlaybackState(buildPlaybackState(isPlaying, position + positionOffsetMs))
+        // Only rebuild the notification when the play/pause icon actually flips.
+        if (notificationStateChanged) {
+            updateNotification(lastTitle, lastArtist, isPlaying)
+        }
+    }
+
+    /**
+     * Build a PlaybackStateCompat with the standard transport actions.
+     *
+     * The reported playback speed is 1.0 while playing and 0.0 while paused so
+     * Android does not extrapolate the position past a paused track.
+     *
+     * While remote volume control is enabled (casting), the state is forced to
+     * STATE_PLAYING regardless of [isPlaying]. Android only surfaces the remote
+     * (absolute) volume slider for a session that is actively playing; if a
+     * periodic metadata/position push reports paused (e.g. before the remote
+     * session has actually started), reporting STATE_PAUSED here makes the
+     * system tear down the remote slider set up by setPlaybackToRemote() and
+     * fall back to the local media-stream volume.
+     */
+    private fun buildPlaybackState(isPlaying: Boolean, position: Long): PlaybackStateCompat {
+        val playing = isPlaying || isRemoteVolumeEnabled
+        return PlaybackStateCompat.Builder()
             .setActions(
                 PlaybackStateCompat.ACTION_PLAY or
                 PlaybackStateCompat.ACTION_PAUSE or
@@ -290,15 +378,11 @@ class JellyTauPlaybackService : MediaSessionService() {
                 PlaybackStateCompat.ACTION_SEEK_TO
             )
             .setState(
-                if (isPlaying) PlaybackStateCompat.STATE_PLAYING else PlaybackStateCompat.STATE_PAUSED,
+                if (playing) PlaybackStateCompat.STATE_PLAYING else PlaybackStateCompat.STATE_PAUSED,
                 position,
-                1.0f
+                if (playing) 1.0f else 0.0f
             )
-
-        session.setPlaybackState(stateBuilder.build())
-
-        // Update the notification
-        updateNotification(title, artist, isPlaying)
+            .build()
     }
 
     /**

src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt

@@ -138,11 +138,22 @@ class JellyTauPlayer(private val appContext: Context) {
     /** Current media ID being played */
     private var currentMediaId: String? = null
 
+    /**
+     * Guards against nativeOnPlaybackEnded() firing more than once per loaded
+     * media. ExoPlayer can re-enter STATE_ENDED (e.g. transient buffering near
+     * end of a transcoded stream), which would otherwise notify the backend
+     * twice and, for example, decrement the sleep-timer episode counter twice.
+     * Reset whenever new media is loaded.
+     */
+    private var endedNotified = false
+
     /** Current media metadata for notification updates */
     private var currentTitle: String = ""
     private var currentArtist: String = ""
     private var currentAlbum: String? = null
     private var currentDurationMs: Long = 0
+    private var currentArtworkUrl: String? = null
+    private var currentArtworkBitmap: android.graphics.Bitmap? = null
 
     /** Media type enum */
     enum class MediaType { AUDIO, VIDEO }
@@ -150,6 +161,9 @@ class JellyTauPlayer(private val appContext: Context) {
     /** SurfaceView for video playback */
     private var surfaceView: SurfaceView? = null
     private var surfaceHolder: SurfaceHolder? = null
+    /** Last reported video frame size, used to fit the surface to the screen preserving aspect ratio */
+    private var videoWidth: Int = 0
+    private var videoHeight: Int = 0
     private var currentMediaType: MediaType = MediaType.AUDIO
     private var currentActivity: java.lang.ref.WeakReference<android.app.Activity>? = null
 
@@ -169,6 +183,12 @@ class JellyTauPlayer(private val appContext: Context) {
         // Create ExoPlayer with audio focus handling
         exoPlayer = ExoPlayer.Builder(appContext)
             .setAudioAttributes(audioAttributes, /* handleAudioFocus= */ true)
+            // Pause when the audio output is removed (wired headphones unplugged or
+            // Bluetooth device disconnected). ExoPlayer listens for the system
+            // ACTION_AUDIO_BECOMING_NOISY broadcast, which fires for both cases.
+            // The resulting pause flows through onIsPlayingChanged, keeping Rust and
+            // the lockscreen notification in sync automatically.
+            .setHandleAudioBecomingNoisy(true)
             .build()
 
         // Set up player listener
@@ -200,7 +220,15 @@ class JellyTauPlayer(private val appContext: Context) {
                         // Playback completed
                         android.util.Log.d("JellyTauPlayer", "▶ Playback ended")
                         stopPositionUpdates()
-                        nativeOnPlaybackEnded()
+                        // Only notify the backend once per loaded media. ExoPlayer
+                        // can re-enter STATE_ENDED, which would double-count things
+                        // like the sleep-timer episode counter.
+                        if (!endedNotified) {
+                            endedNotified = true
+                            nativeOnPlaybackEnded()
+                        } else {
+                            android.util.Log.d("JellyTauPlayer", "▶ Playback ended already notified - ignoring")
+                        }
                     }
                     Player.STATE_BUFFERING -> {
                         android.util.Log.d("JellyTauPlayer", "▶ Buffering...")
@@ -237,7 +265,11 @@ class JellyTauPlayer(private val appContext: Context) {
             }
 
             override fun onVideoSizeChanged(videoSize: androidx.media3.common.VideoSize) {
-                android.util.Log.d("JellyTauPlayer", "▶ Video size: ${videoSize.width}x${videoSize.height}")
+                android.util.Log.d("JellyTauPlayer", "▶ Video size: ${videoSize.width}x${videoSize.height} par=${videoSize.pixelWidthHeightRatio}")
+                // Apply pixel aspect ratio so anamorphic content isn't distorted
+                videoWidth = (videoSize.width * videoSize.pixelWidthHeightRatio).toInt()
+                videoHeight = videoSize.height
+                fitSurfaceToScreen()
             }
 
             override fun onRenderedFirstFrame() {
@@ -314,6 +346,7 @@ class JellyTauPlayer(private val appContext: Context) {
     fun load(url: String, mediaId: String) {
         mainHandler.post {
             currentMediaId = mediaId
+            endedNotified = false
             val mediaItem = MediaItem.fromUri(url)
             exoPlayer.setMediaItem(mediaItem)
             exoPlayer.prepare()
@@ -544,12 +577,15 @@ class JellyTauPlayer(private val appContext: Context) {
     ) {
         mainHandler.post {
             currentMediaId = mediaId
+            endedNotified = false
 
             // Store metadata for notification updates
             currentTitle = title
             currentArtist = artist ?: ""
             currentAlbum = album
             currentDurationMs = durationMs
+            currentArtworkUrl = artworkUrl
+            currentArtworkBitmap = null  // Reset on new track
 
             // Detect media type
             currentMediaType = if (mediaType.equals("video", ignoreCase = true)) {
@@ -666,6 +702,20 @@ class JellyTauPlayer(private val appContext: Context) {
 
             // Start the foreground service for lockscreen controls
             startPlaybackService()
+
+            // Download album art asynchronously (non-blocking)
+            currentArtworkUrl?.let { url ->
+                coroutineScope.launch {
+                    try {
+                        val bitmap = AlbumArtCache.getInstance(appContext).getArtwork(url)
+                        currentArtworkBitmap = bitmap
+                        updatePlaybackServiceNotification(exoPlayer.isPlaying)
+                        android.util.Log.d("JellyTauPlayer", "Album art loaded: ${bitmap?.width}x${bitmap?.height}")
+                    } catch (e: Exception) {
+                        android.util.Log.e("JellyTauPlayer", "Failed to load album art", e)
+                    }
+                }
+            }
         }
     }
 
@@ -717,10 +767,16 @@ class JellyTauPlayer(private val appContext: Context) {
             android.util.Log.d("JellyTauPlayer", "Started position updates coroutine")
             while (isActive) {
                 if (exoPlayer.isPlaying) {
-                    val position = exoPlayer.currentPosition / 1000.0
+                    val positionMs = exoPlayer.currentPosition.coerceAtLeast(0)
+                    val position = positionMs / 1000.0
                     val duration = if (exoPlayer.duration > 0) exoPlayer.duration / 1000.0 else 0.0
                     android.util.Log.v("JellyTauPlayer", "Position update: $position / $duration")
                     nativeOnPositionUpdate(position, duration)
+
+                    // Keep the lockscreen scrubber live. Without this the
+                    // MediaSession position only refreshes on play/pause, so the
+                    // scrubber freezes mid-track and drifts out of sync.
+                    JellyTauPlaybackService.getInstance()?.updatePlaybackPosition(positionMs, true)
                 }
                 delay(POSITION_UPDATE_INTERVAL_MS)
             }
@@ -824,17 +880,62 @@ class JellyTauPlayer(private val appContext: Context) {
 
     /**
      * Resize the video surface (for orientation changes).
+     *
+     * Re-fits the surface to the screen preserving the video's aspect ratio so
+     * nothing is cropped when the device rotates.
      */
     fun resizeSurface(width: Int, height: Int) {
+        fitSurfaceToScreen()
+    }
+
+    /**
+     * Size the video SurfaceView so the video fits entirely inside its parent
+     * (the full-screen content view) while preserving aspect ratio (letterbox/
+     * pillarbox). A raw SurfaceView with MATCH_PARENT otherwise stretches the
+     * video to the surface bounds, which crops the bottom on rotation.
+     */
+    fun fitSurfaceToScreen() {
         mainHandler.post {
-            surfaceView?.let { view ->
-                view.layoutParams = view.layoutParams.apply {
-                    this.width = width
-                    this.height = height
-                }
-                view.requestLayout()
-                android.util.Log.d("JellyTauPlayer", "Video surface resized to ${width}x${height}")
+            val view = surfaceView ?: return@post
+            val parent = view.parent as? ViewGroup
+            // Available area: prefer the parent's measured size, fall back to the screen.
+            val availW = parent?.width?.takeIf { it > 0 }
+                ?: appContext.resources.displayMetrics.widthPixels
+            val availH = parent?.height?.takeIf { it > 0 }
+                ?: appContext.resources.displayMetrics.heightPixels
+
+            if (videoWidth <= 0 || videoHeight <= 0 || availW <= 0 || availH <= 0) {
+                return@post
             }
+
+            val videoAspect = videoWidth.toFloat() / videoHeight.toFloat()
+            val viewAspect = availW.toFloat() / availH.toFloat()
+
+            val targetW: Int
+            val targetH: Int
+            if (videoAspect > viewAspect) {
+                // Video is wider than the screen → fit width, letterbox top/bottom
+                targetW = availW
+                targetH = (availW / videoAspect).toInt()
+            } else {
+                // Video is taller than the screen → fit height, pillarbox sides
+                targetH = availH
+                targetW = (availH * videoAspect).toInt()
+            }
+
+            val lp = view.layoutParams
+            // FrameLayout child: center the fitted surface within the full-screen parent.
+            if (lp is FrameLayout.LayoutParams) {
+                lp.gravity = android.view.Gravity.CENTER
+            }
+            lp.width = targetW
+            lp.height = targetH
+            view.layoutParams = lp
+            view.requestLayout()
+            android.util.Log.d(
+                "JellyTauPlayer",
+                "Video surface fitted to ${targetW}x${targetH} (video ${videoWidth}x${videoHeight}, avail ${availW}x${availH})"
+            )
         }
     }
 

src-tauri/android/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@mipmap/ic_launcher_background"/>
+  <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+</adaptive-icon>