layout and remote fix

Reviewed-on: #9

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

@@ -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
@@ -60,12 +60,24 @@ jobs:
           cargo test
           cd ..
 
-  build:
-    name: Build Android APK
+  # 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
 
     steps:
       - name: Checkout repository
@@ -78,9 +90,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             src-tauri/target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-android-
 
       - name: Cache Node dependencies
         uses: actions/cache@v3
@@ -93,33 +105,13 @@ jobs:
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: |
-          bun install
+        run: bun install
 
-      - name: Build frontend
-        run: bun run build
-
-      - name: Initialize Android project
+      - 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
-          echo "" | bunx tauri android init
-          cd ..
-
-      - name: Build Android APK
-        id: build
-        run: |
-          mkdir -p artifacts
-          bun run tauri android build --apk true
-
-          # 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
-        with:
-          name: jellytau-apk
-          path: ${{ steps.build.outputs.artifact }}
-          retention-days: 30
-          if-no-files-found: error
+          cargo check --target aarch64-linux-android --lib

.gitea/workflows/build-release.yml

@@ -18,37 +18,40 @@ jobs:
   test:
     name: Run Tests
     runs-on: linux/amd64
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
-      - name: Setup Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
       - name: Cache Rust dependencies
         uses: actions/cache@v3
         with:
           path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/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
@@ -63,45 +66,32 @@ jobs:
     name: Build Linux
     runs-on: linux/amd64
     needs: test
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
-      - name: Setup Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      - name: Install system dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y \
-            libwebkit2gtk-4.1-dev \
-            build-essential \
-            curl \
-            wget \
-            file \
-            libssl-dev \
-            libgtk-3-dev \
-            libayatana-appindicator3-dev \
-            librsvg2-dev
-
       - name: Cache Rust dependencies
         uses: actions/cache@v3
         with:
           path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/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
@@ -135,74 +125,79 @@ jobs:
     name: Build Android
     runs-on: linux/amd64
     needs: test
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+    env:
+      ANDROID_HOME: /opt/android-sdk
+      ANDROID_SDK_ROOT: /opt/android-sdk
+      ANDROID_NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
-      - name: Setup Java
-        uses: actions/setup-java@v3
-        with:
-          distribution: 'temurin'
-          java-version: '17'
-
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v2
-        with:
-          api-level: 33
-
-      - name: Setup Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      - name: Add Android targets
-        run: |
-          rustup target add aarch64-linux-android
-          rustup target add armv7-linux-androideabi
-          rustup target add x86_64-linux-android
-
-      - name: Install Android NDK
-        run: |
-          sdkmanager "ndk;25.1.8937393"
-
       - name: Cache Rust dependencies
         uses: actions/cache@v3
         with:
           path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/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: |
+          REF="${GITHUB_REF#refs/tags/v}"
+          VERSION="${REF#refs/heads/}"
+          # On non-tag runs keep whatever is in tauri.conf.json
+          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
+            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: 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
@@ -217,6 +212,8 @@ jobs:
     runs-on: linux/amd64
     needs: [build-linux, build-android]
     if: startsWith(github.ref, 'refs/tags/v')
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -243,23 +240,23 @@ jobs:
         id: release_notes
         run: |
           VERSION="${{ steps.tag_name.outputs.VERSION }}"
-          echo "## 📱 JellyTau $VERSION Release" > release_notes.md
+          echo "## JellyTau $VERSION Release" > release_notes.md
           echo "" >> release_notes.md
-          echo "### 📦 Downloads" >> release_notes.md
+          echo "### Downloads" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Linux" >> release_notes.md
           echo "- **AppImage** - Run directly on most Linux distributions" >> release_notes.md
-          echo "- **DEB** - Install via `sudo dpkg -i jellytau_*.deb` (Ubuntu/Debian)" >> release_notes.md
+          echo "- **DEB** - Install via \`sudo dpkg -i jellytau_*.deb\` (Ubuntu/Debian)" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Android" >> release_notes.md
-          echo "- **APK** - Install via `adb install jellytau-release.apk` or sideload via file manager" >> release_notes.md
+          echo "- **APK** - Install via \`adb install jellytau-release.apk\` or sideload via file manager" >> release_notes.md
           echo "- **AAB** - Upload to Google Play Console or testing platforms" >> release_notes.md
           echo "" >> release_notes.md
-          echo "### ✨ What's New" >> release_notes.md
+          echo "### What's New" >> release_notes.md
           echo "" >> release_notes.md
           echo "See [CHANGELOG.md](CHANGELOG.md) for detailed changes." >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 🔧 Installation" >> release_notes.md
+          echo "### Installation" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Linux (AppImage)" >> release_notes.md
           echo "\`\`\`bash" >> release_notes.md
@@ -277,11 +274,11 @@ jobs:
           echo "- Sideload: Download APK and install via file manager or ADB" >> release_notes.md
           echo "- Play Store: Coming soon" >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 🐛 Known Issues" >> release_notes.md
+          echo "### Known Issues" >> release_notes.md
           echo "" >> release_notes.md
           echo "See [GitHub Issues](../../issues) for reported bugs." >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 📝 Requirements" >> release_notes.md
+          echo "### Requirements" >> release_notes.md
           echo "" >> release_notes.md
           echo "**Linux:**" >> release_notes.md
           echo "- 64-bit Linux system" >> release_notes.md
@@ -292,46 +289,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/traceability-check.yml

@@ -16,6 +16,8 @@ jobs:
   validate-traces:
     runs-on: linux/amd64
     name: Check Requirement Traces
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 
     steps:
       - name: Checkout repository
@@ -93,20 +95,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 ""

.gitea/workflows/traceability.yml

@@ -16,6 +16,8 @@ jobs:
   traceability:
     name: Validate Requirement Traces
     runs-on: linux/amd64
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
 
     steps:
       - name: Checkout code

.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,9 @@ 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

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,6 +21,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
     ca-certificates \
     unzip \
+    jq \
     openjdk-17-jdk-headless \
     pkg-config \
     libssl-dev \
@@ -67,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
 

README.md

@@ -1,336 +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 | Done |
-| UR-007 | Navigate media in library | High | Done |
-| UR-008 | Search media across libraries | High | Done |
-| UR-009 | Connect to Jellyfin to access media | High | Done |
-| UR-010 | Control playback of Jellyfin remote sessions | Low | Done |
-| UR-011 | Download media on demand | Medium | Done |
-| UR-012 | Login info shall be stored securely and persistently | High | Done |
-| UR-013 | View and manage downloaded media | Medium | Done |
-| UR-014 | Make and edit playlists of music that sync back to Jellyfin | Medium | Done |
-| UR-015 | View and manage current audio queue (add, reorder tracks) | Medium | Done |
-| UR-016 | Change system settings while playing (brightness, volume) | Low | Planned |
-| UR-017 | Like or unlike audio, albums, movies, etc. | Medium | Done |
-| UR-018 | Choose to download series, albums, songs, artist discography | Medium | Done |
-| UR-019 | Resume playback from where you left off (movies, shows, albums) | High | Done |
-| UR-020 | Select subtitles for video content | High | Done |
-| UR-021 | Select audio track for video content | High | Done |
-| UR-022 | Control streaming quality and transcoding settings | Medium | Planned |
-| UR-023 | View "Next Up" / Continue Watching on home screen; auto-play next episode with countdown popup and configurable episode limit | Medium | Done |
-| UR-024 | View recently added content on server | Medium | Done |
-| UR-025 | Sync watch history and progress back to Jellyfin | High | Done |
-| UR-026 | Sleep timer for audio and video playback (roller UI, time/track/episode modes) | Low | Done |
-| UR-027 | Audio equalizer for sound customization | Low | Planned |
-| UR-028 | Navigate to artist/album by tapping names in now playing view | High | Done |
-| UR-029 | Toggle between grid and list view in library | Medium | Done |
-| UR-030 | Quick genre browsing and filtering | Medium | Done |
-| UR-031 | Crossfade between audio tracks | Low | Done (Linux only) |
-| UR-032 | Gapless playback for seamless album listening | Medium | Done (Linux only) |
-| UR-033 | Volume normalization to prevent volume jumps between tracks | Low | Done (Linux only) |
-| UR-034 | Rich home screen with hero banners, carousels, and personalized sections | High | Done |
-| UR-035 | View cast/crew (actors, directors) on movie/show detail pages | High | Done |
-| UR-036 | Navigate to actor/person page showing their filmography | Medium | Done |
-| UR-037 | Visually appealing video library with poster grids and metadata | High | Done |
-| UR-038 | Movie/show detail page with backdrop, ratings, and rich metadata | High | Done |
-| UR-039 | Navigate between main sections via bottom navigation bar | High | Done |
-
----
-
-## 2. Software Requirements
-
-### 2.1 Integration Requirements
-
-External system integrations and platform-specific implementations.
-
-| ID | Requirement | Category | Traces To | Status |
-|----|-------------|----------|-----------|--------|
-| IR-001 | Build system supporting multiple targets (Linux, Android) | Build | UR-001 | Done |
-| IR-002 | Build scripts for Android and Linux | Build | UR-001 | Done |
-| IR-003 | Integration of libmpv for Linux playback | Playback | UR-003, UR-004 | Done |
-| IR-004 | Integration of ExoPlayer for Android playback | Playback | UR-003, UR-004 | In Progress (basic playback works, audio settings missing) |
-| IR-005 | MPRIS D-Bus integration for Linux lockscreen/media controls | Platform | UR-006 | Planned |
-| IR-006 | Android MediaSession integration for lockscreen controls | Platform | UR-006 | Done |
-| IR-007 | Bluetooth AVRCP integration via system media session | Platform | UR-006 | Planned |
-| IR-008 | Android audio focus handling (pause on call) | Platform | UR-004, UR-006 | Done |
-| IR-009 | Jellyfin API client for authentication | API | UR-009, UR-012 | Done |
-| IR-010 | Jellyfin API client for library browsing | API | UR-007, UR-008 | Done |
-| IR-011 | Jellyfin API client for playback streaming | API | UR-003, UR-004 | Done |
-| IR-012 | Jellyfin Sessions API for remote playback control | API | UR-010 | Done |
-| IR-021 | Android MediaRouter integration for remote volume in system panel | Platform | UR-010, UR-016 | Planned |
-| IR-013 | SQLite integration for local database | Storage | UR-002, UR-011 | Done |
-| IR-014 | Secure credential storage (keyring/keychain) | Security | UR-012 | Done |
-| IR-015 | Jellyfin API client for playback progress reporting | API | UR-019, UR-025 | Done |
-| IR-016 | Jellyfin API client for subtitle/audio track info | API | UR-020, UR-021 | Done |
-| IR-017 | Jellyfin API client for transcoding parameters | API | UR-022 | Planned |
-| IR-018 | libmpv subtitle rendering and selection | Playback | UR-020 | Planned |
-| IR-019 | libmpv audio track selection | Playback | UR-021 | Planned |
-| IR-020 | libmpv/ExoPlayer equalizer integration | Playback | UR-027 | Planned |
-| IR-022 | Jellyfin API client for person/cast data | API | UR-035, UR-036 | Done |
-| IR-023 | Database schema for person/cast caching | Storage | UR-035, UR-036 | Done |
-| IR-024 | Jellyfin API client for home screen data (featured, continue watching) | API | UR-034 | Done |
-
-### 2.2 Jellyfin API Requirements
-
-API endpoints and data contracts required for Jellyfin integration.
-
-| ID | Requirement | Endpoint Category | Traces To | Status |
-|----|-------------|-------------------|-----------|--------|
-| JA-001 | Server connection and discovery | System | UR-009 | Done |
-| JA-002 | User authentication (username/password) | Users | UR-009, UR-012 | Done |
-| JA-003 | Get user library views | UserViews | UR-007 | Done |
-| JA-004 | Get library items (paginated) | Items | UR-007 | Done |
-| JA-005 | Get item details and metadata | Items | UR-007 | Done |
-| JA-006 | Search across libraries | Items | UR-008 | Done |
-| JA-007 | Get playback info and stream URL | MediaInfo | UR-003, UR-004 | Done |
-| JA-008 | Get available subtitles for item | MediaInfo | UR-020 | Done |
-| JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Done |
-| JA-010 | Report playback start | Sessions | UR-025 | Done |
-| JA-011 | Report playback progress (periodic) | Sessions | UR-025 | Done |
-| JA-012 | Report playback stopped | Sessions | UR-025 | Done |
-| JA-013 | Get resume position for item | UserData | UR-019 | Done |
-| JA-014 | Get "Next Up" items | Shows | UR-023 | Done |
-| JA-015 | Get "Continue Watching" items | Items | UR-023 | Done |
-| JA-016 | Get recently added items | Items | UR-024 | Done |
-| JA-017 | Mark item as favorite | UserData | UR-017 | Done |
-| JA-018 | Remove item from favorites | UserData | UR-017 | Done |
-| JA-019 | Get/create/update playlists | Playlists | UR-014 | Done |
-| JA-020 | Add/remove items from playlist | Playlists | UR-014 | Done |
-| JA-021 | Get active sessions list | Sessions | UR-010 | Done |
-| JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Done |
-| JA-023 | Send seek command to remote session | Sessions | UR-010 | Done |
-| JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Done |
-| JA-025 | Play specific item on remote session | Sessions | UR-010 | Done |
-| JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Done |
-| JA-027 | Get transcoding options | MediaInfo | UR-022 | Planned |
-| JA-028 | Get image/artwork URLs | Images | UR-007 | Done |
-| JA-029 | Get cast/crew for item (actors, directors) | Items | UR-035 | Done |
-| JA-030 | Get person details and filmography | Persons | UR-036 | Done |
-| JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
-
-### 2.3 Development Requirements
-
-Internal architecture, components, and application logic.
-
-| ID | Requirement | Category | Traces To | Status |
-|----|-------------|----------|-----------|--------|
-| DR-001 | Player state machine (idle, loading, playing, paused, seeking, error) | Player | UR-005 | Done |
-| DR-002 | MediaItem struct tracking source, location, duration, metadata | Player | UR-003, UR-004 | Done |
-| DR-003 | Source-agnostic media abstraction (Remote, Local, DirectUrl) | Player | UR-002, UR-011 | Done |
-| DR-004 | PlayerBackend trait for platform-agnostic playback | Player | UR-003, UR-004 | Done |
-| DR-005 | Queue manager with shuffle, repeat, history | Player | UR-005, UR-015 | Done |
-| DR-006 | Audio pre-caching for seamless track transitions | Player | UR-004 | Planned |
-| DR-007 | Library browsing screens (grid view, search, filters) | UI | UR-007, UR-008 | Done |
-| DR-008 | Album/Series detail view with track listing | UI | UR-007 | Done |
-| DR-009 | Audio player UI (mini player, full screen) | UI | UR-005 | Done |
-| DR-010 | Video player UI (fullscreen, controls overlay) | UI | UR-003, UR-005 | Done |
-| DR-011 | Search bar with cross-library search | UI | UR-008 | Done |
-| DR-012 | Local database for media metadata cache | Storage | UR-002 | Done |
-| DR-013 | Repository pattern for online/offline data access | Storage | UR-002 | Done |
-| DR-014 | Offline mutation queue for sync-back operations | Storage | UR-002, UR-014, UR-017 | Done |
-| DR-015 | Download manager with queue and progress tracking | Storage | UR-011, UR-018 | Done |
-| DR-016 | Thumbnail caching and sync with server | Storage | UR-007 | Done |
-| DR-017 | "Manage Downloads" screen for local media management | UI | UR-013 | Done |
-| DR-018 | Download buttons on library/album/player screens | UI | UR-011, UR-018 | Done |
-| DR-019 | Playlist creation and editing UI | UI | UR-014 | Done |
-| DR-020 | Queue management UI (add, remove, reorder) | UI | UR-015 | Done |
-| DR-021 | Like/favorite functionality on media items | UI | UR-017 | Done |
-| DR-022 | Resume position tracking and restoration on play | Player | UR-019 | Done |
-| DR-023 | Subtitle selection UI in video player | UI | UR-020 | Done |
-| DR-024 | Audio track selection UI in video player | UI | UR-021 | Done |
-| DR-025 | Quality/transcoding settings UI | UI | UR-022 | Planned |
-| DR-026 | "Continue Watching" / "Next Up" home section | UI | UR-023 | Done |
-| DR-027 | "Recently Added" home section | UI | UR-024 | Done |
-| DR-028 | Playback progress sync service (periodic reporting) | Player | UR-025 | Done |
-| DR-029 | Sleep timer with roller UI, time/track/episode modes, and auto-stop (audio + video players) | Player | UR-026 | Done |
-| DR-049 | Auto-play episode limit (configurable max episodes per session) | Player | UR-023 | Done |
-| DR-050 | Reusable scroll picker (roller) component | UI | UR-026 | Done |
-| DR-030 | Equalizer UI with presets and custom bands | UI | UR-027 | Planned |
-| DR-031 | Clickable artist/album links in now playing view | UI | UR-028 | Done |
-| DR-032 | List view option for library browsing (albums, artists) | UI | UR-029 | Done |
-| DR-033 | Genre browsing screen with quick filters | UI | UR-030 | Done |
-| DR-034 | Crossfade engine with configurable duration (0-12s) | Player | UR-031 | Done (Linux only) |
-| DR-035 | Gapless playback between sequential tracks | Player | UR-032 | Done (Linux only) |
-| DR-036 | Volume normalization with preset levels (Loud/Normal/Quiet) | Player | UR-033 | Done (Linux only) |
-| DR-037 | Remote session browser and control UI | UI | UR-010 | Done |
-| DR-038 | Home screen with hero banner carousel (featured/continue watching) | UI | UR-034 | Done |
-| DR-039 | Home screen horizontal carousels (recently added, recommendations) | UI | UR-034, UR-024 | Done |
-| DR-040 | Cast/crew section on movie/show detail pages | UI | UR-035 | Done |
-| DR-041 | Person/actor detail page with filmography grid | UI | UR-036 | Done |
-| DR-042 | Video library grid with poster cards, year, and rating badges | UI | UR-037 | Done |
-| DR-043 | Movie/show detail page with backdrop hero, synopsis, and metadata | UI | UR-038 | Done |
-| DR-044 | Horizontal scrolling actor/cast row with profile images | UI | UR-035 | Done |
-| DR-045 | Bottom navigation bar with Home, Library, Search buttons | UI | UR-039 | Done |
-| DR-046 | Dedicated search page with input and results | UI | UR-039 | Done |
-| DR-047 | Next episode auto-play popup with configurable countdown and episode limit | Player | UR-023 | Done |
-| DR-048 | Video settings (auto-play toggle, countdown duration, episode limit) | Settings | UR-023, UR-026 | Done |
-
----
-
-## 3. Traceability Matrix
-
-### User Requirements to Software Requirements
-
-| User Req | Integration Requirements | Development Requirements |
-|----------|-------------------------|-------------------------|
-| UR-001 | IR-001, IR-002 | - |
-| UR-002 | IR-013 | DR-003, DR-012, DR-013, DR-014 |
-| UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010 |
-| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006 |
-| UR-005 | - | DR-001, DR-005, DR-009 |
-| UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
-| UR-007 | IR-010 | DR-007, DR-008, DR-016 |
-| UR-008 | IR-010 | DR-007, DR-011 |
-| UR-009 | IR-009, IR-010, IR-011 | - |
-| UR-010 | IR-012, IR-021 | DR-037 |
-| UR-011 | IR-013 | DR-003, DR-015, DR-018 |
-| UR-012 | IR-009, IR-014 | - |
-| UR-013 | IR-013 | DR-017 |
-| UR-014 | IR-010 | DR-014, DR-019 |
-| UR-015 | - | DR-005, DR-020 |
-| UR-016 | - | - |
-| UR-017 | - | DR-014, DR-021 |
-| UR-018 | IR-013 | DR-015, DR-018 |
-| UR-019 | IR-015 | DR-022 |
-| UR-020 | IR-016, IR-018 | DR-023 |
-| UR-021 | IR-016, IR-019 | DR-024 |
-| UR-022 | IR-017 | DR-025 |
-| UR-023 | IR-010 | DR-026, DR-047, DR-048, DR-049 |
-| UR-024 | IR-010 | DR-027 |
-| UR-025 | IR-015 | DR-028 |
-| UR-026 | - | DR-029, DR-048, DR-050 |
-| UR-027 | IR-020 | DR-030 |
-| UR-028 | - | DR-031 |
-| UR-029 | - | DR-032 |
-| UR-030 | IR-010 | DR-033 |
-| UR-031 | - | DR-034 |
-| UR-032 | - | DR-035 |
-| UR-033 | - | DR-036 |
-| UR-034 | IR-010, IR-024 | DR-038, DR-039 |
-| UR-035 | IR-022, IR-023 | DR-040, DR-044 |
-| UR-036 | IR-022, IR-023 | DR-041 |
-| UR-037 | IR-010 | DR-042 |
-| UR-038 | IR-010 | DR-043 |
-| UR-039 | - | DR-045, DR-046 |
-
----
-
-## 4. Test Traceability
-
-### Unit Tests to Software Requirements
-
-| Test ID | Test Description | Traces To | Status |
-|---------|-----------------|-----------|--------|
-| UT-001 | Player state transitions | DR-001 | Pending |
-| UT-002 | MediaItem source URL resolution | DR-002, DR-003 | Pending |
-| UT-003 | Queue next/previous navigation | DR-005 | Pending |
-| UT-004 | Queue shuffle order generation | DR-005 | Pending |
-| UT-005 | Queue repeat mode behavior | DR-005 | Pending |
-| UT-006 | Jellyfin authentication flow | IR-009 | Pending |
-| UT-007 | Jellyfin library items parsing | IR-010 | Pending |
-| UT-008 | Repository pattern online/offline switching | DR-013 | Pending |
-| UT-009 | Offline mutation queue persistence | DR-014 | Pending |
-| UT-010 | Download queue management | DR-015 | Done |
-| UT-011 | Resume position storage and retrieval | DR-022 | Pending |
-| UT-012 | Sleep timer countdown logic | DR-029 | Pending |
-| UT-013 | Playback progress reporting throttling | DR-028 | Pending |
-| UT-014 | Database open and in-memory mode | IR-013, DR-012 | Done |
-| UT-015 | Database migrations run successfully | IR-013, DR-012 | Done |
-| UT-016 | All database tables created | IR-013, DR-012 | Done |
-| UT-017 | FTS5 search table created | IR-013, DR-012 | Done |
-| UT-018 | Server CRUD operations | IR-013, DR-012 | Done |
-| UT-019 | User CRUD operations | IR-013, DR-012 | Done |
-| UT-020 | Cascade delete server removes users | IR-013, DR-012 | Done |
-| UT-021 | Item insert and FTS search | IR-013, DR-012 | Done |
-| UT-022 | User data playback position storage | IR-013, DR-012, DR-022 | Done |
-| UT-023 | Sync queue operations | IR-013, DR-014 | Done |
-| UT-024 | Downloads table operations | IR-013, DR-015 | Done |
-| UT-025 | Migrations are idempotent | IR-013, DR-012 | Done |
-| UT-026 | NullBackend volume default value | DR-004 | Done |
-| UT-027 | NullBackend set volume | DR-004 | Done |
-| UT-028 | NullBackend volume clamping (high/low) | DR-004 | Done |
-| UT-029 | NullBackend volume boundary values | DR-004 | Done |
-| UT-030 | PlayerController volume default | DR-004, DR-009 | Done |
-| UT-031 | PlayerController set volume | DR-004, DR-009 | Done |
-| UT-032 | PlayerController muted default | DR-004, DR-009 | Done |
-| UT-033 | PlayerController volume delegates to backend | DR-004, DR-009 | Done |
-| UT-034 | Download event serialization roundtrip | DR-015 | Done |
-| UT-035 | Download event completed serialization | DR-015 | Done |
-| UT-036 | Download event failed serialization | DR-015 | Done |
-| UT-037 | Download worker exponential backoff | DR-015 | Done |
-| UT-038 | Download worker error retryable check | DR-015 | Done |
-| UT-039 | Download manager creation | DR-015 | Done |
-| UT-040 | Download manager set max concurrent | DR-015 | Done |
-| UT-041 | Download info serialization | DR-015 | Done |
-| UT-042 | Download command filename sanitization | DR-015, DR-018 | Done |
-| UT-043 | Download command filename extension preservation | DR-015, DR-018 | Done |
-| UT-044 | Offline item serialization | DR-017 | Done |
-| UT-045 | Smart cache default config | DR-015 | Done |
-| UT-046 | Smart cache album affinity tracking | DR-015 | Done |
-| UT-047 | Smart cache queue precache config | DR-015 | Done |
-| UT-048 | Smart cache storage limit check | DR-015 | Done |
-| UT-049 | Playlist create (offline) | DR-019, JA-019 | Done |
-| UT-050 | Playlist delete (offline) | DR-019, JA-019 | Done |
-| UT-051 | Playlist rename (offline) | DR-019, JA-019 | Done |
-| UT-052 | Playlist get items (offline) | DR-019, JA-019 | Done |
-| UT-053 | Playlist add items (offline) | DR-019, JA-020 | Done |
-| UT-054 | Playlist remove items (offline) | DR-019, JA-020 | Done |
-| UT-055 | Playlist reorder items (offline) | DR-019, JA-020 | Done |
-| UT-056 | Playlist entry serialization | DR-019, JA-019 | Done |
-| UT-057 | Playlist Tauri command param naming (camelCase) | DR-019, JA-019, JA-020 | Done |
-| UT-058 | Playlist repository client methods | DR-019, JA-019, JA-020 | Done |
-
-### Integration Tests
-
-| Test ID | Test Description | Traces To | Status |
-|---------|-----------------|-----------|--------|
-| IT-001 | End-to-end authentication with Jellyfin server | IR-009, UR-009 | Pending |
-| IT-002 | Library browsing and item loading | IR-010, UR-007 | Pending |
-| IT-003 | Audio playback via libmpv | IR-003, UR-004 | Pending |
-| IT-004 | Video playback via libmpv | IR-003, UR-003 | Pending |
-| IT-005 | MPRIS lockscreen controls on Linux | IR-005, UR-006 | Pending |
-| IT-006 | Offline mode with local database | IR-013, UR-002 | Pending |
-| IT-007 | Media download and local playback | DR-015, UR-011 | Pending |
-| IT-008 | Subtitle track selection via libmpv | IR-018, UR-020 | Pending |
-| IT-009 | Audio track selection via libmpv | IR-019, UR-021 | Pending |
-| IT-010 | Playback progress sync to Jellyfin | IR-015, UR-025 | Pending |
-| IT-011 | Resume playback from server position | IR-015, UR-019 | Pending |
-| IT-012 | Equalizer bands via libmpv | IR-020, UR-027 | Pending |
-
----
-
-## 5. Development Commands
+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
@@ -340,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

docs/architecture/02-svelte-frontend.md

@@ -176,7 +176,10 @@ classDiagram
         -server_url: String
         -user_id: String
         -access_token: String
+        -connectivity: Option~Arc~ConnectivityMonitor~~
         +new()
+        +with_connectivity()
+        -report_outcome()
     }
 
     class OfflineRepository {
@@ -192,10 +195,9 @@ classDiagram
     class HybridRepository {
         -online: Arc~OnlineRepository~
         -offline: Arc~OfflineRepository~
-        -connectivity: Arc~ConnectivityMonitor~
         +new()
-        -parallel_query()
-        -has_meaningful_content()
+        -parallel_race()
+        -cache_with_timeout()
     }
 
     MediaRepository <|.. OnlineRepository
@@ -214,6 +216,7 @@ classDiagram
    - Returns cache result if it has meaningful content
    - Falls back to server result otherwise
    - Background cache updates planned
+   - **Connectivity feedback**: `OnlineRepository` reports the outcome of every server request to the `ConnectivityMonitor` (classified via `RepoError`). This is the source of truth for the offline/online banner — see [07-connectivity.md](07-connectivity.md). The frontend `connectivity` store is a pure reflection of the resulting events; `navigator.onLine` is only an advisory hint that triggers an immediate recheck.
 
 2. **Handle-Based Resource Management** (`repository.rs` commands):
    ```rust

docs/architecture/03-data-flow.md

@@ -10,6 +10,7 @@ sequenceDiagram
     participant Hybrid as HybridRepository
     participant Cache as OfflineRepository (SQLite)
     participant Server as OnlineRepository (HTTP)
+    participant Conn as ConnectivityMonitor
 
     UI->>Client: getItems(parentId)
     Client->>Rust: invoke("repository_get_items", {handle, parentId})
@@ -20,6 +21,13 @@ sequenceDiagram
         Hybrid->>Server: get_items() (no timeout)
     end
 
+    Note over Server,Conn: Every server request reports its outcome
+    alt Server succeeds (or answers with 4xx/5xx)
+        Server->>Conn: mark_reachable() (server is up)
+    else Network failure / timeout
+        Server->>Conn: mark_unreachable() (debounced)
+    end
+
     alt Cache returns with content
         Cache-->>Hybrid: Result with items
         Hybrid-->>Rust: Return cache result
@@ -39,6 +47,7 @@ sequenceDiagram
 - Cache wins if it has meaningful content
 - Automatic fallback to server if cache is empty/stale
 - Background cache updates (planned)
+- **Connectivity side-effect**: each server request feeds the `ConnectivityMonitor`, which is the source of truth for the offline/online banner (see [07-connectivity.md](07-connectivity.md)). A server-answered error (401/404/5xx) still counts as *reachable* — only network failures, sustained past a debounce window, flip the app to offline.
 
 ## Playback Initiation Flow
 

docs/architecture/05-platform-backends.md

@@ -90,6 +90,50 @@ flowchart LR
 
 **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/`

docs/architecture/07-connectivity.md

@@ -13,12 +13,13 @@ pub struct HttpClient {
 }
 
 pub struct HttpConfig {
-    pub base_url: String,
-    pub timeout: Duration,        // Default: 10s
+    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
@@ -38,39 +39,71 @@ pub enum ErrorKind {
 
 **Location**: `src-tauri/src/connectivity/mod.rs`
 
-The connectivity monitor tracks server reachability with adaptive polling:
+The connectivity monitor is the **single source of truth** for server reachability. Its primary signal is the outcome of *real repository traffic* — every server request the user actually makes. A standalone `/System/Info/Public` probe is kept only as an offline recovery detector.
+
+### Source of truth: repository traffic
+
+`OnlineRepository` reports the result of each server request to the monitor, classified via `RepoError`:
+
+| Repository outcome | Meaning | Effect on reachability |
+|--------------------|---------|------------------------|
+| `Ok(_)` | Server answered successfully | Mark **reachable** (instant recovery) |
+| `Err(Authentication)` | Server answered with 401/403 | Mark **reachable** (server is up; request was rejected) |
+| `Err(NotFound)` | Server answered with 404 | Mark **reachable** (server is up) |
+| `Err(Server)` | Server answered with 5xx / bad body | Mark **reachable** (server is up) |
+| `Err(Network)` | Connection failure / timeout / DNS | **Candidate for offline** (see debounce) |
+| `Err(Database)` | Local cache error only | No effect (not a server signal) |
+
+This classification fixes the previous bug where a successful `/System/Info/Public` ping reported "online" even while the user's authenticated data calls were failing — and vice versa.
+
+### Time-window debounce (offline) + instant recovery (online)
+
+To stop the banner from flapping on a single dropped request, the transition to **offline** is debounced over a time window:
+
+- On the **first** `Network` failure, the monitor records `first_failure_at`.
+- It flips `is_server_reachable = false` only once `Network` failures have persisted continuously for `OFFLINE_CONFIRM_WINDOW` (5s) with no intervening success.
+- **Any** success (or server-answered error) clears `first_failure_at` and immediately marks reachable.
+
+Recovery is therefore instant and asymmetric: one good response brings the app back online, but a brief blip never trips the banner.
+
+### Offline-only recovery probe
 
 ```mermaid
 flowchart TB
-    Monitor["ConnectivityMonitor"] --> Poller["Background Task"]
-    Poller --> Check{"Server<br/>Reachable?"}
-    Check -->|"Yes"| Online["30s Interval"]
-    Check -->|"No"| Offline["5s Interval"]
-    Online --> Emit["Emit Events"]
-    Offline --> Emit
-    Emit --> Frontend["Frontend Store"]
+    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:**
-- **Adaptive Polling**: 30s when online, 5s when offline (for quick reconnection detection)
-- **Event Emission**: Emits `connectivity:changed` and `connectivity:reconnected` events
-- **Manual Marking**: Can mark reachable/unreachable based on API call results
-- **Thread-Safe**: Uses Arc<RwLock<>> for shared state
+- **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 |
+| `connectivity_check_server` | Manual reachability check (also used by the frontend's advisory `navigator.onLine` hint) |
 | `connectivity_set_server_url` | Update monitored server URL |
 | `connectivity_get_status` | Get current connectivity status |
-| `connectivity_start_monitoring` | Start background monitoring |
-| `connectivity_stop_monitoring` | Stop monitoring |
-| `connectivity_mark_reachable` | Mark server as reachable (after successful API call) |
-| `connectivity_mark_unreachable` | Mark server as unreachable (after failed API call) |
+| `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
-// TypeScript store listens to Rust events
+// The store is a pure reflection of backend events — it no longer decides
+// reachability itself. navigator.onLine is advisory: it triggers an immediate
+// recheck rather than forcing the offline state.
 listen<{ isReachable: boolean }>("connectivity:changed", (event) => {
   updateConnectivityState(event.payload.isReachable);
 });
@@ -81,12 +114,14 @@ listen<{ isReachable: boolean }>("connectivity:changed", (event) => {
 The connectivity system provides resilience through multiple layers:
 
 1. **HTTP Client Layer**: Automatic retry with exponential backoff
-2. **Connectivity Monitoring**: Background reachability checks
-3. **Frontend Integration**: Offline mode detection and UI updates
+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:**
-- **Fail Fast**: Don't retry 4xx errors (client errors, authentication)
-- **Fail Slow**: Retry network and 5xx errors with increasing delays
-- **Adaptive Polling**: Reduce polling frequency when online, increase when offline
-- **Event-Driven**: Frontend reacts to connectivity changes via events
+- **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/README.md

@@ -13,8 +13,10 @@ JellyTau uses a client-server architecture: business logic lives in a comprehens
 - **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.
 
@@ -79,26 +81,29 @@ flowchart TB
         Core --> Storage
         Repository --> HttpClient
         Repository --> DatabaseService
+        Repository -->|"reports server outcome<br/>(success / RepoError)"| ConnectivityMonitor
     end
 ```
 
+> The `Repository --> ConnectivityMonitor` edge is the source of truth for the offline/online banner: every server request the user actually makes updates reachability. The monitor's own polling is now an offline-only recovery probe (see [07-connectivity.md](07-connectivity.md)).
+
 ---
 
 ## Detailed Documentation
 
-Each major subsystem is documented in its own file under [docs/architecture/](docs/architecture/):
+Each major subsystem is documented in its own file in this directory:
 
 | Document | Contents |
 |----------|----------|
-| [01 - Rust Backend](docs/architecture/01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
-| [02 - Svelte Frontend](docs/architecture/02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
-| [03 - Data Flow](docs/architecture/03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
-| [04 - Type Sync & Threading](docs/architecture/04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
-| [05 - Platform Backends](docs/architecture/05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
-| [06 - Downloads & Offline](docs/architecture/06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
-| [07 - Connectivity](docs/architecture/07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
-| [08 - Database Design](docs/architecture/08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
-| [09 - Security](docs/architecture/09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
+| [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 |
 
 ---
 
@@ -162,6 +167,9 @@ src/lib/
 │   ├── 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)
@@ -187,7 +195,7 @@ src/lib/
 
 **What moved to Rust (~3,500 lines of business logic):**
 1. **HTTP Client** (338 lines) - Retry logic with exponential backoff
-2. **Connectivity Monitor** (301 lines) - Adaptive polling, event emission
+2. **Connectivity Monitor** (301 lines) - Reachability derived from real repository traffic, time-window debounce, offline-only recovery probe, event emission
 3. **Repository Pattern** (1061 lines) - Cache-first hybrid with parallel racing
 4. **Database Service** - Async wrapper preventing UI freezing
 5. **Playback Mode** (303 lines) - Local/remote transfer coordination

docs/requirements.md

@@ -0,0 +1,454 @@
+# Requirements Specification
+
+This document captures JellyTau's user requirements, software requirements,
+traceability matrix, test traceability, and known technical debt.
+
+For a narrative overview of the system design, see
+[docs/architecture/](architecture/). For development workflows, see the
+[README](../README.md) and [scripts/README.md](../scripts/README.md).
+
+## 1. User Requirements
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| UR-001 | Run the app on multiple platforms (Linux, Android) | High | In Progress |
+| UR-002 | Access media when online or offline | High | Done |
+| UR-003 | Play videos | High | Done |
+| UR-004 | Play audio uninterrupted | High | Done |
+| UR-005 | Control media playback (pause, play, skip, scrub) | High | Done |
+| UR-006 | Control media when device is on lock screen or via BLE headsets | Medium | Done |
+| UR-007 | Navigate media in library | High | Done |
+| UR-008 | Search media across libraries | High | Done |
+| UR-009 | Connect to Jellyfin to access media | High | Done |
+| UR-010 | Control playback of Jellyfin remote sessions | Low | Done |
+| UR-011 | Download media on demand | Medium | Done |
+| UR-012 | Login info shall be stored securely and persistently | High | Done |
+| UR-013 | View and manage downloaded media | Medium | Done |
+| UR-014 | Make and edit playlists of music that sync back to Jellyfin | Medium | Done |
+| UR-015 | View and manage current audio queue (add, reorder tracks) | Medium | Done |
+| UR-016 | Change system settings while playing (brightness, volume) | Low | Planned |
+| UR-017 | Like or unlike audio, albums, movies, etc. | Medium | Done |
+| UR-018 | Choose to download series, albums, songs, artist discography | Medium | Done |
+| UR-019 | Resume playback from where you left off (movies, shows, albums) | High | Done |
+| UR-020 | Select subtitles for video content | High | Done |
+| UR-021 | Select audio track for video content | High | Done |
+| UR-022 | Control streaming quality and transcoding settings | Medium | Planned |
+| UR-023 | View "Next Up" / Continue Watching on home screen; auto-play next episode with countdown popup and configurable episode limit | Medium | Done |
+| UR-024 | View recently added content on server | Medium | Done |
+| UR-025 | Sync watch history and progress back to Jellyfin | High | Done |
+| UR-026 | Sleep timer for audio and video playback (roller UI, time/track/episode modes) | Low | Done |
+| UR-027 | Audio equalizer for sound customization | Low | Planned |
+| UR-028 | Navigate to artist/album by tapping names in now playing view | High | Done |
+| UR-029 | Toggle between grid and list view in library | Medium | Done |
+| UR-030 | Quick genre browsing and filtering | Medium | Done |
+| UR-031 | Crossfade between audio tracks | Low | Done (Linux only) |
+| UR-032 | Gapless playback for seamless album listening | Medium | Done (Linux only) |
+| UR-033 | Volume normalization to prevent volume jumps between tracks | Low | Done (Linux only) |
+| UR-034 | Rich home screen with hero banners, carousels, and personalized sections | High | Done |
+| UR-035 | View cast/crew (actors, directors) on movie/show detail pages | High | Done |
+| UR-036 | Navigate to actor/person page showing their filmography | Medium | Done |
+| UR-037 | Visually appealing video library with poster grids and metadata | High | Done |
+| UR-038 | Movie/show detail page with backdrop, ratings, and rich metadata | High | Done |
+| UR-039 | Navigate between main sections via bottom navigation bar | High | Done |
+
+---
+
+## 2. Software Requirements
+
+### 2.1 Integration Requirements
+
+External system integrations and platform-specific implementations.
+
+| ID | Requirement | Category | Traces To | Status |
+|----|-------------|----------|-----------|--------|
+| IR-001 | Build system supporting multiple targets (Linux, Android) | Build | UR-001 | Done |
+| IR-002 | Build scripts for Android and Linux | Build | UR-001 | Done |
+| IR-003 | Integration of libmpv for Linux playback | Playback | UR-003, UR-004 | Done |
+| IR-004 | Integration of ExoPlayer for Android playback | Playback | UR-003, UR-004 | In Progress (basic playback works, audio settings missing) |
+| IR-005 | MPRIS D-Bus integration for Linux lockscreen/media controls | Platform | UR-006 | Planned |
+| IR-006 | Android MediaSession integration for lockscreen controls | Platform | UR-006 | Done |
+| IR-007 | Bluetooth AVRCP integration via system media session | Platform | UR-006 | Planned |
+| IR-008 | Android audio focus handling (pause on call) | Platform | UR-004, UR-006 | Done |
+| IR-009 | Jellyfin API client for authentication | API | UR-009, UR-012 | Done |
+| IR-010 | Jellyfin API client for library browsing | API | UR-007, UR-008 | Done |
+| IR-011 | Jellyfin API client for playback streaming | API | UR-003, UR-004 | Done |
+| IR-012 | Jellyfin Sessions API for remote playback control | API | UR-010 | Done |
+| IR-021 | Android MediaRouter integration for remote volume in system panel | Platform | UR-010, UR-016 | Planned |
+| IR-013 | SQLite integration for local database | Storage | UR-002, UR-011 | Done |
+| IR-014 | Secure credential storage (keyring/keychain) | Security | UR-012 | Done |
+| IR-015 | Jellyfin API client for playback progress reporting | API | UR-019, UR-025 | Done |
+| IR-016 | Jellyfin API client for subtitle/audio track info | API | UR-020, UR-021 | Done |
+| IR-017 | Jellyfin API client for transcoding parameters | API | UR-022 | Planned |
+| IR-018 | libmpv subtitle rendering and selection | Playback | UR-020 | Planned |
+| IR-019 | libmpv audio track selection | Playback | UR-021 | Planned |
+| IR-020 | libmpv/ExoPlayer equalizer integration | Playback | UR-027 | Planned |
+| IR-022 | Jellyfin API client for person/cast data | API | UR-035, UR-036 | Done |
+| IR-023 | Database schema for person/cast caching | Storage | UR-035, UR-036 | Done |
+| IR-024 | Jellyfin API client for home screen data (featured, continue watching) | API | UR-034 | Done |
+
+### 2.2 Jellyfin API Requirements
+
+API endpoints and data contracts required for Jellyfin integration.
+
+| ID | Requirement | Endpoint Category | Traces To | Status |
+|----|-------------|-------------------|-----------|--------|
+| JA-001 | Server connection and discovery | System | UR-009 | Done |
+| JA-002 | User authentication (username/password) | Users | UR-009, UR-012 | Done |
+| JA-003 | Get user library views | UserViews | UR-007 | Done |
+| JA-004 | Get library items (paginated) | Items | UR-007 | Done |
+| JA-005 | Get item details and metadata | Items | UR-007 | Done |
+| JA-006 | Search across libraries | Items | UR-008 | Done |
+| JA-007 | Get playback info and stream URL | MediaInfo | UR-003, UR-004 | Done |
+| JA-008 | Get available subtitles for item | MediaInfo | UR-020 | Done |
+| JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Done |
+| JA-010 | Report playback start | Sessions | UR-025 | Done |
+| JA-011 | Report playback progress (periodic) | Sessions | UR-025 | Done |
+| JA-012 | Report playback stopped | Sessions | UR-025 | Done |
+| JA-013 | Get resume position for item | UserData | UR-019 | Done |
+| JA-014 | Get "Next Up" items | Shows | UR-023 | Done |
+| JA-015 | Get "Continue Watching" items | Items | UR-023 | Done |
+| JA-016 | Get recently added items | Items | UR-024 | Done |
+| JA-017 | Mark item as favorite | UserData | UR-017 | Done |
+| JA-018 | Remove item from favorites | UserData | UR-017 | Done |
+| JA-019 | Get/create/update playlists | Playlists | UR-014 | Done |
+| JA-020 | Add/remove items from playlist | Playlists | UR-014 | Done |
+| JA-021 | Get active sessions list | Sessions | UR-010 | Done |
+| JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Done |
+| JA-023 | Send seek command to remote session | Sessions | UR-010 | Done |
+| JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Done |
+| JA-025 | Play specific item on remote session | Sessions | UR-010 | Done |
+| JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Done |
+| JA-027 | Get transcoding options | MediaInfo | UR-022 | Planned |
+| JA-028 | Get image/artwork URLs | Images | UR-007 | Done |
+| JA-029 | Get cast/crew for item (actors, directors) | Items | UR-035 | Done |
+| JA-030 | Get person details and filmography | Persons | UR-036 | Done |
+| JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
+
+### 2.3 Development Requirements
+
+Internal architecture, components, and application logic.
+
+| ID | Requirement | Category | Traces To | Status |
+|----|-------------|----------|-----------|--------|
+| DR-001 | Player state machine (idle, loading, playing, paused, seeking, error) | Player | UR-005 | Done |
+| DR-002 | MediaItem struct tracking source, location, duration, metadata | Player | UR-003, UR-004 | Done |
+| DR-003 | Source-agnostic media abstraction (Remote, Local, DirectUrl) | Player | UR-002, UR-011 | Done |
+| DR-004 | PlayerBackend trait for platform-agnostic playback | Player | UR-003, UR-004 | Done |
+| DR-005 | Queue manager with shuffle, repeat, history | Player | UR-005, UR-015 | Done |
+| DR-006 | Audio pre-caching for seamless track transitions | Player | UR-004 | Planned |
+| DR-007 | Library browsing screens (grid view, search, filters) | UI | UR-007, UR-008 | Done |
+| DR-008 | Album/Series detail view with track listing | UI | UR-007 | Done |
+| DR-009 | Audio player UI (mini player, full screen) | UI | UR-005 | Done |
+| DR-010 | Video player UI (fullscreen, controls overlay) | UI | UR-003, UR-005 | Done |
+| DR-011 | Search bar with cross-library search | UI | UR-008 | Done |
+| DR-012 | Local database for media metadata cache | Storage | UR-002 | Done |
+| DR-013 | Repository pattern for online/offline data access | Storage | UR-002 | Done |
+| DR-014 | Offline mutation queue for sync-back operations | Storage | UR-002, UR-014, UR-017 | Done |
+| DR-015 | Download manager with queue and progress tracking | Storage | UR-011, UR-018 | Done |
+| DR-016 | Thumbnail caching and sync with server | Storage | UR-007 | Done |
+| DR-017 | "Manage Downloads" screen for local media management | UI | UR-013 | Done |
+| DR-018 | Download buttons on library/album/player screens | UI | UR-011, UR-018 | Done |
+| DR-019 | Playlist creation and editing UI | UI | UR-014 | Done |
+| DR-020 | Queue management UI (add, remove, reorder) | UI | UR-015 | Done |
+| DR-021 | Like/favorite functionality on media items | UI | UR-017 | Done |
+| DR-022 | Resume position tracking and restoration on play | Player | UR-019 | Done |
+| DR-023 | Subtitle selection UI in video player | UI | UR-020 | Done |
+| DR-024 | Audio track selection UI in video player | UI | UR-021 | Done |
+| DR-025 | Quality/transcoding settings UI | UI | UR-022 | Planned |
+| DR-026 | "Continue Watching" / "Next Up" home section | UI | UR-023 | Done |
+| DR-027 | "Recently Added" home section | UI | UR-024 | Done |
+| DR-028 | Playback progress sync service (periodic reporting) | Player | UR-025 | Done |
+| DR-029 | Sleep timer with roller UI, time/track/episode modes, and auto-stop (audio + video players) | Player | UR-026 | Done |
+| DR-049 | Auto-play episode limit (configurable max episodes per session) | Player | UR-023 | Done |
+| DR-050 | Reusable scroll picker (roller) component | UI | UR-026 | Done |
+| DR-030 | Equalizer UI with presets and custom bands | UI | UR-027 | Planned |
+| DR-031 | Clickable artist/album links in now playing view | UI | UR-028 | Done |
+| DR-032 | List view option for library browsing (albums, artists) | UI | UR-029 | Done |
+| DR-033 | Genre browsing screen with quick filters | UI | UR-030 | Done |
+| DR-034 | Crossfade engine with configurable duration (0-12s) | Player | UR-031 | Done (Linux only) |
+| DR-035 | Gapless playback between sequential tracks | Player | UR-032 | Done (Linux only) |
+| DR-036 | Volume normalization with preset levels (Loud/Normal/Quiet) | Player | UR-033 | Done (Linux only) |
+| DR-037 | Remote session browser and control UI | UI | UR-010 | Done |
+| DR-038 | Home screen with hero banner carousel (featured/continue watching) | UI | UR-034 | Done |
+| DR-039 | Home screen horizontal carousels (recently added, recommendations) | UI | UR-034, UR-024 | Done |
+| DR-040 | Cast/crew section on movie/show detail pages | UI | UR-035 | Done |
+| DR-041 | Person/actor detail page with filmography grid | UI | UR-036 | Done |
+| DR-042 | Video library grid with poster cards, year, and rating badges | UI | UR-037 | Done |
+| DR-043 | Movie/show detail page with backdrop hero, synopsis, and metadata | UI | UR-038 | Done |
+| DR-044 | Horizontal scrolling actor/cast row with profile images | UI | UR-035 | Done |
+| DR-045 | Bottom navigation bar with Home, Library, Search buttons | UI | UR-039 | Done |
+| DR-046 | Dedicated search page with input and results | UI | UR-039 | Done |
+| DR-047 | Next episode auto-play popup with configurable countdown and episode limit | Player | UR-023 | Done |
+| DR-048 | Video settings (auto-play toggle, countdown duration, episode limit) | Settings | UR-023, UR-026 | Done |
+
+---
+
+## 3. Traceability Matrix
+
+### User Requirements to Software Requirements
+
+| User Req | Integration Requirements | Development Requirements |
+|----------|-------------------------|-------------------------|
+| UR-001 | IR-001, IR-002 | - |
+| UR-002 | IR-013 | DR-003, DR-012, DR-013, DR-014 |
+| UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010 |
+| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006 |
+| UR-005 | - | DR-001, DR-005, DR-009 |
+| UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
+| UR-007 | IR-010 | DR-007, DR-008, DR-016 |
+| UR-008 | IR-010 | DR-007, DR-011 |
+| UR-009 | IR-009, IR-010, IR-011 | - |
+| UR-010 | IR-012, IR-021 | DR-037 |
+| UR-011 | IR-013 | DR-003, DR-015, DR-018 |
+| UR-012 | IR-009, IR-014 | - |
+| UR-013 | IR-013 | DR-017 |
+| UR-014 | IR-010 | DR-014, DR-019 |
+| UR-015 | - | DR-005, DR-020 |
+| UR-016 | - | - |
+| UR-017 | - | DR-014, DR-021 |
+| UR-018 | IR-013 | DR-015, DR-018 |
+| UR-019 | IR-015 | DR-022 |
+| UR-020 | IR-016, IR-018 | DR-023 |
+| UR-021 | IR-016, IR-019 | DR-024 |
+| UR-022 | IR-017 | DR-025 |
+| UR-023 | IR-010 | DR-026, DR-047, DR-048, DR-049 |
+| UR-024 | IR-010 | DR-027 |
+| UR-025 | IR-015 | DR-028 |
+| UR-026 | - | DR-029, DR-048, DR-050 |
+| UR-027 | IR-020 | DR-030 |
+| UR-028 | - | DR-031 |
+| UR-029 | - | DR-032 |
+| UR-030 | IR-010 | DR-033 |
+| UR-031 | - | DR-034 |
+| UR-032 | - | DR-035 |
+| UR-033 | - | DR-036 |
+| UR-034 | IR-010, IR-024 | DR-038, DR-039 |
+| UR-035 | IR-022, IR-023 | DR-040, DR-044 |
+| UR-036 | IR-022, IR-023 | DR-041 |
+| UR-037 | IR-010 | DR-042 |
+| UR-038 | IR-010 | DR-043 |
+| UR-039 | - | DR-045, DR-046 |
+
+---
+
+## 4. Test Traceability
+
+### Unit Tests to Software Requirements
+
+| Test ID | Test Description | Traces To | Status |
+|---------|-----------------|-----------|--------|
+| UT-001 | Player state transitions | DR-001 | Pending |
+| UT-002 | MediaItem source URL resolution | DR-002, DR-003 | Pending |
+| UT-003 | Queue next/previous navigation | DR-005 | Pending |
+| UT-004 | Queue shuffle order generation | DR-005 | Pending |
+| UT-005 | Queue repeat mode behavior | DR-005 | Pending |
+| UT-006 | Jellyfin authentication flow | IR-009 | Pending |
+| UT-007 | Jellyfin library items parsing | IR-010 | Pending |
+| UT-008 | Repository pattern online/offline switching | DR-013 | Pending |
+| UT-009 | Offline mutation queue persistence | DR-014 | Pending |
+| UT-010 | Download queue management | DR-015 | Done |
+| UT-011 | Resume position storage and retrieval | DR-022 | Pending |
+| UT-012 | Sleep timer countdown logic | DR-029 | Pending |
+| UT-013 | Playback progress reporting throttling | DR-028 | Pending |
+| UT-014 | Database open and in-memory mode | IR-013, DR-012 | Done |
+| UT-015 | Database migrations run successfully | IR-013, DR-012 | Done |
+| UT-016 | All database tables created | IR-013, DR-012 | Done |
+| UT-017 | FTS5 search table created | IR-013, DR-012 | Done |
+| UT-018 | Server CRUD operations | IR-013, DR-012 | Done |
+| UT-019 | User CRUD operations | IR-013, DR-012 | Done |
+| UT-020 | Cascade delete server removes users | IR-013, DR-012 | Done |
+| UT-021 | Item insert and FTS search | IR-013, DR-012 | Done |
+| UT-022 | User data playback position storage | IR-013, DR-012, DR-022 | Done |
+| UT-023 | Sync queue operations | IR-013, DR-014 | Done |
+| UT-024 | Downloads table operations | IR-013, DR-015 | Done |
+| UT-025 | Migrations are idempotent | IR-013, DR-012 | Done |
+| UT-026 | NullBackend volume default value | DR-004 | Done |
+| UT-027 | NullBackend set volume | DR-004 | Done |
+| UT-028 | NullBackend volume clamping (high/low) | DR-004 | Done |
+| UT-029 | NullBackend volume boundary values | DR-004 | Done |
+| UT-030 | PlayerController volume default | DR-004, DR-009 | Done |
+| UT-031 | PlayerController set volume | DR-004, DR-009 | Done |
+| UT-032 | PlayerController muted default | DR-004, DR-009 | Done |
+| UT-033 | PlayerController volume delegates to backend | DR-004, DR-009 | Done |
+| UT-034 | Download event serialization roundtrip | DR-015 | Done |
+| UT-035 | Download event completed serialization | DR-015 | Done |
+| UT-036 | Download event failed serialization | DR-015 | Done |
+| UT-037 | Download worker exponential backoff | DR-015 | Done |
+| UT-038 | Download worker error retryable check | DR-015 | Done |
+| UT-039 | Download manager creation | DR-015 | Done |
+| UT-040 | Download manager set max concurrent | DR-015 | Done |
+| UT-041 | Download info serialization | DR-015 | Done |
+| UT-042 | Download command filename sanitization | DR-015, DR-018 | Done |
+| UT-043 | Download command filename extension preservation | DR-015, DR-018 | Done |
+| UT-044 | Offline item serialization | DR-017 | Done |
+| UT-045 | Smart cache default config | DR-015 | Done |
+| UT-046 | Smart cache album affinity tracking | DR-015 | Done |
+| UT-047 | Smart cache queue precache config | DR-015 | Done |
+| UT-048 | Smart cache storage limit check | DR-015 | Done |
+| UT-049 | Playlist create (offline) | DR-019, JA-019 | Done |
+| UT-050 | Playlist delete (offline) | DR-019, JA-019 | Done |
+| UT-051 | Playlist rename (offline) | DR-019, JA-019 | Done |
+| UT-052 | Playlist get items (offline) | DR-019, JA-019 | Done |
+| UT-053 | Playlist add items (offline) | DR-019, JA-020 | Done |
+| UT-054 | Playlist remove items (offline) | DR-019, JA-020 | Done |
+| UT-055 | Playlist reorder items (offline) | DR-019, JA-020 | Done |
+| UT-056 | Playlist entry serialization | DR-019, JA-019 | Done |
+| UT-057 | Playlist Tauri command param naming (camelCase) | DR-019, JA-019, JA-020 | Done |
+| UT-058 | Playlist repository client methods | DR-019, JA-019, JA-020 | Done |
+
+### Integration Tests
+
+| Test ID | Test Description | Traces To | Status |
+|---------|-----------------|-----------|--------|
+| IT-001 | End-to-end authentication with Jellyfin server | IR-009, UR-009 | Pending |
+| IT-002 | Library browsing and item loading | IR-010, UR-007 | Pending |
+| IT-003 | Audio playback via libmpv | IR-003, UR-004 | Pending |
+| IT-004 | Video playback via libmpv | IR-003, UR-003 | Pending |
+| IT-005 | MPRIS lockscreen controls on Linux | IR-005, UR-006 | Pending |
+| IT-006 | Offline mode with local database | IR-013, UR-002 | Pending |
+| IT-007 | Media download and local playback | DR-015, UR-011 | Pending |
+| IT-008 | Subtitle track selection via libmpv | IR-018, UR-020 | Pending |
+| IT-009 | Audio track selection via libmpv | IR-019, UR-021 | Pending |
+| IT-010 | Playback progress sync to Jellyfin | IR-015, UR-025 | Pending |
+| IT-011 | Resume playback from server position | IR-015, UR-019 | Pending |
+| IT-012 | Equalizer bands via libmpv | IR-020, UR-027 | Pending |
+
+---
+
+## 5. Technical Debt
+
+### Linux Keyring Integration Workaround
+
+**Issue**: The `keyring-rs` crate (v3.x) has issues with retrieving credentials from the Linux Secret Service API, despite successfully saving them.
+
+**Symptoms**:
+- Credentials are saved to the system keyring successfully (verified with `secret-tool search`)
+- Retrieval via the `keyring-rs` library fails with `NoEntry` error
+- Session restoration fails on app restart even though credentials exist
+
+**Root Cause**:
+The `keyring-rs` library's Linux backend doesn't correctly retrieve entries from the Secret Service that it previously stored. This appears to be a bug in how the library interfaces with the Secret Service D-Bus API.
+
+**Current Workaround**:
+We bypass the `keyring-rs` library on Linux and use direct system calls to `secret-tool`:
+- **Save**: `secret-tool store --label <label> service <service> username <username>`
+- **Retrieve**: `secret-tool lookup service <service> username <username>`
+- **Delete**: `secret-tool clear service <service> username <username>`
+
+**Implementation**:
+See [src-tauri/src/credentials.rs](../src-tauri/src/credentials.rs) for the
+Linux-specific `secret-tool` save/get/delete paths.
+
+**Future Fix**:
+- Monitor `keyring-rs` for bug fixes in future versions
+- Consider alternative secure storage libraries
+- Test if newer versions of `keyring-rs` (v4.x+) resolve the issue
+- Once fixed, remove the Linux-specific workaround and use the cross-platform `keyring-rs` API
+
+**Impact**:
+- Low - The workaround is functionally equivalent to proper keyring integration
+- Credentials are stored securely in the system keyring
+- Session restoration works correctly
+- Only affects Linux; macOS and Windows use the standard `keyring-rs` implementation
+
+**Dependencies**:
+- Requires `secret-tool` to be installed on Linux systems (part of `libsecret-tools` package)
+- Already available on most Linux distributions by default
+
+---
+
+### Platform Playback Backend Parity (Linux vs Android)
+
+**Issue**: The Linux (MPV) and Android (ExoPlayer) playback backends have diverged in feature implementation and architecture patterns.
+
+**Symptoms**:
+- Audio settings (crossfade, gapless playback, volume normalization) work on Linux but not on Android
+- Position update frequency differs between platforms (Linux: 250ms polling, Android: on-demand callbacks)
+- Thread safety models differ (Linux: `Arc<Mutex<>>`, Android: global `OnceLock` statics)
+
+**Root Cause**:
+The `PlayerBackend` trait defines optional audio settings methods with default empty implementations. The Linux `MpvBackend` overrides these with full MPV property commands, but `ExoPlayerBackend` uses the defaults.
+
+**Affected Files**:
+- [src-tauri/src/player/backend.rs](../src-tauri/src/player/backend.rs) - Trait with default empty implementations
+- [src-tauri/src/player/mpv_backend.rs](../src-tauri/src/player/mpv_backend.rs) - Full audio settings support
+- [src-tauri/src/player/android/mod.rs](../src-tauri/src/player/android/mod.rs) - Missing audio settings implementation
+
+**Feature Parity Matrix**:
+
+| Feature | Linux (MPV) | Android (ExoPlayer) | Status |
+|---------|-------------|---------------------|--------|
+| Basic playback | ✅ | ✅ | Parity |
+| Volume control | ✅ | ✅ | Parity |
+| Seek | ✅ | ✅ | Parity |
+| Crossfade | ✅ | ❌ | Gap |
+| Gapless playback | ✅ | ❌ | Gap |
+| Volume normalization | ✅ | ❌ | Gap |
+| Position updates | 250ms | On-demand | Inconsistent |
+
+**Future Fix**:
+1. Implement `set_audio_settings()` in `ExoPlayerBackend`
+2. Add Kotlin-side ExoPlayer configuration for crossfade (using `ConcatenatingMediaSource` or `DefaultMediaSourceFactory`)
+3. Implement gapless via ExoPlayer's built-in gapless support
+4. Add volume normalization via ExoPlayer's `LoudnessEnhancer` or audio processor
+5. Standardize position update frequency across platforms
+
+**Impact**:
+- Medium - Android users lack audio enhancement features advertised in requirements
+- User experience differs between platforms
+- UR-031 (Crossfade), UR-032 (Gapless), UR-033 (Normalization) only work on Linux
+
+**Traces To**: IR-004, UR-031, UR-032, UR-033, DR-034, DR-035, DR-036
+
+---
+
+### Frontend Playback Code Duplication
+
+**Issue**: Playback control handlers and state derivations are duplicated between `AudioPlayer.svelte` and `MiniPlayer.svelte`.
+
+**Symptoms**:
+- Identical try-catch wrapped handler functions in both components (~44 lines duplicated)
+- Same `$derived` state merging logic for local/remote playback in both components
+- Position conversion (ticks ↔ seconds) scattered across multiple files
+
+**Affected Files**:
+- [src/lib/components/player/AudioPlayer.svelte](../src/lib/components/player/AudioPlayer.svelte) - Duplicate handlers
+- [src/lib/components/player/MiniPlayer.svelte](../src/lib/components/player/MiniPlayer.svelte) - Duplicate handlers
+- [src/lib/services/playbackControl.ts](../src/lib/services/playbackControl.ts) - Position conversion
+- [src/lib/stores/playbackMode.ts](../src/lib/stores/playbackMode.ts) - Position conversion
+- [src/lib/services/playbackReporting.ts](../src/lib/services/playbackReporting.ts) - Position conversion
+
+**Duplicated Code**:
+```typescript
+// These handlers are identical in both AudioPlayer and MiniPlayer:
+handlePlayPause(), handleNext(), handlePrevious(),
+handleToggleShuffle(), handleCycleRepeat(), handleVolumeChange()
+
+// These derived states use identical logic:
+displayMedia, displayIsPlaying, displayPosition, displayDuration
+```
+
+**Future Fix**:
+1. Create `src/lib/utils/playbackUnits.ts`:
+   ```typescript
+   export const TICKS_PER_SECOND = 10_000_000;
+   export const secondsToTicks = (s: number) => Math.floor(s * TICKS_PER_SECOND);
+   export const ticksToSeconds = (t: number) => t / TICKS_PER_SECOND;
+   ```
+
+2. Create `src/lib/composables/useMergedPlaybackState.svelte.ts`:
+   - Export `displayMedia`, `displayIsPlaying`, `displayPosition`, `displayDuration`
+   - Single source of truth for merged local/remote state
+
+3. Simplify handler wrappers using a utility:
+   ```typescript
+   export const withErrorHandler = (fn: () => Promise<void>, context: string) =>
+     async () => { try { await fn(); } catch (e) { console.error(`${context}:`, e); } };
+   ```
+
+**Impact**:
+- Low - Code works correctly but violates DRY principle
+- Maintenance burden when logic needs to change
+- Risk of handlers diverging over time
+
+**Traces To**: DR-009

package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "description": "",
   "type": "module",
+  "packageManager": "bun@1.3.5",
   "scripts": {
     "dev": "vite dev",
     "build": "vite build",
@@ -18,7 +19,7 @@
     "test:rust": "./scripts/test-rust.sh",
     "android:build": "./scripts/build-android.sh",
     "android:build:release": "./scripts/build-android.sh release",
-    "android:build:clean": "rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target && npm install && npm run build",
+    "android:build:clean": "rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target && bun install && bun run build",
     "android:deploy": "./scripts/deploy-android.sh",
     "android:dev": "./scripts/build-and-deploy.sh",
     "android:check": "./scripts/check-android.sh",

scripts/README.md

@@ -94,7 +94,7 @@ The traceability system is integrated with Gitea Actions CI/CD:
 
 For details, see:
 - [Traceability CI Guide](../docs/traceability-ci.md) - Full CI/CD documentation
-- [TRACES Quick Reference](../traces-quick-ref.md) - Quick guide for adding TRACES
+- [TRACES Quick Reference](../docs/traces-quick-ref.md) - Quick guide for adding TRACES
 
 ## Utility Scripts
 

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,13 +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: Clear build caches to ensure fresh builds
-echo "🧹 Clearing build caches..."
-rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target 2>/dev/null || true
-npm install > /dev/null 2>&1
+# 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..."
@@ -33,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

@@ -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/sync-android-sources.sh

@@ -31,4 +31,59 @@ 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
+
+# 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
+    # 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/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

@@ -33,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"
 
@@ -50,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,14 @@
+# 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.** { *; }
+
+# Media3 / ExoPlayer is accessed reflectively in places; keep it intact.
+-keep class androidx.media3.** { *; }
+-dontwarn androidx.media3.**

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/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,44 @@ 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)
+                    val positionSeconds = position / 1000.0
+                    nativeOnMediaCommand("seek:$positionSeconds")
                 }
             })
         }
@@ -253,9 +252,19 @@ 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
+
     /**
-     * Update the MediaSession metadata and playback state.
-     * This updates both the MediaSession and the notification.
+     * 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 +276,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)
@@ -280,7 +293,59 @@ class JellyTauPlaybackService : MediaSessionService() {
         session.setMetadata(metadataBuilder.build())
 
         // Update MediaSession playback state
-        val stateBuilder = PlaybackStateCompat.Builder()
+        session.setPlaybackState(buildPlaybackState(isPlaying, position))
+
+        // 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
+        session.setPlaybackState(buildPlaybackState(isPlaying, position))
+        // 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 +355,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,6 +138,15 @@ 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 = ""
@@ -152,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
 
@@ -171,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
@@ -202,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...")
@@ -239,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() {
@@ -316,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()
@@ -546,6 +577,7 @@ class JellyTauPlayer(private val appContext: Context) {
     ) {
         mainHandler.post {
             currentMediaId = mediaId
+            endedNotified = false
 
             // Store metadata for notification updates
             currentTitle = title
@@ -735,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)
             }
@@ -842,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>

src-tauri/src/auth/mod.rs

@@ -10,8 +10,9 @@ use crate::connectivity::ConnectivityMonitor;
 pub use session_verifier::SessionVerifier;
 
 /// Server information returned from Jellyfin
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
+#[specta(rename = "AuthServerInfo")]
 pub struct ServerInfo {
     pub name: String,
     pub version: String,
@@ -21,7 +22,7 @@ pub struct ServerInfo {
 }
 
 /// User information
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User {
     pub id: String,
@@ -31,7 +32,7 @@ pub struct User {
 }
 
 /// Authentication result
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AuthResult {
     pub user: User,
@@ -40,7 +41,7 @@ pub struct AuthResult {
 }
 
 /// Active session for restoration
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Session {
     pub user_id: String,
@@ -55,7 +56,7 @@ pub struct Session {
 
 // Jellyfin API response types (PascalCase from server)
 
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 struct PublicSystemInfo {
     server_name: String,
@@ -63,7 +64,7 @@ struct PublicSystemInfo {
     id: String,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 struct AuthenticateByNameResponse {
     user: JellyfinUser,
@@ -71,7 +72,7 @@ struct AuthenticateByNameResponse {
     server_id: String,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 struct JellyfinUser {
     id: String,
@@ -132,7 +133,7 @@ impl AuthManager {
 
         log::info!("[AuthManager] Connecting to server: {}", normalized_url);
 
-        match self.http_client.get_json_with_retry::<PublicSystemInfo>(&endpoint).await {
+        match self.http_client.get_json_fast::<PublicSystemInfo>(&endpoint).await {
             Ok(info) => {
                 log::info!("[AuthManager] Connected to server: {} ({})", info.server_name, info.version);
 

src-tauri/src/commands/auth.rs

@@ -12,6 +12,7 @@ pub struct SessionVerifierWrapper(pub Arc<tokio::sync::Mutex<Option<SessionVerif
 /// Initialize the auth manager (call on app startup)
 /// Restores session from storage if available
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_initialize(
     auth_manager: State<'_, AuthManagerWrapper>,
     database: State<'_, crate::commands::DatabaseWrapper>,
@@ -61,6 +62,7 @@ pub async fn auth_initialize(
 
 /// Connect to a Jellyfin server and get server info
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_connect_to_server(
     server_url: String,
     auth_manager: State<'_, AuthManagerWrapper>,
@@ -70,6 +72,7 @@ pub async fn auth_connect_to_server(
 
 /// Login with username and password
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_login(
     server_url: String,
     username: String,
@@ -100,6 +103,7 @@ pub async fn auth_login(
 
 /// Verify current session
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_verify_session(
     server_url: String,
     user_id: String,
@@ -118,6 +122,7 @@ pub async fn auth_verify_session(
 
 /// Logout (clear session and call Jellyfin logout endpoint)
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_logout(
     server_url: String,
     access_token: String,
@@ -143,6 +148,7 @@ pub async fn auth_logout(
 
 /// Get current session
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_get_session(
     auth_manager: State<'_, AuthManagerWrapper>,
 ) -> Result<Option<Session>, String> {
@@ -151,6 +157,7 @@ pub async fn auth_get_session(
 
 /// Set current session (for restoration from storage)
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_set_session(
     session: Option<Session>,
     auth_manager: State<'_, AuthManagerWrapper>,
@@ -170,6 +177,7 @@ pub async fn auth_set_session(
 
 /// Start background session verification
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_start_verification(
     device_id: String,
     app_handle: tauri::AppHandle,
@@ -198,6 +206,7 @@ pub async fn auth_start_verification(
 
 /// Stop background session verification
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_stop_verification(
     session_verifier: State<'_, SessionVerifierWrapper>,
 ) -> Result<(), String> {
@@ -212,6 +221,7 @@ pub async fn auth_stop_verification(
 
 /// Re-authenticate with password (when session expired)
 #[tauri::command]
+#[specta::specta]
 pub async fn auth_reauthenticate(
     password: String,
     device_id: String,

src-tauri/src/commands/catalog.rs

@@ -0,0 +1,469 @@
+//! Tauri commands for the offline "browse & queue" feature.
+//!
+//! Two backend pieces support browsing the full server catalog while offline
+//! and queueing downloads that fire on reconnect:
+//!
+//! - [`sync_full_catalog`] walks every library while online and persists all
+//!   items to the offline cache so the whole catalog is browsable (greyed out)
+//!   offline. It reuses [`HybridRepository::cache_items_from_server`], which in
+//!   turn reuses `OfflineRepository::save_to_cache` (sets `synced_at`, which is
+//!   what `get_items` branch 3 serves offline).
+//! - [`resume_queued_downloads`] resolves and pumps the `pending` download rows
+//!   that were queued offline (they have `stream_url IS NULL`), mirroring the
+//!   heal-and-pump pattern in `player_preload_upcoming`.
+
+use std::sync::Arc;
+
+use log::{info, warn};
+use tauri::State;
+
+use crate::commands::repository::RepositoryManagerWrapper;
+use crate::commands::download::{pump_download_queue, DownloadManagerWrapper};
+use crate::commands::storage::DatabaseWrapper;
+use crate::repository::types::GetItemsOptions;
+use crate::storage::db_service::{DatabaseService, Query, QueryParam};
+
+/// app_settings key holding the RFC-3339 timestamp of the last successful
+/// full-catalog sync.
+const LAST_CATALOG_SYNC_KEY: &str = "last_catalog_sync";
+
+/// Item types worth caching for offline browsing: containers the library
+/// landing pages render plus the playable leaves users queue for download.
+const CATALOG_ITEM_TYPES: &[&str] = &[
+    "MusicAlbum",
+    "Movie",
+    "Series",
+    "Season",
+    "Episode",
+    "Audio",
+    "BoxSet",
+];
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogSyncResult {
+    /// Total items persisted to the offline cache across all libraries.
+    pub items_cached: usize,
+    /// Libraries that failed to sync (e.g. server hiccup); best-effort.
+    pub libraries_failed: usize,
+}
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogSyncStatus {
+    /// RFC-3339 timestamp of the last successful sync, if any.
+    pub last_synced_at: Option<String>,
+}
+
+/// Walk every library on the server and persist all items to the offline cache
+/// so the full catalog is browsable offline (greyed out when not downloaded).
+///
+/// Best-effort: a library that fails to fetch is counted and skipped rather than
+/// aborting the whole sync. Runs libraries sequentially to avoid hammering the
+/// server. Uses `Recursive=true` so a single request per library returns the
+/// containers and their playable children.
+#[tauri::command]
+#[specta::specta]
+pub async fn sync_full_catalog(
+    repository: State<'_, RepositoryManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
+    handle: String,
+) -> Result<CatalogSyncResult, String> {
+    use crate::repository::MediaRepository;
+
+    let repo = repository.0.get(&handle).ok_or("Repository not found")?;
+
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let libraries = repo.get_libraries().await.map_err(|e| e.to_string())?;
+    info!("[Catalog] Full sync starting across {} libraries", libraries.len());
+
+    let include_types: Vec<String> = CATALOG_ITEM_TYPES.iter().map(|s| s.to_string()).collect();
+
+    let mut items_cached = 0usize;
+    let mut libraries_failed = 0usize;
+
+    for library in &libraries {
+        let opts = GetItemsOptions {
+            recursive: Some(true),
+            include_item_types: Some(include_types.clone()),
+            limit: Some(100_000),
+            ..Default::default()
+        };
+
+        match repo.cache_items_from_server(&library.id, Some(opts)).await {
+            Ok(items) => {
+                info!(
+                    "[Catalog] Cached {} items from library '{}'",
+                    items.len(),
+                    library.name
+                );
+                items_cached += items.len();
+            }
+            Err(e) => {
+                warn!("[Catalog] Failed to sync library '{}': {:?}", library.name, e);
+                libraries_failed += 1;
+            }
+        }
+    }
+
+    // Record the sync time so callers can skip re-syncing too eagerly.
+    let now = chrono::Utc::now().to_rfc3339();
+    let upsert = Query::with_params(
+        "INSERT INTO app_settings (key, value, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP",
+        vec![
+            QueryParam::String(LAST_CATALOG_SYNC_KEY.to_string()),
+            QueryParam::String(now),
+        ],
+    );
+    if let Err(e) = db_service.execute(upsert).await {
+        warn!("[Catalog] Failed to persist last-sync timestamp: {}", e);
+    }
+
+    info!(
+        "[Catalog] Full sync complete: {} items cached, {} libraries failed",
+        items_cached, libraries_failed
+    );
+
+    Ok(CatalogSyncResult {
+        items_cached,
+        libraries_failed,
+    })
+}
+
+/// Report the last-synced timestamp so the UI can show a hint / decide whether
+/// to trigger a fresh sync.
+#[tauri::command]
+#[specta::specta]
+pub async fn catalog_sync_status(
+    db: State<'_, DatabaseWrapper>,
+) -> Result<CatalogSyncStatus, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let query = Query::with_params(
+        "SELECT value FROM app_settings WHERE key = ?",
+        vec![QueryParam::String(LAST_CATALOG_SYNC_KEY.to_string())],
+    );
+    let last_synced_at: Option<String> = db_service
+        .query_optional(query, |row| row.get(0))
+        .await
+        .map_err(|e| e.to_string())?;
+
+    Ok(CatalogSyncStatus { last_synced_at })
+}
+
+/// Control whether offline library queries reveal the full synced catalog
+/// (greyed-out, non-downloaded media) or only downloaded/local media.
+///
+/// The frontend calls this from the "Show all server media" toggle: pass `true`
+/// when online, or when offline with the toggle on; pass `false` when offline
+/// with the toggle off so library pages show downloaded media only. Fixes the
+/// bug where offline library pages showed every server item regardless of the
+/// toggle.
+#[tauri::command]
+#[specta::specta]
+pub fn set_show_server_catalog(show: bool) {
+    crate::repository::offline::set_include_catalog_browse(show);
+}
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ResumeQueuedResult {
+    /// Rows whose stream URL was resolved and are now pump-eligible.
+    pub resolved: usize,
+    /// Rows that couldn't be resolved (item metadata / URL lookup failed).
+    pub failed: usize,
+}
+
+/// Core of [`resume_queued_downloads`], factored out for testing: select every
+/// `pending`/`stream_url IS NULL` row, resolve each via `resolve` (returning
+/// `None` leaves the row pending), and heal the row so the pump can start it.
+/// The `resolve` closure receives `(item_id, media_type, quality_preset)`.
+pub(crate) async fn resolve_pending_download_urls<F, Fut>(
+    db_service: &Arc<crate::storage::db_service::RusqliteService>,
+    target_dir: &str,
+    resolve: F,
+) -> Result<ResumeQueuedResult, String>
+where
+    F: Fn(String, String, String) -> Fut,
+    Fut: std::future::Future<Output = Option<String>>,
+{
+    let rows_query = Query::new(
+        "SELECT id, item_id, COALESCE(media_type, 'audio'), COALESCE(quality_preset, 'original')
+         FROM downloads
+         WHERE status = 'pending' AND stream_url IS NULL",
+    );
+    let rows: Vec<(i64, String, String, String)> = db_service
+        .query_many(rows_query, |row| {
+            Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
+        })
+        .await
+        .map_err(|e| e.to_string())?;
+
+    if rows.is_empty() {
+        return Ok(ResumeQueuedResult { resolved: 0, failed: 0 });
+    }
+
+    info!("[Catalog] Resolving {} offline-queued downloads on reconnect", rows.len());
+
+    let mut resolved = 0usize;
+    let mut failed = 0usize;
+
+    for (download_id, item_id, media_type, quality) in rows {
+        let stream_url = match resolve(item_id.clone(), media_type, quality).await {
+            Some(url) => url,
+            None => {
+                failed += 1;
+                continue;
+            }
+        };
+
+        // Heal the row so the pump can start it. Guard on stream_url IS NULL so a
+        // concurrent resolver doesn't clobber an already-started row.
+        let update = Query::with_params(
+            "UPDATE downloads SET stream_url = ?, target_dir = ?
+             WHERE id = ? AND status = 'pending' AND stream_url IS NULL",
+            vec![
+                QueryParam::String(stream_url),
+                QueryParam::String(target_dir.to_string()),
+                QueryParam::Int64(download_id),
+            ],
+        );
+        match db_service.execute(update).await {
+            Ok(n) if n > 0 => resolved += 1,
+            Ok(_) => {} // already resolved by someone else; not a failure
+            Err(e) => {
+                warn!("[Catalog] Failed to persist URL for download {}: {}", download_id, e);
+                failed += 1;
+            }
+        }
+    }
+
+    Ok(ResumeQueuedResult { resolved, failed })
+}
+
+/// Resolve the stream URL for every download row that was queued while offline
+/// (`status = 'pending' AND stream_url IS NULL`), then pump the queue so they
+/// start. Call this on reconnect.
+///
+/// Audio rows resolve via `get_audio_stream_url`; video rows (media_type =
+/// 'video') via the pure `get_video_download_url` builder using the row's stored
+/// `quality_preset` — mirroring `enqueue_video_downloads`. Rows whose URL can't
+/// be resolved are left pending (they retry on the next reconnect).
+#[tauri::command]
+#[specta::specta]
+pub async fn resume_queued_downloads(
+    repository: State<'_, RepositoryManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
+    download_manager: State<'_, DownloadManagerWrapper>,
+    app: tauri::AppHandle,
+    handle: String,
+) -> Result<ResumeQueuedResult, String> {
+    use crate::repository::MediaRepository;
+
+    use crate::repository::HybridRepository;
+
+    let repo = repository.0.get(&handle).ok_or("Repository not found")?;
+
+    // The pump needs a target_dir; use the same storage root the other download
+    // paths use (the database's parent directory — see `storage_get_path`).
+    let (db_service, target_dir) = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        let target_dir = database
+            .path()
+            .parent()
+            .ok_or_else(|| "Database path has no parent directory".to_string())?
+            .to_string_lossy()
+            .to_string();
+        (Arc::new(database.service()), target_dir)
+    };
+
+    // Recover stale downloads: rows left in 'downloading' when the app was killed
+    // mid-transfer are orphaned — nothing ever restarts them, so they show as
+    // permanently "downloading". Reset them to 'pending' and clear the stale
+    // stream_url so they get re-resolved and restarted from scratch below.
+    let recover_query = Query::new(
+        "UPDATE downloads SET status = 'pending', stream_url = NULL, progress = 0, \
+         bytes_downloaded = 0, started_at = NULL \
+         WHERE status = 'downloading'",
+    );
+    match db_service.execute(recover_query).await {
+        Ok(n) if n > 0 => info!("[Catalog] Reset {} stale 'downloading' rows to pending", n),
+        Ok(_) => {}
+        Err(e) => warn!("[Catalog] Failed to reset stale downloads: {}", e),
+    }
+
+    // Resolve each row's URL against the (now reachable) repository.
+    let repo_for_resolve = Arc::clone(&repo);
+    let outcome = resolve_pending_download_urls(
+        &db_service,
+        &target_dir,
+        move |item_id: String, media_type: String, quality: String| {
+            let repo = Arc::clone(&repo_for_resolve);
+            async move {
+                if media_type == "video" {
+                    Some(<HybridRepository as MediaRepository>::get_video_download_url(
+                        repo.as_ref(),
+                        &item_id,
+                        &quality,
+                        None,
+                    ))
+                } else {
+                    match repo.get_audio_stream_url(&item_id).await {
+                        Ok(url) => Some(url),
+                        Err(e) => {
+                            warn!("[Catalog] Failed to resolve audio URL for {}: {:?}", item_id, e);
+                            None
+                        }
+                    }
+                }
+            }
+        },
+    )
+    .await
+    .map_err(|e| e.to_string())?;
+
+    let ResumeQueuedResult { resolved, failed } = outcome;
+
+    // Kick the pump so the newly-resolved rows actually start.
+    if resolved > 0 {
+        let active_downloads = {
+            let manager = download_manager.0.lock().map_err(|e| e.to_string())?;
+            manager.get_active_downloads()
+        };
+        pump_download_queue(app, db_service, active_downloads).await;
+    }
+
+    info!("[Catalog] Resume complete: {} resolved, {} failed", resolved, failed);
+
+    Ok(ResumeQueuedResult { resolved, failed })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::storage::db_service::RusqliteService;
+    use rusqlite::Connection;
+    use std::sync::Mutex;
+
+    fn test_db() -> Arc<RusqliteService> {
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(
+            r#"
+            CREATE TABLE downloads (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                item_id TEXT NOT NULL,
+                status TEXT NOT NULL,
+                stream_url TEXT,
+                target_dir TEXT,
+                media_type TEXT,
+                quality_preset TEXT
+            );
+            "#,
+        )
+        .unwrap();
+        Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))))
+    }
+
+    async fn insert_download(
+        db: &Arc<RusqliteService>,
+        item_id: &str,
+        status: &str,
+        stream_url: Option<&str>,
+        media_type: Option<&str>,
+    ) {
+        let q = Query::with_params(
+            "INSERT INTO downloads (item_id, status, stream_url, media_type) VALUES (?, ?, ?, ?)",
+            vec![
+                QueryParam::String(item_id.to_string()),
+                QueryParam::String(status.to_string()),
+                stream_url.map(|s| QueryParam::String(s.to_string())).unwrap_or(QueryParam::Null),
+                media_type.map(|s| QueryParam::String(s.to_string())).unwrap_or(QueryParam::Null),
+            ],
+        );
+        db.execute(q).await.unwrap();
+    }
+
+    async fn get_row(db: &Arc<RusqliteService>, item_id: &str) -> (String, Option<String>, Option<String>) {
+        let q = Query::with_params(
+            "SELECT status, stream_url, target_dir FROM downloads WHERE item_id = ?",
+            vec![QueryParam::String(item_id.to_string())],
+        );
+        db.query_one(q, |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
+            .await
+            .unwrap()
+    }
+
+    #[tokio::test]
+    async fn resolves_offline_queued_row_and_leaves_resolved_rows_untouched() {
+        let db = test_db();
+        // A row queued offline: pending with no URL yet.
+        insert_download(&db, "queued-1", "pending", None, None).await;
+        // An already-resolved pending row: must NOT be touched.
+        insert_download(&db, "already", "pending", Some("http://existing/url"), None).await;
+        // A completed row: irrelevant.
+        insert_download(&db, "done", "completed", Some("http://done/url"), None).await;
+
+        let out = resolve_pending_download_urls(&db, "/data/downloads", |item_id, _mt, _q| async move {
+            Some(format!("http://resolved/{item_id}"))
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(out.resolved, 1);
+        assert_eq!(out.failed, 0);
+
+        // The offline-queued row now has a URL + target dir and stays pending.
+        let (status, url, target) = get_row(&db, "queued-1").await;
+        assert_eq!(status, "pending");
+        assert_eq!(url.as_deref(), Some("http://resolved/queued-1"));
+        assert_eq!(target.as_deref(), Some("/data/downloads"));
+
+        // The already-resolved row is unchanged (not re-resolved).
+        let (_s, url2, _t) = get_row(&db, "already").await;
+        assert_eq!(url2.as_deref(), Some("http://existing/url"));
+    }
+
+    #[tokio::test]
+    async fn counts_unresolvable_rows_as_failed_and_leaves_them_pending() {
+        let db = test_db();
+        insert_download(&db, "bad", "pending", None, None).await;
+
+        // Resolver returns None (e.g. server lookup failed).
+        let out = resolve_pending_download_urls(&db, "/data", |_id, _mt, _q| async move { None })
+            .await
+            .unwrap();
+
+        assert_eq!(out.resolved, 0);
+        assert_eq!(out.failed, 1);
+
+        // Still pending with no URL, so a later reconnect can retry it.
+        let (status, url, _t) = get_row(&db, "bad").await;
+        assert_eq!(status, "pending");
+        assert_eq!(url, None);
+    }
+
+    #[tokio::test]
+    async fn video_rows_use_media_type_in_resolver() {
+        let db = test_db();
+        insert_download(&db, "vid-1", "pending", None, Some("video")).await;
+
+        let out = resolve_pending_download_urls(&db, "/data", |item_id, media_type, _q| async move {
+            assert_eq!(media_type, "video");
+            Some(format!("http://transcode/{item_id}"))
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(out.resolved, 1);
+        let (_s, url, _t) = get_row(&db, "vid-1").await;
+        assert_eq!(url.as_deref(), Some("http://transcode/vid-1"));
+    }
+}

src-tauri/src/commands/connectivity.rs

@@ -7,6 +7,7 @@ pub struct ConnectivityMonitorWrapper(pub Arc<tokio::sync::Mutex<ConnectivityMon
 
 /// Check if the server is currently reachable
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_check_server(
     state: State<'_, ConnectivityMonitorWrapper>,
 ) -> Result<bool, String> {
@@ -16,6 +17,7 @@ pub async fn connectivity_check_server(
 
 /// Set the server URL and trigger an immediate check
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_set_server_url(
     url: String,
     state: State<'_, ConnectivityMonitorWrapper>,
@@ -27,6 +29,7 @@ pub async fn connectivity_set_server_url(
 
 /// Get the current connectivity status
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_get_status(
     state: State<'_, ConnectivityMonitorWrapper>,
 ) -> Result<ConnectivityStatus, String> {
@@ -36,6 +39,7 @@ pub async fn connectivity_get_status(
 
 /// Start monitoring connectivity with adaptive polling
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_start_monitoring(
     state: State<'_, ConnectivityMonitorWrapper>,
 ) -> Result<(), String> {
@@ -46,6 +50,7 @@ pub async fn connectivity_start_monitoring(
 
 /// Stop monitoring connectivity
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_stop_monitoring(
     state: State<'_, ConnectivityMonitorWrapper>,
 ) -> Result<(), String> {
@@ -56,6 +61,7 @@ pub async fn connectivity_stop_monitoring(
 
 /// Mark the server as reachable (called after successful API calls)
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_mark_reachable(
     state: State<'_, ConnectivityMonitorWrapper>,
 ) -> Result<(), String> {
@@ -66,6 +72,7 @@ pub async fn connectivity_mark_reachable(
 
 /// Mark the server as unreachable (called after failed API calls)
 #[tauri::command]
+#[specta::specta]
 pub async fn connectivity_mark_unreachable(
     error: Option<String>,
     state: State<'_, ConnectivityMonitorWrapper>,

src-tauri/src/commands/conversions.rs

@@ -16,6 +16,7 @@ use crate::utils::conversions::{
 /// # Returns
 /// Formatted string like "3:45" or "12:09"
 #[tauri::command]
+#[specta::specta]
 pub fn format_time_seconds(seconds: f64) -> String {
     format_time(seconds)
 }
@@ -32,6 +33,7 @@ pub fn format_time_seconds(seconds: f64) -> String {
 /// # Returns
 /// Formatted string like "1:23:45" or "3:45"
 #[tauri::command]
+#[specta::specta]
 pub fn format_time_seconds_long(seconds: f64) -> String {
     format_time_long(seconds)
 }
@@ -44,6 +46,7 @@ pub fn format_time_seconds_long(seconds: f64) -> String {
 /// # Returns
 /// Time in seconds
 #[tauri::command]
+#[specta::specta]
 pub fn convert_ticks_to_seconds(ticks: i64) -> f64 {
     ticks_to_seconds(ticks)
 }
@@ -57,6 +60,7 @@ pub fn convert_ticks_to_seconds(ticks: i64) -> f64 {
 /// # Returns
 /// Progress as percentage (0.0 to 100.0)
 #[tauri::command]
+#[specta::specta]
 pub fn calc_progress(position: f64, duration: f64) -> f64 {
     calculate_progress(position, duration)
 }
@@ -69,6 +73,7 @@ pub fn calc_progress(position: f64, duration: f64) -> f64 {
 /// # Returns
 /// Normalized volume (0.0 to 1.0)
 #[tauri::command]
+#[specta::specta]
 pub fn convert_percent_to_volume(percent: f64) -> f64 {
     percent_to_volume(percent)
 }

src-tauri/src/commands/device.rs

@@ -23,6 +23,7 @@ use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 ///
 /// TRACES: UR-009 | DR-011
 #[tauri::command]
+#[specta::specta]
 pub async fn device_get_id(db: State<'_, DatabaseWrapper>) -> Result<String, String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -79,6 +80,7 @@ pub async fn device_get_id(db: State<'_, DatabaseWrapper>) -> Result<String, Str
 ///
 /// TRACES: UR-009 | DR-011
 #[tauri::command]
+#[specta::specta]
 pub async fn device_set_id(device_id: String, db: State<'_, DatabaseWrapper>) -> Result<(), String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;

src-tauri/src/commands/download/pinning.rs

@@ -0,0 +1,66 @@
+//! Pinning commands - protect an item's cached metadata from cache clearing.
+
+use std::sync::Arc;
+use tauri::State;
+
+use crate::commands::DatabaseWrapper;
+use crate::storage::db_service::{DatabaseService, Query, QueryParam};
+
+/// Pin an item's metadata (protects from cache clear)
+#[tauri::command]
+#[specta::specta]
+pub async fn pin_item(db: State<'_, DatabaseWrapper>, item_id: String) -> Result<(), String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let query = Query::with_params(
+        "UPDATE items SET is_pinned = 1 WHERE id = ?",
+        vec![QueryParam::String(item_id)],
+    );
+
+    db_service.execute(query).await.map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+/// Unpin an item's metadata
+#[tauri::command]
+#[specta::specta]
+pub async fn unpin_item(db: State<'_, DatabaseWrapper>, item_id: String) -> Result<(), String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let query = Query::with_params(
+        "UPDATE items SET is_pinned = 0 WHERE id = ?",
+        vec![QueryParam::String(item_id)],
+    );
+
+    db_service.execute(query).await.map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+/// Check if an item is pinned
+#[tauri::command]
+#[specta::specta]
+pub async fn is_item_pinned(db: State<'_, DatabaseWrapper>, item_id: String) -> Result<bool, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let query = Query::with_params(
+        "SELECT COALESCE(is_pinned, 0) FROM items WHERE id = ?",
+        vec![QueryParam::String(item_id)],
+    );
+
+    let is_pinned: i32 = db_service
+        .query_optional(query, |row| row.get(0))
+        .await
+        .map_err(|e| e.to_string())?
+        .unwrap_or(0);
+
+    Ok(is_pinned == 1)
+}

src-tauri/src/commands/download/smart_cache.rs

@@ -0,0 +1,228 @@
+//! Smart-cache statistics/config and album recommendation commands.
+
+use std::sync::Arc;
+use log::info;
+use tauri::State;
+
+use crate::commands::{DatabaseWrapper, SmartCacheWrapper};
+use crate::storage::db_service::{DatabaseService, Query, QueryParam};
+
+/// SmartCache statistics
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
+pub struct SmartCacheStats {
+    pub total_size: u64,
+    pub storage_limit: u64,
+    pub available_space: u64,
+    pub items_count: i64,
+    pub config: crate::download::cache::CacheConfig,
+}
+
+/// Get SmartCache statistics
+#[tauri::command]
+#[specta::specta]
+pub async fn get_smart_cache_stats(
+    db: State<'_, DatabaseWrapper>,
+    smart_cache: State<'_, SmartCacheWrapper>,
+    user_id: String,
+) -> Result<SmartCacheStats, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    // Clone cache to avoid holding lock across async operations
+    let cache = {
+        let guard = smart_cache.0.lock().map_err(|e| e.to_string())?;
+        guard.clone()
+    };
+
+    let total_size = cache
+        .get_total_download_size_async(&db_service, &user_id)
+        .await?;
+
+    let config = cache
+        .get_config()
+        .ok_or_else(|| "Failed to get cache config".to_string())?;
+
+    let storage_limit = config.storage_limit;
+    let available_space = storage_limit.saturating_sub(total_size);
+
+    // Get item count
+    let count_query = Query::with_params(
+        "SELECT COUNT(*) FROM downloads WHERE user_id = ? AND status = 'completed'",
+        vec![QueryParam::String(user_id)],
+    );
+    let items_count: i64 = db_service
+        .query_one(count_query, |row| row.get(0))
+        .await
+        .unwrap_or(0);
+
+    Ok(SmartCacheStats {
+        total_size,
+        storage_limit,
+        available_space,
+        items_count,
+        config,
+    })
+}
+
+/// Update SmartCache configuration
+#[tauri::command]
+#[specta::specta]
+pub async fn update_smart_cache_config(
+    smart_cache: State<'_, SmartCacheWrapper>,
+    config: crate::download::cache::CacheConfig,
+) -> Result<(), String> {
+    let cache = smart_cache.0.lock().map_err(|e| e.to_string())?;
+    cache.update_config(config);
+    info!("Updated SmartCache configuration");
+    Ok(())
+}
+
+/// Get SmartCache configuration
+#[tauri::command]
+#[specta::specta]
+pub async fn get_smart_cache_config(
+    smart_cache: State<'_, SmartCacheWrapper>,
+) -> Result<crate::download::cache::CacheConfig, String> {
+    let cache = smart_cache.0.lock().map_err(|e| e.to_string())?;
+    cache
+        .get_config()
+        .ok_or_else(|| "Failed to get cache config".to_string())
+}
+
+/// Album recommendation info
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
+pub struct AlbumRecommendation {
+    pub album_id: String,
+    pub album_name: String,
+    pub tracks_played: usize,
+    pub total_tracks: usize,
+    pub should_download: bool,
+}
+
+/// Album affinity status info
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AlbumAffinityStatus {
+    pub album_id: String,
+    pub unique_tracks_played: usize,
+    pub threshold: usize,
+    pub threshold_reached: bool,
+}
+
+/// Get album recommendations based on play history
+#[tauri::command]
+#[specta::specta]
+pub async fn get_album_recommendations(
+    db: State<'_, DatabaseWrapper>,
+    smart_cache: State<'_, SmartCacheWrapper>,
+    user_id: String,
+) -> Result<Vec<AlbumRecommendation>, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    // Clone cache to avoid holding lock across async operations
+    let cache = {
+        let guard = smart_cache.0.lock().map_err(|e| e.to_string())?;
+        guard.clone()
+    };
+
+    // Get all albums that user has played tracks from
+    let query = Query::with_params(
+        "SELECT DISTINCT i.album_id, a.name
+         FROM user_data ud
+         JOIN items i ON ud.item_id = i.id
+         JOIN items a ON i.album_id = a.id
+         WHERE ud.user_id = ?
+           AND ud.play_count > 0
+           AND i.item_type = 'Audio'
+           AND i.album_id IS NOT NULL",
+        vec![QueryParam::String(user_id.clone())],
+    );
+
+    let albums: Vec<(String, String)> = db_service
+        .query_many(query, |row| Ok((row.get(0)?, row.get(1)?)))
+        .await
+        .unwrap_or_default();
+
+    let mut recommendations = Vec::new();
+
+    for (album_id, album_name) in albums {
+        // Check if should cache
+        let should_download = cache.should_cache_album(&album_id).unwrap_or(false);
+
+        // Get track counts
+        let tracks_query = Query::with_params(
+            "SELECT
+                COUNT(*) as total,
+                COUNT(ud.id) as played
+             FROM items i
+             LEFT JOIN user_data ud ON i.id = ud.item_id AND ud.user_id = ?
+             WHERE i.album_id = ? AND i.item_type = 'Audio'",
+            vec![
+                QueryParam::String(user_id.clone()),
+                QueryParam::String(album_id.clone()),
+            ],
+        );
+
+        let (total_tracks, tracks_played): (i64, i64) = db_service
+            .query_one(tracks_query, |row| Ok((row.get(0)?, row.get(1)?)))
+            .await
+            .unwrap_or((0, 0));
+
+        if tracks_played > 0 {
+            recommendations.push(AlbumRecommendation {
+                album_id,
+                album_name,
+                tracks_played: tracks_played as usize,
+                total_tracks: total_tracks as usize,
+                should_download,
+            });
+        }
+    }
+
+    // Sort by tracks played (descending)
+    recommendations.sort_by(|a, b| b.tracks_played.cmp(&a.tracks_played));
+
+    Ok(recommendations)
+}
+
+/// Get album affinity status for all tracked albums
+/// This shows the SmartCache's internal play history and threshold status
+#[tauri::command]
+#[specta::specta]
+pub fn get_album_affinity_status(
+    smart_cache: State<'_, SmartCacheWrapper>,
+) -> Result<Vec<AlbumAffinityStatus>, String> {
+    let cache = smart_cache.0.lock().map_err(|e| e.to_string())?;
+
+    // Get the threshold from config
+    let threshold = cache
+        .get_config()
+        .map(|c| c.album_affinity_threshold)
+        .unwrap_or(3);
+
+    // Get all tracked albums with their play counts
+    let play_history = cache.get_album_play_history();
+
+    let mut statuses: Vec<AlbumAffinityStatus> = play_history
+        .into_iter()
+        .map(|(album_id, unique_tracks_played)| {
+            let threshold_reached = unique_tracks_played >= threshold;
+            AlbumAffinityStatus {
+                album_id,
+                unique_tracks_played,
+                threshold,
+                threshold_reached,
+            }
+        })
+        .collect();
+
+    // Sort by play count (descending)
+    statuses.sort_by(|a, b| b.unique_tracks_played.cmp(&a.unique_tracks_played));
+
+    Ok(statuses)
+}

src-tauri/src/commands/mod.rs

@@ -2,6 +2,7 @@
 // TRACES: UR-002, UR-003, UR-004, UR-005, UR-009, UR-011, UR-012, UR-017, UR-019, UR-025 |
 //         DR-015, DR-017, DR-021, DR-028
 pub mod auth;
+pub mod catalog;
 pub mod connectivity;
 pub mod conversions;
 pub mod device;
@@ -17,6 +18,7 @@ pub mod storage;
 pub mod sync;
 
 pub use auth::*;
+pub use catalog::*;
 pub use connectivity::*;
 pub use conversions::*;
 pub use device::*;

src-tauri/src/commands/offline.rs

@@ -7,7 +7,7 @@ use tauri::State;
 use super::DatabaseWrapper;
 use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
-#[derive(Debug, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct OfflineItem {
     pub id: String,
@@ -22,6 +22,7 @@ pub struct OfflineItem {
 
 /// Check if an item is available offline
 #[tauri::command]
+#[specta::specta]
 pub async fn offline_is_available(
     db: State<'_, DatabaseWrapper>,
     item_id: String,
@@ -46,6 +47,7 @@ pub async fn offline_is_available(
 
 /// Get all offline items for a user
 #[tauri::command]
+#[specta::specta]
 pub async fn offline_get_items(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -84,6 +86,7 @@ pub async fn offline_get_items(
 
 /// Search offline items
 #[tauri::command]
+#[specta::specta]
 pub async fn offline_search(
     db: State<'_, DatabaseWrapper>,
     user_id: String,

src-tauri/src/commands/playback_mode.rs

@@ -8,6 +8,7 @@ pub struct PlaybackModeManagerWrapper(pub Arc<PlaybackModeManager>);
 
 /// Get the current playback mode
 #[tauri::command]
+#[specta::specta]
 pub fn playback_mode_get_current(
     manager: State<'_, PlaybackModeManagerWrapper>,
 ) -> Result<PlaybackMode, String> {
@@ -16,6 +17,7 @@ pub fn playback_mode_get_current(
 
 /// Set the playback mode (internal/testing use)
 #[tauri::command]
+#[specta::specta]
 pub fn playback_mode_set(
     manager: State<'_, PlaybackModeManagerWrapper>,
     mode: PlaybackMode,
@@ -26,6 +28,7 @@ pub fn playback_mode_set(
 
 /// Check if currently transferring between playback modes
 #[tauri::command]
+#[specta::specta]
 pub fn playback_mode_is_transferring(
     manager: State<'_, PlaybackModeManagerWrapper>,
 ) -> Result<bool, String> {
@@ -34,15 +37,34 @@ pub fn playback_mode_is_transferring(
 
 /// Transfer playback from local device to a remote Jellyfin session
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_mode_transfer_to_remote(
     manager: State<'_, PlaybackModeManagerWrapper>,
     session_id: String,
+    position: Option<f64>,
 ) -> Result<(), String> {
     log::info!(
-        "[PlaybackModeCommands] Transferring to remote session: {}",
-        session_id
+        "[PlaybackModeCommands] Transferring to remote session: {} (position override: {:?})",
+        session_id,
+        position
     );
-    manager.0.transfer_to_remote(session_id).await
+    manager.0.transfer_to_remote(session_id, position).await
+}
+
+/// Set the transferring flag on the playback mode manager.
+///
+/// Used by the frontend remote->local flow to mark the whole two-step sequence
+/// as a transfer, so `player_play_tracks` starts LOCAL playback instead of
+/// casting back to the remote session it's leaving. Always pair `true` with a
+/// later `false` (including on error) so the flag can't stick.
+#[tauri::command]
+#[specta::specta]
+pub async fn playback_mode_set_transferring(
+    manager: State<'_, PlaybackModeManagerWrapper>,
+    transferring: bool,
+) -> Result<(), String> {
+    manager.0.set_transferring(transferring);
+    Ok(())
 }
 
 /// Transfer playback from remote session back to local device
@@ -51,6 +73,7 @@ pub async fn playback_mode_transfer_to_remote(
 /// - current_item_id: The Jellyfin item ID currently playing on remote
 /// - position_ticks: Current playback position in ticks (10,000 ticks = 1ms)
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_mode_transfer_to_local(
     manager: State<'_, PlaybackModeManagerWrapper>,
     current_item_id: String,
@@ -69,6 +92,7 @@ pub async fn playback_mode_transfer_to_local(
 
 /// Get remote session status (for polling position/duration)
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_mode_get_remote_status(
     manager: State<'_, PlaybackModeManagerWrapper>,
     player: State<'_, crate::commands::PlayerStateWrapper>,
@@ -119,7 +143,7 @@ pub async fn playback_mode_get_remote_status(
 }
 
 /// Remote session status for UI updates
-#[derive(serde::Serialize)]
+#[derive(specta::Type, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RemoteSessionStatus {
     pub position: f64,

src-tauri/src/commands/playback_reporting.rs

@@ -24,6 +24,7 @@ pub struct PlaybackReporterWrapper(pub Arc<TokioMutex<Option<PlaybackReporter>>>
 
 /// Initialize playback reporter (called after login)
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_reporter_init(
     reporter_wrapper: State<'_, PlaybackReporterWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -66,6 +67,7 @@ pub async fn playback_reporter_init(
 
 /// Destroy playback reporter (called on logout)
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_reporter_destroy(
     reporter_wrapper: State<'_, PlaybackReporterWrapper>,
 ) -> Result<(), String> {
@@ -76,6 +78,7 @@ pub async fn playback_reporter_destroy(
 
 /// Report playback start
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_report_start(
     reporter: State<'_, PlaybackReporterWrapper>,
     connectivity: State<'_, ConnectivityMonitorWrapper>,
@@ -110,6 +113,7 @@ pub async fn playback_report_start(
 
 /// Report playback progress
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_report_progress(
     reporter: State<'_, PlaybackReporterWrapper>,
     connectivity: State<'_, ConnectivityMonitorWrapper>,
@@ -138,6 +142,7 @@ pub async fn playback_report_progress(
 
 /// Report playback stopped
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_report_stopped(
     reporter: State<'_, PlaybackReporterWrapper>,
     connectivity: State<'_, ConnectivityMonitorWrapper>,
@@ -164,6 +169,7 @@ pub async fn playback_report_stopped(
 
 /// Mark item as played
 #[tauri::command]
+#[specta::specta]
 pub async fn playback_mark_played(
     reporter: State<'_, PlaybackReporterWrapper>,
     connectivity: State<'_, ConnectivityMonitorWrapper>,