fix: Autoplay now resets time to zero and ignores trigger if episode already started (#3)

Reviewed-on: #3
Co-authored-by: Duncan Tourolle <duncan@tourolle.paris>
Co-committed-by: Duncan Tourolle <duncan@tourolle.paris>

.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
@@ -66,6 +66,10 @@ jobs:
     needs: test
     container:
       image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+    env:
+      ANDROID_HOME: /opt/android-sdk
+      NDK_VERSION: 27.0.11902837
+      NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
 
     steps:
       - name: Checkout repository
@@ -78,9 +82,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             src-tauri/target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-android-
 
       - name: Cache Node dependencies
         uses: actions/cache@v3
@@ -99,6 +103,15 @@ jobs:
       - name: Build frontend
         run: bun run build
 
+      - name: Ensure Android NDK
+        run: |
+          if [ ! -d "$NDK_HOME" ]; then
+            echo "NDK not found at $NDK_HOME, installing ndk;$NDK_VERSION"
+            yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$ANDROID_HOME" "ndk;$NDK_VERSION"
+          fi
+          echo "Using NDK at $NDK_HOME"
+          ls "$NDK_HOME"
+
       - name: Initialize Android project
         run: |
           cd src-tauri
@@ -109,7 +122,7 @@ jobs:
         id: build
         run: |
           mkdir -p artifacts
-          bun run tauri android build --apk true
+          bun run tauri android build --apk true --target aarch64
 
           # Find the generated APK file
           ARTIFACT=$(find src-tauri/gen/android/app/build/outputs/apk -name "*.apk" -type f -print -quit)

.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
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
-            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
-            target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-host-
+
+      - name: Cache Node dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
 
       - name: Install dependencies
         run: bun install
 
       - name: Run frontend tests
-        run: bun run test --run
+        run: |
+          bunx svelte-kit sync
+          bun run test --run
         continue-on-error: false
 
       - name: Run Rust tests
@@ -63,45 +66,32 @@ jobs:
     name: Build Linux
     runs-on: linux/amd64
     needs: test
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
-      - name: Setup Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      - name: Install system dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y \
-            libwebkit2gtk-4.1-dev \
-            build-essential \
-            curl \
-            wget \
-            file \
-            libssl-dev \
-            libgtk-3-dev \
-            libayatana-appindicator3-dev \
-            librsvg2-dev
-
       - name: Cache Rust dependencies
         uses: actions/cache@v3
         with:
           path: |
-            ~/.cargo/bin/
+            ~/.cargo/registry
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
-            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
-            target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-
+            ${{ runner.os }}-cargo-host-
+
+      - name: Cache Node dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
 
       - name: Install dependencies
         run: bun install
@@ -135,59 +125,40 @@ jobs:
     name: Build Android
     runs-on: linux/amd64
     needs: test
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+    env:
+      ANDROID_HOME: /opt/android-sdk
+      ANDROID_SDK_ROOT: /opt/android-sdk
+      ANDROID_NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-
-      - name: Setup Java
-        uses: actions/setup-java@v3
-        with:
-          distribution: 'temurin'
-          java-version: '17'
-
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v2
-        with:
-          api-level: 33
-
-      - name: Setup Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      - name: Add Android targets
-        run: |
-          rustup target add aarch64-linux-android
-          rustup target add armv7-linux-androideabi
-          rustup target add x86_64-linux-android
-
-      - name: Install Android NDK
-        run: |
-          sdkmanager "ndk;25.1.8937393"
-
       - name: Cache Rust dependencies
         uses: actions/cache@v3
         with:
           path: |
-            ~/.cargo/bin/
+            ~/.cargo/registry
-            ~/.cargo/registry/index/
+            ~/.cargo/git
-            ~/.cargo/registry/cache/
+            src-tauri/target
-            ~/.cargo/git/db/
-            target/
           key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
             ${{ runner.os }}-cargo-android-
 
+      - name: Cache Node dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
       - name: Install dependencies
         run: bun install
 
-      - name: Resolve Android NDK path
-        run: echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.1.8937393" >> "$GITHUB_ENV"
-
       - name: Set app version from tag
         run: |
           REF="${GITHUB_REF#refs/tags/v}"
@@ -201,8 +172,6 @@ jobs:
 
       - name: Initialize Android project
         run: bun run tauri android init
-        env:
-          ANDROID_NDK_HOME: ${{ env.ANDROID_NDK_HOME }}
 
       - name: Sync custom Android sources & gradle config
         run: ./scripts/sync-android-sources.sh
@@ -218,11 +187,7 @@ jobs:
           EOF
 
       - name: Build signed Android APK
-        run: bun run tauri android build --apk
+        run: bun run tauri android build --apk true --target aarch64
-        env:
-          ANDROID_NDK_HOME: ${{ env.ANDROID_NDK_HOME }}
-          ANDROID_SDK_ROOT: ${{ env.ANDROID_SDK_ROOT }}
-          ANDROID_HOME: ${{ env.ANDROID_SDK_ROOT }}
 
       - name: Collect & verify signed APK
         run: |
@@ -247,6 +212,8 @@ jobs:
     runs-on: linux/amd64
     needs: [build-linux, build-android]
     if: startsWith(github.ref, 'refs/tags/v')
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -273,23 +240,23 @@ jobs:
         id: release_notes
         run: |
           VERSION="${{ steps.tag_name.outputs.VERSION }}"
-          echo "## 📱 JellyTau $VERSION Release" > release_notes.md
+          echo "## JellyTau $VERSION Release" > release_notes.md
           echo "" >> release_notes.md
-          echo "### 📦 Downloads" >> release_notes.md
+          echo "### Downloads" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Linux" >> release_notes.md
           echo "- **AppImage** - Run directly on most Linux distributions" >> release_notes.md
-          echo "- **DEB** - Install via `sudo dpkg -i jellytau_*.deb` (Ubuntu/Debian)" >> release_notes.md
+          echo "- **DEB** - Install via \`sudo dpkg -i jellytau_*.deb\` (Ubuntu/Debian)" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Android" >> release_notes.md
-          echo "- **APK** - Install via `adb install jellytau-release.apk` or sideload via file manager" >> release_notes.md
+          echo "- **APK** - Install via \`adb install jellytau-release.apk\` or sideload via file manager" >> release_notes.md
           echo "- **AAB** - Upload to Google Play Console or testing platforms" >> release_notes.md
           echo "" >> release_notes.md
-          echo "### ✨ What's New" >> release_notes.md
+          echo "### What's New" >> release_notes.md
           echo "" >> release_notes.md
           echo "See [CHANGELOG.md](CHANGELOG.md) for detailed changes." >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 🔧 Installation" >> release_notes.md
+          echo "### Installation" >> release_notes.md
           echo "" >> release_notes.md
           echo "#### Linux (AppImage)" >> release_notes.md
           echo "\`\`\`bash" >> release_notes.md
@@ -307,11 +274,11 @@ jobs:
           echo "- Sideload: Download APK and install via file manager or ADB" >> release_notes.md
           echo "- Play Store: Coming soon" >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 🐛 Known Issues" >> release_notes.md
+          echo "### Known Issues" >> release_notes.md
           echo "" >> release_notes.md
           echo "See [GitHub Issues](../../issues) for reported bugs." >> release_notes.md
           echo "" >> release_notes.md
-          echo "### 📝 Requirements" >> release_notes.md
+          echo "### Requirements" >> release_notes.md
           echo "" >> release_notes.md
           echo "**Linux:**" >> release_notes.md
           echo "- 64-bit Linux system" >> release_notes.md
@@ -322,7 +289,7 @@ jobs:
           echo "- 50MB free storage" >> release_notes.md
           echo "" >> release_notes.md
           echo "---" >> release_notes.md
-          echo "Built with Tauri, SvelteKit, and Rust 🦀" >> release_notes.md
+          echo "Built with Tauri, SvelteKit, and Rust" >> release_notes.md
 
       - name: Publish Gitea release & upload assets
         env:
@@ -346,11 +313,20 @@ jobs:
             '{tag_name:$tag, name:$name, body:$body, draft:false, prerelease:$pre}')
 
           echo "📦 Creating release $VERSION on $REPO"
-          RESP=$(curl -fsS -X POST "$API/repos/$REPO/releases" \
+          # -f drops on HTTP error; capture status so an existing release (409) is handled gracefully.
+          HTTP=$(curl -sS -o resp.json -w '%{http_code}' -X POST "$API/repos/$REPO/releases" \
             -H "Authorization: token $TOKEN" \
             -H "Content-Type: application/json" \
             -d "$PAYLOAD")
-          RELEASE_ID=$(echo "$RESP" | jq -r '.id')
+          if [ "$HTTP" = "201" ]; then
+            RELEASE_ID=$(jq -r '.id' resp.json)
+          elif [ "$HTTP" = "409" ]; then
+            echo "ℹ️  Release $VERSION already exists; fetching its id to upload assets"
+            RELEASE_ID=$(curl -fsS "$API/repos/$REPO/releases/tags/$VERSION" \
+              -H "Authorization: token $TOKEN" | jq -r '.id')
+          else
+            echo "❌ Failed to create release (HTTP $HTTP):"; cat resp.json; exit 1
+          fi
           echo "Release id=$RELEASE_ID"
 
           for f in artifacts/android/* artifacts/linux/*; do

.gitea/workflows/traceability-check.yml

@@ -95,20 +95,28 @@ jobs:
           echo ""
 
           # Check each file
-          MISSING_TRACES=0
+          # Pipe into the loop instead of a here-string (<<<) so this step works
-          while IFS= read -r file; do
+          # 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
+            case "$file" in
-              continue
+              *.test.*) continue ;;
-            fi
+            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 ""

.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
@@ -50,3 +55,6 @@ logs
 
 # 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

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

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()
+        -parallel_race()
-        -has_meaningful_content()
+        -cache_with_timeout()
     }
 
     MediaRepository <|.. OnlineRepository
@@ -214,6 +216,7 @@ classDiagram
    - Returns cache result if it has meaningful content
    - Falls back to server result otherwise
    - Background cache updates planned
+   - **Connectivity feedback**: `OnlineRepository` reports the outcome of every server request to the `ConnectivityMonitor` (classified via `RepoError`). This is the source of truth for the offline/online banner — see [07-connectivity.md](07-connectivity.md). The frontend `connectivity` store is a pure reflection of the resulting events; `navigator.onLine` is only an advisory hint that triggers an immediate recheck.
 
 2. **Handle-Based Resource Management** (`repository.rs` commands):
    ```rust

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/07-connectivity.md

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

docs/architecture/README.md

@@ -15,6 +15,7 @@ JellyTau uses a client-server architecture: business logic lives in a comprehens
 - **Events + Polling hybrid**: Rust emits events the frontend listens to, and the UI also polls status on short intervals in a few hot spots (e.g. queue status in `library/+layout.svelte`, playback progress in `VideoPlayer.svelte`).
 - **Handle-Based Resources**: UUID handles for stateful Rust objects.
 - **Cache-First**: Parallel queries with intelligent fallback.
+- **Single source of truth for reachability**: Server reachability is derived from the outcome of *real repository traffic*, not a side-channel poller. The `OnlineRepository` reports each server result to the `ConnectivityMonitor` (classified via `RepoError`), which applies a time-window debounce before declaring the server offline and recovers instantly on the first success. The standalone `/System/Info/Public` probe runs *only while offline*, as a recovery detector for idle sessions.
 - **Poison-tolerant locking**: Shared `std::sync` state is accessed via the `MutexSafe`/`RwLockSafe` helpers in `utils/lock.rs`, which recover a poisoned lock instead of cascading a panic across the player.
 - **Graceful backend init**: If a native player backend (MPV/ExoPlayer) fails to initialize, the app falls back to a no-op backend and emits a `backend-init-failed` event rather than crashing.
 
@@ -79,26 +80,29 @@ flowchart TB
         Core --> Storage
         Repository --> HttpClient
         Repository --> DatabaseService
+        Repository -->|"reports server outcome<br/>(success / RepoError)"| ConnectivityMonitor
     end
 ```
 
+> The `Repository --> ConnectivityMonitor` edge is the source of truth for the offline/online banner: every server request the user actually makes updates reachability. The monitor's own polling is now an offline-only recovery probe (see [07-connectivity.md](07-connectivity.md)).
+
 ---
 
 ## Detailed Documentation
 
-Each major subsystem is documented in its own file under [docs/architecture/](docs/architecture/):
+Each major subsystem is documented in its own file in this directory:
 
 | Document | Contents |
 |----------|----------|
-| [01 - Rust Backend](docs/architecture/01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
+| [01 - Rust Backend](01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
-| [02 - Svelte Frontend](docs/architecture/02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
+| [02 - Svelte Frontend](02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
-| [03 - Data Flow](docs/architecture/03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
+| [03 - Data Flow](03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
-| [04 - Type Sync & Threading](docs/architecture/04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
+| [04 - Type Sync & Threading](04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
-| [05 - Platform Backends](docs/architecture/05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
+| [05 - Platform Backends](05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
-| [06 - Downloads & Offline](docs/architecture/06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
+| [06 - Downloads & Offline](06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
-| [07 - Connectivity](docs/architecture/07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
+| [07 - Connectivity](07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
-| [08 - Database Design](docs/architecture/08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
+| [08 - Database Design](08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
-| [09 - Security](docs/architecture/09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
+| [09 - Security](09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
 
 ---
 
@@ -187,7 +191,7 @@ src/lib/
 
 **What moved to Rust (~3,500 lines of business logic):**
 1. **HTTP Client** (338 lines) - Retry logic with exponential backoff
-2. **Connectivity Monitor** (301 lines) - Adaptive polling, event emission
+2. **Connectivity Monitor** (301 lines) - Reachability derived from real repository traffic, time-window debounce, offline-only recovery probe, event emission
 3. **Repository Pattern** (1061 lines) - Cache-first hybrid with parallel racing
 4. **Database Service** - Async wrapper preventing UI freezing
 5. **Playback Mode** (303 lines) - Local/remote transfer coordination

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/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();
 

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/android/src/main/java/com/dtourolle/jellytau/VideoOverlayManager.kt

@@ -0,0 +1,86 @@
+package com.dtourolle.jellytau
+
+import android.app.Activity
+import android.view.SurfaceView
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.dtourolle.jellytau.player.JellyTauPlayer
+
+/**
+ * Manages the video SurfaceView overlay in the Activity's view hierarchy.
+ *
+ * This class handles attaching and detaching the native ExoPlayer SurfaceView
+ * so that it renders video content behind the WebView.
+ */
+object VideoOverlayManager {
+
+    private var attachedSurfaceView: SurfaceView? = null
+
+    /**
+     * Attach the video SurfaceView to the Activity's content view.
+     *
+     * The SurfaceView is added at index 0 (bottom of z-order) so it renders
+     * behind the Tauri WebView, allowing Svelte controls to overlay on top.
+     *
+     * @param activity The Activity to attach the surface to
+     */
+    fun attachVideoSurface(activity: Activity) {
+        try {
+            // Get the SurfaceView from JellyTauPlayer
+            val player = JellyTauPlayer.getInstance()
+            val surfaceView = player.getSurfaceView()
+
+            if (surfaceView == null) {
+                android.util.Log.w("VideoOverlayManager", "No SurfaceView available to attach")
+                return
+            }
+
+            // Get the root content view
+            val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
+
+            // Remove from parent if already attached elsewhere
+            (surfaceView.parent as? ViewGroup)?.removeView(surfaceView)
+
+            // Configure layout params to fill the screen
+            val layoutParams = FrameLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT,
+                ViewGroup.LayoutParams.MATCH_PARENT
+            )
+
+            // Add to content view at index 0 (behind WebView)
+            contentView.addView(surfaceView, 0, layoutParams)
+            attachedSurfaceView = surfaceView
+
+            android.util.Log.d("VideoOverlayManager", "Video surface attached to view hierarchy")
+        } catch (e: Exception) {
+            android.util.Log.e("VideoOverlayManager", "Failed to attach video surface", e)
+        }
+    }
+
+    /**
+     * Detach the video SurfaceView from the Activity's view hierarchy.
+     *
+     * @param activity The Activity to detach the surface from
+     */
+    fun detachVideoSurface(activity: Activity) {
+        try {
+            attachedSurfaceView?.let { surfaceView ->
+                val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
+                contentView.removeView(surfaceView)
+                attachedSurfaceView = null
+                android.util.Log.d("VideoOverlayManager", "Video surface detached from view hierarchy")
+            }
+        } catch (e: Exception) {
+            android.util.Log.e("VideoOverlayManager", "Failed to detach video surface", e)
+        }
+    }
+
+    /**
+     * Check if a video surface is currently attached.
+     *
+     * @return true if a surface is attached, false otherwise
+     */
+    fun isVideoSurfaceAttached(): Boolean {
+        return attachedSurfaceView != null
+    }
+}

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,

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/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/mod.rs

@@ -22,7 +22,7 @@ pub struct DownloadManagerWrapper(pub Mutex<DownloadManager>);
 
 /// Download statistics computed server-side
 #[allow(dead_code)]
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DownloadStats {
     pub total: usize,
@@ -35,7 +35,7 @@ pub struct DownloadStats {
 
 /// Enhanced response with pre-computed stats
 #[allow(dead_code)]
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DownloadsResponse {
     pub downloads: Vec<DownloadInfo>,
@@ -52,22 +52,66 @@ fn sanitize_filename(name: &str) -> String {
         .collect()
 }
 
+/// Request payload for download_item_and_start (bundled to stay within specta's
+/// 10-argument command limit).
+#[derive(Debug, specta::Type, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DownloadItemAndStartRequest {
+    pub item_id: String,
+    pub user_id: String,
+    pub stream_url: String,
+    pub target_dir: String,
+    pub item_name: Option<String>,
+    pub artist_name: Option<String>,
+    pub album_name: Option<String>,
+}
+
+/// Request payload for download_item.
+#[derive(Debug, specta::Type, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DownloadItemRequest {
+    pub item_id: String,
+    pub user_id: String,
+    pub file_path: String,
+    pub mime_type: Option<String>,
+    pub priority: Option<i32>,
+    pub item_name: Option<String>,
+    pub artist_name: Option<String>,
+    pub album_name: Option<String>,
+    pub expected_size: Option<i64>,
+}
+
+/// Request payload for download_video.
+#[derive(Debug, specta::Type, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DownloadVideoRequest {
+    pub item_id: String,
+    pub user_id: String,
+    pub file_path: String,
+    pub mime_type: Option<String>,
+    pub priority: Option<i32>,
+    pub item_name: Option<String>,
+    pub quality_preset: Option<String>,
+    pub series_name: Option<String>,
+    pub season_name: Option<String>,
+    pub episode_number: Option<i32>,
+    pub season_number: Option<i32>,
+}
+
 /// Queue and start a download in a single atomic operation
 /// This simplifies the frontend flow by combining multiple steps
 #[tauri::command]
+#[specta::specta]
 pub async fn download_item_and_start(
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
     download_manager: State<'_, DownloadManagerWrapper>,
     app: tauri::AppHandle,
-    item_id: String,
+    request: DownloadItemAndStartRequest,
-    user_id: String,
-    stream_url: String,
-    target_dir: String,
-    item_name: Option<String>,
-    artist_name: Option<String>,
-    album_name: Option<String>,
 ) -> Result<i64, String> {
+    let DownloadItemAndStartRequest {
+        item_id, user_id, stream_url, target_dir, item_name, artist_name, album_name,
+    } = request;
     // Sanitize filename
     let safe_name = sanitize_filename(item_name.as_deref().unwrap_or(&item_id));
     let file_path = format!("downloads/{}.mp3", safe_name);
@@ -76,15 +120,17 @@ pub async fn download_item_and_start(
     let download_id = download_item(
         db.clone(),
         smart_cache.clone(),
-        item_id,
+        DownloadItemRequest {
-        user_id,
+            item_id,
-        file_path,
+            user_id,
-        None, // mime_type
+            file_path,
-        None, // priority
+            mime_type: None,
-        item_name,
+            priority: None,
-        artist_name,
+            item_name,
-        album_name,
+            artist_name,
-        None, // expected_size
+            album_name,
+            expected_size: None,
+        },
     ).await?;
 
     // Start the download immediately
@@ -102,19 +148,15 @@ pub async fn download_item_and_start(
 
 /// Queue a media item for download
 #[tauri::command]
+#[specta::specta]
 pub async fn download_item(
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
-    item_id: String,
+    request: DownloadItemRequest,
-    user_id: String,
-    file_path: String,
-    mime_type: Option<String>,
-    priority: Option<i32>,
-    item_name: Option<String>,
-    artist_name: Option<String>,
-    album_name: Option<String>,
-    expected_size: Option<i64>,
 ) -> Result<i64, String> {
+    let DownloadItemRequest {
+        item_id, user_id, file_path, mime_type, priority, item_name, artist_name, album_name, expected_size,
+    } = request;
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
         Arc::new(database.service())
@@ -196,6 +238,7 @@ pub async fn download_item(
 
 /// Queue an entire album for download
 #[tauri::command]
+#[specta::specta]
 pub async fn download_album(
     db: State<'_, DatabaseWrapper>,
     album_id: String,
@@ -267,21 +310,15 @@ pub async fn download_album(
 
 /// Queue a video item (movie or episode) for download with quality preset
 #[tauri::command]
+#[specta::specta]
 pub async fn download_video(
     db: State<'_, DatabaseWrapper>,
-    item_id: String,
+    request: DownloadVideoRequest,
-    user_id: String,
-    file_path: String,
-    mime_type: Option<String>,
-    priority: Option<i32>,
-    item_name: Option<String>,
-    quality_preset: Option<String>,
-    // Video-specific metadata
-    series_name: Option<String>,
-    season_name: Option<String>,
-    episode_number: Option<i32>,
-    season_number: Option<i32>,
 ) -> Result<i64, String> {
+    let DownloadVideoRequest {
+        item_id, user_id, file_path, mime_type, priority, item_name, quality_preset,
+        series_name, season_name, episode_number, season_number,
+    } = request;
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
         Arc::new(database.service())
@@ -338,6 +375,7 @@ pub async fn download_video(
 
 /// Queue all episodes of a series for download
 #[tauri::command]
+#[specta::specta]
 pub async fn download_series(
     db: State<'_, DatabaseWrapper>,
     series_id: String,
@@ -438,6 +476,7 @@ pub async fn download_series(
 
 /// Queue all episodes of a specific season for download
 #[tauri::command]
+#[specta::specta]
 pub async fn download_season(
     db: State<'_, DatabaseWrapper>,
     season_id: String,
@@ -558,6 +597,7 @@ fn compute_download_stats(downloads: &[DownloadInfo]) -> DownloadStats {
 
 /// Get all downloads for a user, optionally filtered by status
 #[tauri::command]
+#[specta::specta]
 pub async fn get_downloads(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -632,6 +672,7 @@ pub async fn get_downloads(
 
 /// Pause a download
 #[tauri::command]
+#[specta::specta]
 pub async fn pause_download(db: State<'_, DatabaseWrapper>, download_id: i64) -> Result<(), String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -649,6 +690,7 @@ pub async fn pause_download(db: State<'_, DatabaseWrapper>, download_id: i64) ->
 
 /// Resume a paused download
 #[tauri::command]
+#[specta::specta]
 pub async fn resume_download(db: State<'_, DatabaseWrapper>, download_id: i64) -> Result<(), String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -666,6 +708,7 @@ pub async fn resume_download(db: State<'_, DatabaseWrapper>, download_id: i64) -
 
 /// Cancel a download
 #[tauri::command]
+#[specta::specta]
 pub async fn cancel_download(
     db: State<'_, DatabaseWrapper>,
     download_manager: State<'_, DownloadManagerWrapper>,
@@ -714,6 +757,7 @@ pub async fn cancel_download(
 
 /// Mark a download as completed
 #[tauri::command]
+#[specta::specta]
 pub async fn mark_download_completed(
     db: State<'_, DatabaseWrapper>,
     download_id: i64,
@@ -742,6 +786,7 @@ pub async fn mark_download_completed(
 
 /// Mark a download as failed
 #[tauri::command]
+#[specta::specta]
 pub async fn mark_download_failed(
     db: State<'_, DatabaseWrapper>,
     download_id: i64,
@@ -764,6 +809,7 @@ pub async fn mark_download_failed(
 /// Start downloading a file immediately
 /// This command actually downloads the file using the worker
 #[tauri::command]
+#[specta::specta]
 pub async fn start_download(
     db: State<'_, DatabaseWrapper>,
     download_manager: State<'_, DownloadManagerWrapper>,
@@ -981,6 +1027,7 @@ pub async fn start_download(
 
 /// Delete a completed download
 #[tauri::command]
+#[specta::specta]
 pub async fn delete_download(db: State<'_, DatabaseWrapper>, download_id: i64) -> Result<(), String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -1048,7 +1095,7 @@ fn map_download_row(row: &rusqlite::Row) -> rusqlite::Result<DownloadInfo> {
 }
 
 /// Storage statistics for downloads
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 pub struct StorageStats {
     pub total_bytes: i64,
     pub total_items: i64,
@@ -1056,7 +1103,7 @@ pub struct StorageStats {
 }
 
 /// Storage info for a single album
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 pub struct AlbumStorageInfo {
     pub album_id: String,
     pub album_name: String,
@@ -1067,6 +1114,7 @@ pub struct AlbumStorageInfo {
 
 /// Get storage statistics for downloads
 #[tauri::command]
+#[specta::specta]
 pub async fn get_download_storage_stats(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -1127,6 +1175,7 @@ pub async fn get_download_storage_stats(
 
 /// Delete all downloads for a user
 #[tauri::command]
+#[specta::specta]
 pub async fn delete_all_downloads(db: State<'_, DatabaseWrapper>, user_id: String) -> Result<i64, String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -1166,6 +1215,7 @@ pub async fn delete_all_downloads(db: State<'_, DatabaseWrapper>, user_id: Strin
 
 /// Clear all stale pending/failed/paused downloads
 #[tauri::command]
+#[specta::specta]
 pub async fn clear_stale_downloads(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -1208,6 +1258,7 @@ pub async fn clear_stale_downloads(
 
 /// Delete all downloads for a specific album
 #[tauri::command]
+#[specta::specta]
 pub async fn delete_album_downloads(
     db: State<'_, DatabaseWrapper>,
     album_id: String,
@@ -1252,7 +1303,7 @@ pub async fn delete_album_downloads(
 }
 
 /// Download manager statistics
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 pub struct DownloadManagerStats {
     pub max_concurrent: usize,
     pub active_count: usize,
@@ -1261,6 +1312,7 @@ pub struct DownloadManagerStats {
 
 /// Get download manager statistics
 #[tauri::command]
+#[specta::specta]
 pub async fn get_download_manager_stats(
     download_manager: State<'_, DownloadManagerWrapper>,
 ) -> Result<DownloadManagerStats, String> {
@@ -1278,6 +1330,7 @@ pub async fn get_download_manager_stats(
 
 /// Set the maximum concurrent downloads
 #[tauri::command]
+#[specta::specta]
 pub async fn set_max_concurrent_downloads(
     download_manager: State<'_, DownloadManagerWrapper>,
     max: usize,

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

@@ -8,6 +8,7 @@ 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())?;
@@ -25,6 +26,7 @@ pub async fn pin_item(db: State<'_, DatabaseWrapper>, item_id: String) -> Result
 
 /// 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())?;
@@ -42,6 +44,7 @@ pub async fn unpin_item(db: State<'_, DatabaseWrapper>, item_id: String) -> Resu
 
 /// 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())?;

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

@@ -8,7 +8,7 @@ use crate::commands::{DatabaseWrapper, SmartCacheWrapper};
 use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 /// SmartCache statistics
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 pub struct SmartCacheStats {
     pub total_size: u64,
     pub storage_limit: u64,
@@ -19,6 +19,7 @@ pub struct SmartCacheStats {
 
 /// Get SmartCache statistics
 #[tauri::command]
+#[specta::specta]
 pub async fn get_smart_cache_stats(
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
@@ -67,6 +68,7 @@ pub async fn get_smart_cache_stats(
 
 /// Update SmartCache configuration
 #[tauri::command]
+#[specta::specta]
 pub async fn update_smart_cache_config(
     smart_cache: State<'_, SmartCacheWrapper>,
     config: crate::download::cache::CacheConfig,
@@ -79,6 +81,7 @@ pub async fn update_smart_cache_config(
 
 /// Get SmartCache configuration
 #[tauri::command]
+#[specta::specta]
 pub async fn get_smart_cache_config(
     smart_cache: State<'_, SmartCacheWrapper>,
 ) -> Result<crate::download::cache::CacheConfig, String> {
@@ -89,7 +92,7 @@ pub async fn get_smart_cache_config(
 }
 
 /// Album recommendation info
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 pub struct AlbumRecommendation {
     pub album_id: String,
     pub album_name: String,
@@ -99,7 +102,7 @@ pub struct AlbumRecommendation {
 }
 
 /// Album affinity status info
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AlbumAffinityStatus {
     pub album_id: String,
@@ -110,6 +113,7 @@ pub struct AlbumAffinityStatus {
 
 /// Get album recommendations based on play history
 #[tauri::command]
+#[specta::specta]
 pub async fn get_album_recommendations(
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
@@ -189,6 +193,7 @@ pub async fn get_album_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> {

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,6 +37,7 @@ 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,
@@ -51,6 +55,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 +74,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 +125,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>,

src-tauri/src/commands/player/mod.rs

@@ -56,7 +56,7 @@ pub struct MediaSessionManagerWrapper(pub Mutex<MediaSessionManager>);
 pub struct VideoSettingsWrapper(pub Mutex<VideoSettings>);
 
 /// Response for player state queries
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlayerStatus {
     pub state: PlayerState,
@@ -82,7 +82,7 @@ pub struct PlayerStatus {
 
 /// Lightweight media item for merged playback state
 /// Converts from both local MediaItem and remote NowPlayingItem
-#[derive(Debug, Serialize, Clone)]
+#[derive(specta::Type, Debug, Serialize, Clone)]
 #[serde(rename_all = "camelCase")]
 pub struct MergedMediaItem {
     pub id: String,
@@ -134,7 +134,7 @@ impl From<&crate::jellyfin::client::NowPlayingItem> for MergedMediaItem {
 }
 
 /// Response for queue queries
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct QueueStatus {
     pub items: Vec<MediaItem>,
@@ -146,7 +146,7 @@ pub struct QueueStatus {
 }
 
 /// Backend type for video playback
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum VideoBackend {
     /// Native backend (ExoPlayer on Android, libmpv on Linux)
@@ -159,7 +159,7 @@ pub enum VideoBackend {
 ///
 /// Simplified to video playback only. Audio playback uses player_play_tracks
 /// to avoid Tauri Android serialization issues with complex objects.
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlayItemRequest {
     pub id: String,
@@ -172,7 +172,7 @@ pub struct PlayItemRequest {
 }
 
 /// Queue context for remote transfer - what type of queue is this?
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum PlayQueueContext {
     /// Playing from a specific album
@@ -194,7 +194,7 @@ pub enum PlayQueueContext {
 }
 
 /// Request to play a queue of items
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlayQueueRequest {
     pub items: Vec<PlayItemRequest>,
@@ -207,7 +207,7 @@ pub struct PlayQueueRequest {
 }
 
 /// Request to play a track from an album (backend fetches all tracks)
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlayAlbumTrackRequest {
     pub album_id: String,
@@ -217,7 +217,7 @@ pub struct PlayAlbumTrackRequest {
 }
 
 /// Request to play tracks by ID (backend fetches metadata)
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlayTracksRequest {
     pub track_ids: Vec<String>,
@@ -227,7 +227,7 @@ pub struct PlayTracksRequest {
 }
 
 /// Context information for track playback
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum PlayTracksContext {
     Playlist {
@@ -249,7 +249,7 @@ pub enum PlayTracksContext {
 }
 
 /// Response for video seek operations
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(tag = "strategy", rename_all = "camelCase")]
 pub enum VideoSeekResponse {
     /// Use native seeking (HLS or direct stream)
@@ -267,7 +267,7 @@ pub enum VideoSeekResponse {
 }
 
 /// Response for audio track switching operations
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(tag = "strategy", rename_all = "camelCase")]
 pub enum AudioTrackSwitchResponse {
     /// Native backend handled it (Android ExoPlayer)
@@ -384,6 +384,7 @@ pub(super) async fn check_for_local_download(
 /// @req: UR-005 - Control media playback (play operation)
 /// @req: DR-009 - Audio player UI
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play_item(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -410,9 +411,22 @@ pub async fn player_play_item(
     }
 
     let controller = player.0.lock().await;
+    // On Linux, video plays in the WebKitGTK HTML5 <video> element (see
+    // get_player_status -> use_html5_element). The MPV backend has no embedded
+    // window, so loading the stream into it would only start a redundant decode
+    // (and the frontend would immediately stop it). Only load into the native
+    // backend on platforms that actually render video through it (e.g. Android).
+    #[cfg(not(target_os = "linux"))]
     controller
         .play_item(media_item)
         .map_err(|e| e.to_string())?;
+    #[cfg(target_os = "linux")]
+    {
+        // Keep the queue in sync for UI/remote-transfer without starting MPV.
+        controller
+            .set_current_item(media_item)
+            .map_err(|e| e.to_string())?;
+    }
 
     // Emit queue changed event
     controller.emit_queue_changed();
@@ -435,6 +449,7 @@ pub async fn player_play_item(
 /// @req: UR-015 - View and manage current audio queue
 /// @req: DR-005 - Queue manager with shuffle, repeat, history
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play_queue(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -511,6 +526,7 @@ pub async fn player_play_queue(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -538,6 +554,7 @@ pub async fn player_play(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_pause(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -565,6 +582,7 @@ pub async fn player_pause(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_toggle(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -592,6 +610,7 @@ pub async fn player_toggle(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_stop(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -651,6 +670,7 @@ pub async fn player_stop(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_next(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -703,6 +723,7 @@ pub async fn player_next(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_previous(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -753,6 +774,7 @@ pub async fn player_previous(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_seek(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -792,6 +814,7 @@ pub async fn player_seek(
 /// For native (non-HTML5) backends, this command handles the entire stream reload
 /// internally. For HTML5 backends, it returns the new URL for the frontend to handle.
 #[tauri::command]
+#[specta::specta]
 pub async fn player_seek_video(
     player: State<'_, PlayerStateWrapper>,
     repository_manager: State<'_, super::repository::RepositoryManagerWrapper>,
@@ -929,6 +952,7 @@ pub async fn player_seek_video(
 /// Switch audio track - handles both HTML5 (stream reload) and native (direct switch)
 /// Note: Frontend should handle saving series preferences after this command succeeds
 #[tauri::command]
+#[specta::specta]
 pub async fn player_switch_audio_track(
     player: State<'_, PlayerStateWrapper>,
     repository_manager: State<'_, super::repository::RepositoryManagerWrapper>,
@@ -984,6 +1008,7 @@ pub async fn player_switch_audio_track(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_audio_track(
     player: State<'_, PlayerStateWrapper>,
     stream_index: i32,
@@ -994,6 +1019,7 @@ pub async fn player_set_audio_track(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_subtitle_track(
     player: State<'_, PlayerStateWrapper>,
     stream_index: Option<i32>,
@@ -1004,6 +1030,7 @@ pub async fn player_set_subtitle_track(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_volume(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -1034,6 +1061,7 @@ pub async fn player_set_volume(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_toggle_mute(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -1062,6 +1090,7 @@ pub async fn player_toggle_mute(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_toggle_shuffle(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<QueueStatus, String> {
@@ -1072,6 +1101,7 @@ pub async fn player_toggle_shuffle(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_cycle_repeat(player: State<'_, PlayerStateWrapper>) -> Result<QueueStatus, String> {
     let controller = player.0.lock().await;
     controller.cycle_repeat();
@@ -1080,6 +1110,7 @@ pub async fn player_cycle_repeat(player: State<'_, PlayerStateWrapper>) -> Resul
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_status(
     player: State<'_, PlayerStateWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
@@ -1165,6 +1196,7 @@ pub async fn player_get_status(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_queue(player: State<'_, PlayerStateWrapper>) -> Result<QueueStatus, String> {
     let controller = player.0.lock().await;
     Ok(get_queue_status(&controller))
@@ -1216,6 +1248,7 @@ pub(super) fn get_queue_status(controller: &PlayerController) -> QueueStatus {
 
 /// Play a track from an album - backend fetches all album tracks and builds queue
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play_album_track(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -1383,6 +1416,7 @@ pub async fn player_play_album_track(
 
 /// Play tracks by ID - backend fetches all metadata
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play_tracks(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
@@ -1521,7 +1555,7 @@ pub async fn player_play_tracks(
 }
 
 /// Response for preload operation
-#[derive(Debug, Serialize)]
+#[derive(specta::Type, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PreloadResult {
     /// Number of tracks queued for preload
@@ -1535,6 +1569,7 @@ pub struct PreloadResult {
 /// Preload upcoming tracks from the queue
 /// This queues background downloads for the next N tracks that aren't already downloaded
 #[tauri::command]
+#[specta::specta]
 pub async fn player_preload_upcoming(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -1671,6 +1706,7 @@ fn sanitize_filename(name: &str) -> String {
 
 /// Update SmartCache configuration
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_cache_config(
     smart_cache: State<'_, SmartCacheWrapper>,
     config: CacheConfig,
@@ -1682,6 +1718,7 @@ pub async fn player_set_cache_config(
 
 /// Get current SmartCache configuration
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_cache_config(
     smart_cache: State<'_, SmartCacheWrapper>,
 ) -> Result<CacheConfig, String> {
@@ -1691,6 +1728,7 @@ pub async fn player_get_cache_config(
 
 /// Configure Jellyfin API client for automatic playback reporting
 #[tauri::command]
+#[specta::specta]
 pub async fn player_configure_jellyfin(
     player: State<'_, PlayerStateWrapper>,
     server_url: String,
@@ -1717,6 +1755,7 @@ pub async fn player_configure_jellyfin(
 
 /// Disable Jellyfin automatic playback reporting
 #[tauri::command]
+#[specta::specta]
 pub async fn player_disable_jellyfin(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<(), String> {
@@ -1757,6 +1796,7 @@ mod tests {
         // Test finding track 1 (should be index 0)
         let index1 = tracks.iter().position(|t| t.id == "track1");
         assert_eq!(index1, Some(0), "Track 1 should be at index 0");
+        assert_eq!(tracks[0].name, "Song 1", "Track at index 0 should carry its name");
 
         // Test finding track 3 (should be index 2)
         let index3 = tracks.iter().position(|t| t.id == "track3");
@@ -1830,6 +1870,7 @@ mod tests {
 
         // Verify all tracks are in correct order
         assert_eq!(tracks[0].id, "id1");
+        assert_eq!(tracks[0].name, "Track 1", "Sorted track should retain its name");
         assert_eq!(tracks[1].id, "id2");
         assert_eq!(tracks[2].id, "id3");
         assert_eq!(tracks[3].id, "id4");

src-tauri/src/commands/player/queue.rs

@@ -16,7 +16,7 @@ use crate::repository::types::{ImageOptions, ImageType};
 use crate::repository::MediaRepository;
 
 /// Request to add items to queue
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AddToQueueRequest {
     pub items: Vec<PlayItemRequest>,
@@ -24,7 +24,7 @@ pub struct AddToQueueRequest {
 }
 
 /// Request to add a track by ID - backend fetches metadata
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AddTrackByIdRequest {
     pub track_id: String,
@@ -32,7 +32,7 @@ pub struct AddTrackByIdRequest {
 }
 
 /// Request to add multiple tracks by IDs - backend fetches metadata
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AddTracksByIdsRequest {
     pub track_ids: Vec<String>,
@@ -40,6 +40,7 @@ pub struct AddTracksByIdsRequest {
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_add_to_queue(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -81,6 +82,7 @@ pub async fn player_add_to_queue(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_remove_from_queue(
     player: State<'_, PlayerStateWrapper>,
     index: usize,
@@ -107,6 +109,7 @@ pub async fn player_remove_from_queue(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_move_in_queue(
     player: State<'_, PlayerStateWrapper>,
     from_index: usize,
@@ -137,6 +140,7 @@ pub async fn player_move_in_queue(
 
 /// Add a track to queue by ID - backend fetches metadata and constructs URLs
 #[tauri::command]
+#[specta::specta]
 pub async fn player_add_track_by_id(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -236,6 +240,7 @@ pub async fn player_add_track_by_id(
 
 /// Add multiple tracks to queue by IDs - backend fetches metadata and constructs URLs
 #[tauri::command]
+#[specta::specta]
 pub async fn player_add_tracks_by_ids(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -339,6 +344,7 @@ pub async fn player_add_tracks_by_ids(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_skip_to(
     player: State<'_, PlayerStateWrapper>,
     index: usize,

src-tauri/src/commands/player/remote.rs

@@ -9,6 +9,7 @@ use super::PlayerStateWrapper;
 
 /// Play items on a remote Jellyfin session (casting)
 #[tauri::command]
+#[specta::specta]
 pub async fn remote_play_on_session(
     player: State<'_, PlayerStateWrapper>,
     session_id: String,
@@ -36,6 +37,7 @@ pub async fn remote_play_on_session(
 
 /// Send a playback command to a remote session
 #[tauri::command]
+#[specta::specta]
 pub async fn remote_send_command(
     player: State<'_, PlayerStateWrapper>,
     session_id: String,
@@ -59,6 +61,7 @@ pub async fn remote_send_command(
 
 /// Seek on a remote session
 #[tauri::command]
+#[specta::specta]
 pub async fn remote_session_seek(
     player: State<'_, PlayerStateWrapper>,
     session_id: String,
@@ -82,6 +85,7 @@ pub async fn remote_session_seek(
 
 /// Set volume on a remote session
 #[tauri::command]
+#[specta::specta]
 pub async fn remote_session_set_volume(
     player: State<'_, PlayerStateWrapper>,
     session_id: String,
@@ -105,6 +109,7 @@ pub async fn remote_session_set_volume(
 
 /// Toggle mute on a remote session
 #[tauri::command]
+#[specta::specta]
 pub async fn remote_session_toggle_mute(
     player: State<'_, PlayerStateWrapper>,
     session_id: String,

src-tauri/src/commands/player/session.rs

@@ -10,6 +10,7 @@ use crate::player::PlayerStatusEvent;
 
 /// Get the current media session state
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_session(
     session: State<'_, MediaSessionManagerWrapper>,
 ) -> Result<crate::player::session::MediaSessionType, String> {
@@ -19,6 +20,7 @@ pub async fn player_get_session(
 
 /// Dismiss the current media session (returns to Idle)
 #[tauri::command]
+#[specta::specta]
 pub async fn player_dismiss_session(
     session: State<'_, MediaSessionManagerWrapper>,
     player: State<'_, PlayerStateWrapper>,

src-tauri/src/commands/player/settings.rs

@@ -7,6 +7,7 @@ use crate::player::AutoplaySettings;
 use crate::settings::{AudioSettings, VideoSettings};
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_audio_settings(
     player: State<'_, PlayerStateWrapper>,
     settings: AudioSettings,
@@ -19,6 +20,7 @@ pub async fn player_set_audio_settings(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_audio_settings(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<AudioSettings, String> {
@@ -27,6 +29,7 @@ pub async fn player_get_audio_settings(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_video_settings(
     video_settings: State<'_, VideoSettingsWrapper>,
     player: State<'_, PlayerStateWrapper>,
@@ -50,6 +53,7 @@ pub async fn player_set_video_settings(
 }
 
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_video_settings(
     video_settings: State<'_, VideoSettingsWrapper>,
 ) -> Result<VideoSettings, String> {

src-tauri/src/commands/player/timers.rs

@@ -17,6 +17,7 @@ use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 /// Set sleep timer mode
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_sleep_timer(
     player: State<'_, PlayerStateWrapper>,
     mode: SleepTimerMode,
@@ -28,6 +29,7 @@ pub async fn player_set_sleep_timer(
 
 /// Cancel sleep timer
 #[tauri::command]
+#[specta::specta]
 pub async fn player_cancel_sleep_timer(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<SleepTimerState, String> {
@@ -38,6 +40,7 @@ pub async fn player_cancel_sleep_timer(
 
 /// Get current sleep timer state
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_sleep_timer(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<SleepTimerState, String> {
@@ -49,6 +52,7 @@ pub async fn player_get_sleep_timer(
 
 /// Get autoplay settings
 #[tauri::command]
+#[specta::specta]
 pub async fn player_get_autoplay_settings(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<AutoplaySettings, String> {
@@ -58,6 +62,7 @@ pub async fn player_get_autoplay_settings(
 
 /// Set autoplay settings and persist to database
 #[tauri::command]
+#[specta::specta]
 pub async fn player_set_autoplay_settings(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -101,6 +106,7 @@ pub async fn player_set_autoplay_settings(
 
 /// Cancel active autoplay countdown
 #[tauri::command]
+#[specta::specta]
 pub async fn player_cancel_autoplay_countdown(
     player: State<'_, PlayerStateWrapper>,
 ) -> Result<(), String> {
@@ -111,6 +117,7 @@ pub async fn player_cancel_autoplay_countdown(
 
 /// Play next episode (user confirmed from popup)
 #[tauri::command]
+#[specta::specta]
 pub async fn player_play_next_episode(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
@@ -131,6 +138,7 @@ pub async fn player_play_next_episode(
 /// - Frontend when audio track ends via backend event - no itemId/repositoryHandle needed
 /// - Android JNI callback also triggers this logic directly
 #[tauri::command]
+#[specta::specta]
 pub async fn player_on_playback_ended(
     player: State<'_, PlayerStateWrapper>,
     repository_manager: State<'_, crate::commands::repository::RepositoryManagerWrapper>,

src-tauri/src/commands/playlist.rs

@@ -11,6 +11,7 @@ use super::repository::RepositoryManagerWrapper;
 
 /// Create a new playlist
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_create(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -27,6 +28,7 @@ pub async fn playlist_create(
 
 /// Delete a playlist
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_delete(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -41,6 +43,7 @@ pub async fn playlist_delete(
 
 /// Rename a playlist
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_rename(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -56,6 +59,7 @@ pub async fn playlist_rename(
 
 /// Get playlist items with PlaylistItemId
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_get_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -70,6 +74,7 @@ pub async fn playlist_get_items(
 
 /// Add items to a playlist
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_add_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -85,6 +90,7 @@ pub async fn playlist_add_items(
 
 /// Remove items from a playlist (uses PlaylistItemId entry IDs, NOT media item IDs)
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_remove_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -100,6 +106,7 @@ pub async fn playlist_remove_items(
 
 /// Move a playlist item to a new position
 #[tauri::command]
+#[specta::specta]
 pub async fn playlist_move_item(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,

src-tauri/src/commands/repository.rs

@@ -48,9 +48,11 @@ pub struct RepositoryManagerWrapper(pub RepositoryManager);
 /// Create a new repository instance
 /// Returns a handle (UUID) for accessing the repository
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_create(
     manager: State<'_, RepositoryManagerWrapper>,
     db: State<'_, crate::commands::storage::DatabaseWrapper>,
+    connectivity: State<'_, crate::commands::connectivity::ConnectivityMonitorWrapper>,
     server_url: String,
     user_id: String,
     access_token: String,
@@ -67,9 +69,18 @@ pub async fn repository_create(
     })?;
     debug!("[REPO] HTTP client created successfully");
 
-    // Create online repository
+    // Grab a connectivity reporter so the online repository's server outcomes
+    // drive the reachability state the UI observes (source of truth for the
+    // offline/online banner). See docs/architecture/07-connectivity.md.
+    let connectivity_reporter = {
+        let monitor = connectivity.0.lock().await;
+        monitor.reporter()
+    };
+
+    // Create online repository wired to connectivity reporting
     debug!("[REPO] Creating online repository...");
-    let online = OnlineRepository::new(Arc::new(http_client), server_url, user_id.clone(), access_token);
+    let online = OnlineRepository::new(Arc::new(http_client), server_url, user_id.clone(), access_token)
+        .with_connectivity(connectivity_reporter);
     debug!("[REPO] Online repository created");
 
     // Create offline repository with async-safe database service
@@ -108,6 +119,7 @@ pub async fn repository_create(
 
 /// Destroy a repository instance
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_destroy(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -118,6 +130,7 @@ pub async fn repository_destroy(
 
 /// Get libraries
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_libraries(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -138,6 +151,7 @@ pub async fn repository_get_libraries(
 
 /// Get items in a container (library, folder, album, etc.)
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -152,6 +166,7 @@ pub async fn repository_get_items(
 
 /// Get a single item by ID
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_item(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -165,6 +180,7 @@ pub async fn repository_get_item(
 
 /// Get latest items in a library
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_latest_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -179,6 +195,7 @@ pub async fn repository_get_latest_items(
 
 /// Get resume items (continue watching/listening)
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_resume_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -201,6 +218,7 @@ pub async fn repository_get_resume_items(
 
 /// Get next up episodes
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_next_up_episodes(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -215,6 +233,7 @@ pub async fn repository_get_next_up_episodes(
 
 /// Get recently played audio
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_recently_played_audio(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -228,6 +247,7 @@ pub async fn repository_get_recently_played_audio(
 
 /// Get resume movies
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_resume_movies(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -241,6 +261,7 @@ pub async fn repository_get_resume_movies(
 
 /// Get genres for a library
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_genres(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -254,6 +275,7 @@ pub async fn repository_get_genres(
 
 /// Search for items
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_search(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -268,6 +290,7 @@ pub async fn repository_search(
 
 /// Get playback info for an item
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_playback_info(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -281,6 +304,7 @@ pub async fn repository_get_playback_info(
 
 /// Get video stream URL with optional seeking support
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_video_stream_url(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -303,6 +327,7 @@ pub async fn repository_get_video_stream_url(
 
 /// Get audio stream URL for a track
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_audio_stream_url(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -317,6 +342,7 @@ pub async fn repository_get_audio_stream_url(
 
 /// Report playback start
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_report_playback_start(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -331,6 +357,7 @@ pub async fn repository_report_playback_start(
 
 /// Report playback progress
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_report_playback_progress(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -345,6 +372,7 @@ pub async fn repository_report_playback_progress(
 
 /// Report playback stopped
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_report_playback_stopped(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -359,6 +387,7 @@ pub async fn repository_report_playback_stopped(
 
 /// Get image URL for an item
 #[tauri::command]
+#[specta::specta]
 pub fn repository_get_image_url(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -372,6 +401,7 @@ pub fn repository_get_image_url(
 
 /// Get subtitle URL for a media item
 #[tauri::command]
+#[specta::specta]
 #[allow(dead_code)]
 pub fn repository_get_subtitle_url(
     manager: State<'_, RepositoryManagerWrapper>,
@@ -387,6 +417,7 @@ pub fn repository_get_subtitle_url(
 
 /// Get video download URL with quality preset
 #[tauri::command]
+#[specta::specta]
 #[allow(dead_code)]
 pub fn repository_get_video_download_url(
     manager: State<'_, RepositoryManagerWrapper>,
@@ -401,6 +432,7 @@ pub fn repository_get_video_download_url(
 
 /// Mark an item as favorite
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_mark_favorite(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -414,6 +446,7 @@ pub async fn repository_mark_favorite(
 
 /// Unmark an item as favorite
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_unmark_favorite(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -427,6 +460,7 @@ pub async fn repository_unmark_favorite(
 
 /// Get person details
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_person(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -440,6 +474,7 @@ pub async fn repository_get_person(
 
 /// Get items by person (actor, director, etc.)
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_items_by_person(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -454,6 +489,7 @@ pub async fn repository_get_items_by_person(
 
 /// Get similar/related items for a media item
 #[tauri::command]
+#[specta::specta]
 pub async fn repository_get_similar_items(
     manager: State<'_, RepositoryManagerWrapper>,
     handle: String,
@@ -473,16 +509,16 @@ mod tests {
     #[test]
     fn test_repository_manager_creation() {
         let manager = RepositoryManager::new();
-        // Should be able to create RepositoryManager without panicking
+        // A freshly created manager holds no repositories
-        assert_eq!(std::mem::size_of::<RepositoryManager>() > 0, true);
+        assert!(manager.get("any-handle").is_none());
     }
 
     #[test]
     fn test_repository_manager_wrapper_structure() {
         let manager = RepositoryManager::new();
         let wrapper = RepositoryManagerWrapper(manager);
-        // Verify wrapper holds the manager
+        // The wrapper exposes the underlying manager, which starts empty
-        assert_eq!(std::mem::size_of::<RepositoryManagerWrapper>() > 0, true);
+        assert!(wrapper.0.get("any-handle").is_none());
     }
 
     #[test]

src-tauri/src/commands/sessions.rs

@@ -10,6 +10,7 @@ pub struct SessionPollerWrapper(pub Arc<SessionPollerManager>);
 
 /// Set polling frequency hint based on UI state
 #[tauri::command]
+#[specta::specta]
 pub fn sessions_set_polling_hint(
     poller: State<'_, SessionPollerWrapper>,
     hint: String,
@@ -27,6 +28,7 @@ pub fn sessions_set_polling_hint(
 
 /// Manually trigger a session poll (for refresh button)
 #[tauri::command]
+#[specta::specta]
 pub async fn sessions_poll_now(
     poller: State<'_, SessionPollerWrapper>,
 ) -> Result<Vec<SessionInfo>, String> {

src-tauri/src/commands/storage/mod.rs

@@ -32,7 +32,7 @@ pub struct CredentialStoreWrapper(pub Mutex<CredentialStore>);
 pub struct ThumbnailCacheWrapper(pub Arc<ThumbnailCache>);
 
 /// Server info returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 pub struct ServerInfo {
     pub id: String,
     pub name: String,
@@ -41,7 +41,7 @@ pub struct ServerInfo {
 }
 
 /// User info returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UserInfo {
     pub id: String,
@@ -51,7 +51,7 @@ pub struct UserInfo {
 }
 
 /// Active session info (for session restoration)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ActiveSession {
     pub user_id: String,
@@ -63,7 +63,7 @@ pub struct ActiveSession {
 }
 
 /// Security status info
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SecurityStatus {
     pub using_keyring: bool,
@@ -72,6 +72,7 @@ pub struct SecurityStatus {
 
 /// Initialize the database and run migrations
 #[tauri::command]
+#[specta::specta]
 pub fn storage_init(db: State<DatabaseWrapper>) -> Result<String, String> {
     let database = db.0.lock().map_err(|e| e.to_string())?;
     Ok(database.path().to_string_lossy().to_string())
@@ -79,6 +80,7 @@ pub fn storage_init(db: State<DatabaseWrapper>) -> Result<String, String> {
 
 /// Get storage directory path (parent directory of the database file)
 #[tauri::command]
+#[specta::specta]
 pub fn storage_get_path(db: State<DatabaseWrapper>) -> Result<String, String> {
     let database = db.0.lock().map_err(|e| e.to_string())?;
     let db_path = database.path();
@@ -92,6 +94,7 @@ pub fn storage_get_path(db: State<DatabaseWrapper>) -> Result<String, String> {
 
 /// Get database file size in bytes
 #[tauri::command]
+#[specta::specta]
 pub fn storage_get_size(db: State<DatabaseWrapper>) -> Result<Option<u64>, String> {
     let database = db.0.lock().map_err(|e| e.to_string())?;
     Ok(database.file_size())
@@ -99,6 +102,7 @@ pub fn storage_get_size(db: State<DatabaseWrapper>) -> Result<Option<u64>, Strin
 
 /// Get security status (keyring vs encrypted file fallback)
 #[tauri::command]
+#[specta::specta]
 pub fn storage_get_security_status(
     creds: State<CredentialStoreWrapper>,
 ) -> Result<SecurityStatus, String> {
@@ -117,6 +121,7 @@ pub fn storage_get_security_status(
 /// Save a server connection
 /// Uses INSERT ... ON CONFLICT to avoid triggering CASCADE DELETE on users
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_server(
     db: State<'_, DatabaseWrapper>,
     id: String,
@@ -154,6 +159,7 @@ pub async fn storage_save_server(
 
 /// Get all saved servers
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_servers(db: State<'_, DatabaseWrapper>) -> Result<Vec<ServerInfo>, String> {
     let db_service = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
@@ -179,6 +185,7 @@ pub async fn storage_get_servers(db: State<'_, DatabaseWrapper>) -> Result<Vec<S
 
 /// Delete a server and all associated data
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_delete_server(
     db: State<'_, DatabaseWrapper>,
     creds: State<'_, CredentialStoreWrapper>,
@@ -221,6 +228,7 @@ pub async fn storage_delete_server(
 
 /// Save a user account (token stored in secure storage, not database)
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_user(
     db: State<'_, DatabaseWrapper>,
     creds: State<'_, CredentialStoreWrapper>,
@@ -298,6 +306,7 @@ pub async fn storage_save_user(
 
 /// Get users for a server
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_users(
     db: State<'_, DatabaseWrapper>,
     server_id: String,
@@ -330,6 +339,7 @@ pub async fn storage_get_users(
 
 /// Set a user as active (and deactivate all other users globally)
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_set_active_user(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -378,6 +388,7 @@ pub async fn storage_set_active_user(
 
 /// Get the active user for a server
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_active_user(
     db: State<'_, DatabaseWrapper>,
     server_id: String,
@@ -408,6 +419,7 @@ pub async fn storage_get_active_user(
 
 /// Get the active session (user + server + token) for session restoration
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_active_session(
     db: State<'_, DatabaseWrapper>,
     creds: State<'_, CredentialStoreWrapper>,
@@ -483,6 +495,7 @@ pub async fn storage_get_active_session(
 
 /// Get user's access token from secure storage
 #[tauri::command]
+#[specta::specta]
 pub fn storage_get_access_token(
     creds: State<CredentialStoreWrapper>,
     user_id: String,
@@ -497,6 +510,7 @@ pub fn storage_get_access_token(
 
 /// Delete a user account and their token from secure storage
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_delete_user(
     db: State<'_, DatabaseWrapper>,
     creds: State<'_, CredentialStoreWrapper>,
@@ -529,7 +543,7 @@ pub async fn storage_delete_user(
 }
 
 /// Playback progress info
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlaybackProgress {
     pub item_id: String,
@@ -542,6 +556,7 @@ pub struct PlaybackProgress {
 /// Update playback progress in local database
 /// This stores the progress locally for offline access and "continue watching"
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_update_playback_progress(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -593,6 +608,7 @@ pub async fn storage_update_playback_progress(
 /// Update playback progress with context in local database
 /// This stores the progress along with playback context (container vs single)
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_update_playback_context(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -642,6 +658,7 @@ pub async fn storage_update_playback_context(
 
 /// Mark item as played in local database
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_mark_played(
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
@@ -772,6 +789,7 @@ pub async fn storage_mark_played(
 
 /// Get playback progress for an item
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_playback_progress(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -804,6 +822,7 @@ pub async fn storage_get_playback_progress(
 
 /// Mark pending sync as completed for an item
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_mark_synced(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -828,6 +847,7 @@ pub async fn storage_mark_synced(
 /// Toggle favorite status for an item in local database
 /// This updates the is_favorite field and marks it for sync to Jellyfin
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_toggle_favorite(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -873,7 +893,7 @@ pub async fn storage_toggle_favorite(
 // =============================================================================
 
 /// Cached library info returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CachedLibrary {
     pub id: String,
@@ -884,7 +904,7 @@ pub struct CachedLibrary {
 }
 
 /// Cached media item returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CachedItem {
     pub id: String,
@@ -915,6 +935,7 @@ pub struct CachedItem {
 
 /// Get cached libraries for a server
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_libraries(
     db: State<'_, DatabaseWrapper>,
     server_id: String,
@@ -977,6 +998,7 @@ fn row_to_cached_item(row: &rusqlite::Row) -> rusqlite::Result<CachedItem> {
 
 /// Get cached items with optional filtering
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_items(
     db: State<'_, DatabaseWrapper>,
     server_id: String,
@@ -1043,6 +1065,7 @@ pub async fn storage_get_items(
 
 /// Get a single cached item by ID
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_item(
     db: State<'_, DatabaseWrapper>,
     item_id: String,
@@ -1070,6 +1093,7 @@ pub async fn storage_get_item(
 
 /// Search cached items using FTS
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_search_items(
     db: State<'_, DatabaseWrapper>,
     server_id: String,
@@ -1111,6 +1135,7 @@ pub async fn storage_search_items(
 
 /// Save a library to the cache
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_library(
     db: State<'_, DatabaseWrapper>,
     id: String,
@@ -1144,6 +1169,7 @@ pub async fn storage_save_library(
 
 /// Save an item to the cache
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_item(
     db: State<'_, DatabaseWrapper>,
     item: CachedItem,
@@ -1207,6 +1233,7 @@ pub async fn storage_save_item(
 
 /// Get count of pending sync operations for a user
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_pending_sync_count(
     db: State<'_, DatabaseWrapper>,
     user_id: String,

src-tauri/src/commands/storage/people.rs

@@ -9,7 +9,7 @@ use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 
 /// Cached person info returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CachedPerson {
     pub id: String,
@@ -22,7 +22,7 @@ pub struct CachedPerson {
 }
 
 /// Item-person association for caching
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CachedItemPerson {
     pub item_id: String,
@@ -35,6 +35,7 @@ pub struct CachedItemPerson {
 
 /// Save a person to the cache
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_person(
     db: State<'_, DatabaseWrapper>,
     person: CachedPerson,
@@ -66,6 +67,7 @@ pub async fn storage_save_person(
 
 /// Get a cached person by ID
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_person(
     db: State<'_, DatabaseWrapper>,
     person_id: String,
@@ -101,6 +103,7 @@ pub async fn storage_get_person(
 
 /// Save item-person associations (batch)
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_item_people(
     db: State<'_, DatabaseWrapper>,
     associations: Vec<CachedItemPerson>,
@@ -139,6 +142,7 @@ pub async fn storage_save_item_people(
 
 /// Get people for an item (with person details joined)
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_item_people(
     db: State<'_, DatabaseWrapper>,
     item_id: String,

src-tauri/src/commands/storage/series_prefs.rs

@@ -9,7 +9,7 @@ use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 
 /// Audio track preference for a series
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SeriesAudioPreference {
     pub series_id: String,
@@ -20,6 +20,7 @@ pub struct SeriesAudioPreference {
 
 /// Save user's preferred audio track for a series
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_save_series_audio_preference(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -59,6 +60,7 @@ pub async fn storage_save_series_audio_preference(
 
 /// Get user's preferred audio track for a series
 #[tauri::command]
+#[specta::specta]
 pub async fn storage_get_series_audio_preference(
     db: State<'_, DatabaseWrapper>,
     user_id: String,

src-tauri/src/commands/storage/thumbnails.rs

@@ -15,6 +15,7 @@ use crate::thumbnail::{ThumbnailCacheStats, ThumbnailWorker};
 /// Get cached thumbnail path, returns None if not cached
 /// Also updates last_accessed timestamp for LRU tracking
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_get_cached(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -38,6 +39,7 @@ pub async fn thumbnail_get_cached(
 /// Download and save a thumbnail to cache
 /// Returns the local file path on success
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_save(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -65,6 +67,7 @@ pub async fn thumbnail_save(
 
 /// Get thumbnail cache statistics
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_get_stats(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -87,6 +90,7 @@ pub async fn thumbnail_get_stats(
 
 /// Set thumbnail cache storage limit in bytes
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_set_limit(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -102,6 +106,7 @@ pub async fn thumbnail_set_limit(
 
 /// Clear all cached thumbnails
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_clear_cache(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -116,6 +121,7 @@ pub async fn thumbnail_clear_cache(
 
 /// Delete cached thumbnails for a specific item
 #[tauri::command]
+#[specta::specta]
 pub async fn thumbnail_delete_item(
     db: State<'_, DatabaseWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,
@@ -149,7 +155,7 @@ fn image_semaphore() -> &'static Semaphore {
 }
 
 /// Request to get an image URL (with caching)
-#[derive(Debug, Deserialize)]
+#[derive(specta::Type, Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GetImageRequest {
     pub item_id: String,
@@ -165,6 +171,7 @@ pub struct GetImageRequest {
 /// Get image as base64 data URL, caching if not already cached
 /// This extends the thumbnail system to serve all images through Rust with automatic caching
 #[tauri::command]
+#[specta::specta]
 pub async fn image_get_url(
     repository_manager: State<'_, RepositoryManagerWrapper>,
     thumbnail_cache: State<'_, ThumbnailCacheWrapper>,

src-tauri/src/commands/sync.rs

@@ -12,7 +12,7 @@ use super::storage::DatabaseWrapper;
 use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 /// Sync queue item returned to frontend
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SyncQueueItem {
     pub id: i64,
@@ -28,6 +28,7 @@ pub struct SyncQueueItem {
 
 /// Queue a mutation for sync to server
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_queue_mutation(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -59,6 +60,7 @@ pub async fn sync_queue_mutation(
 
 /// Get all pending sync operations for a user
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_get_pending(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -107,6 +109,7 @@ pub async fn sync_get_pending(
 
 /// Mark a sync operation as in progress
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_mark_processing(
     db: State<'_, DatabaseWrapper>,
     id: i64,
@@ -127,6 +130,7 @@ pub async fn sync_mark_processing(
 
 /// Mark a sync operation as completed
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_mark_completed(
     db: State<'_, DatabaseWrapper>,
     id: i64,
@@ -147,6 +151,7 @@ pub async fn sync_mark_completed(
 
 /// Mark a sync operation as failed with error message
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_mark_failed(
     db: State<'_, DatabaseWrapper>,
     id: i64,
@@ -173,6 +178,7 @@ pub async fn sync_mark_failed(
 
 /// Get count of pending sync operations for a user
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_get_pending_count(
     db: State<'_, DatabaseWrapper>,
     user_id: String,
@@ -195,6 +201,7 @@ pub async fn sync_get_pending_count(
 
 /// Delete completed sync operations older than specified days
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_cleanup_completed(
     db: State<'_, DatabaseWrapper>,
     days_old: i32,
@@ -217,6 +224,7 @@ pub async fn sync_cleanup_completed(
 
 /// Delete all sync operations for a user (used during logout)
 #[tauri::command]
+#[specta::specta]
 pub async fn sync_clear_user(
     db: State<'_, DatabaseWrapper>,
     user_id: String,

src-tauri/src/connectivity/mod.rs

@@ -1,18 +1,26 @@
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tokio::sync::RwLock;
 use tauri::{AppHandle, Emitter};
 use serde::{Serialize, Deserialize};
 
 use crate::jellyfin::http_client::HttpClient;
 
-// Adaptive polling intervals (matches TypeScript)
+// Offline recovery probe interval.
-const AUTO_CHECK_INTERVAL_MS: u64 = 30000; // 30 seconds when online
+// Reachability while online is driven by real repository traffic, so there is
-const RETRY_CHECK_INTERVAL_MS: u64 = 5000;  // 5 seconds when offline
+// no online polling. While offline we probe quickly to detect the server
+// returning even when no user traffic is flowing.
+const RETRY_CHECK_INTERVAL_MS: u64 = 5000; // 5 seconds when offline
+
+// Time-window debounce for declaring the server offline.
+// A single dropped request must not trip the banner: we only flip to offline
+// once network failures have persisted continuously for this window with no
+// intervening success. Recovery (online) is instant on the first success.
+const OFFLINE_CONFIRM_WINDOW: Duration = Duration::from_secs(5);
 
 /// Connectivity status
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ConnectivityStatus {
     /// Whether the Jellyfin server is reachable
@@ -39,216 +47,121 @@ impl Default for ConnectivityStatus {
 }
 
 /// Connectivity change event emitted to frontend
-#[derive(Debug, Clone, Serialize)]
+#[derive(specta::Type, Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 struct ConnectivityChangeEvent {
     is_reachable: bool,
 }
 
-/// Connectivity monitor for tracking server reachability
+/// Shared reachability state and transition logic.
-pub struct ConnectivityMonitor {
+///
-    server_url: Arc<RwLock<Option<String>>>,
+/// This is the single place that mutates reachability and emits events. It is
-    http_client: Arc<HttpClient>,
+/// cheap to clone (all fields are `Arc`/`Option`) and is shared by:
+/// - the `ConnectivityMonitor` (commands, offline recovery probe), and
+/// - `OnlineRepository`, which reports the outcome of every server request.
+///
+/// Reachability is therefore driven by real traffic; the probe only fills the
+/// gap while offline.
+#[derive(Clone)]
+pub struct ConnectivityReporter {
     status: Arc<RwLock<ConnectivityStatus>>,
-    is_monitoring: Arc<AtomicBool>,
+    /// Timestamp of the first network failure in the current failure streak.
+    /// Used to debounce the transition to offline (see `OFFLINE_CONFIRM_WINDOW`).
+    first_failure_at: Arc<RwLock<Option<Instant>>>,
     app_handle: Option<AppHandle>,
 }
 
-impl ConnectivityMonitor {
+impl ConnectivityReporter {
-    /// Create a new connectivity monitor
+    fn new(status: Arc<RwLock<ConnectivityStatus>>, app_handle: Option<AppHandle>) -> Self {
-    pub fn new(http_client: HttpClient) -> Self {
         Self {
-            server_url: Arc::new(RwLock::new(None)),
+            status,
-            http_client: Arc::new(http_client),
+            first_failure_at: Arc::new(RwLock::new(None)),
-            status: Arc::new(RwLock::new(ConnectivityStatus::default())),
+            app_handle,
-            is_monitoring: Arc::new(AtomicBool::new(false)),
-            app_handle: None,
         }
     }
 
-    /// Set the Tauri app handle for event emission
+    /// Current reachability as seen by this reporter (shared with the monitor
-    pub fn set_app_handle(&mut self, app_handle: AppHandle) {
+    /// and the UI). Useful for callers that want to branch on connectivity.
-        self.app_handle = Some(app_handle);
+    pub async fn is_reachable(&self) -> bool {
+        self.status.read().await.is_server_reachable
     }
 
-    /// Update the server URL
+    /// Test-only: force the reporter into the offline state without going through
-    pub async fn set_server_url(&self, url: String) {
+    /// the debounce, so other modules' tests can set up an "offline" precondition.
-        log::info!("[ConnectivityMonitor] Setting server URL: {}", url);
+    #[cfg(test)]
-        let mut server_url = self.server_url.write().await;
+    pub async fn mark_unreachable_for_test(&self) {
-        *server_url = Some(url.clone());
+        self.apply_probe_result(false, Some("forced offline (test)".to_string()))
-        drop(server_url);
+            .await;
-
-        // Check new server immediately
-        log::info!("[ConnectivityMonitor] Checking reachability of new server...");
-        let is_reachable = self.check_reachability().await;
-        log::info!("[ConnectivityMonitor] New server is {}", if is_reachable { "REACHABLE" } else { "UNREACHABLE" });
     }
 
-    /// Get current connectivity status
+    /// Report that a real server request succeeded (or that the server answered
-    pub async fn get_status(&self) -> ConnectivityStatus {
+    /// at all, e.g. with 401/404/5xx). The server is up — recover instantly.
-        self.status.read().await.clone()
+    pub async fn report_success(&self) {
+        *self.first_failure_at.write().await = None;
+        self.set_reachable(true, None).await;
     }
 
-    /// Check if the Jellyfin server is reachable
+    /// Report that a real server request failed with a network-level error
-    pub async fn check_reachability(&self) -> bool {
+    /// (connection refused, timeout, DNS). Subject to the time-window debounce:
-        // Mark as checking
+    /// we only flip to offline once failures have persisted for
-        {
+    /// `OFFLINE_CONFIRM_WINDOW` with no intervening success.
-            let mut status = self.status.write().await;
+    pub async fn report_network_failure(&self, error: Option<String>) {
-            status.is_checking = true;
+        // If already offline, nothing to debounce.
+        if !self.status.read().await.is_server_reachable {
+            return;
         }
 
-        let server_url = self.server_url.read().await.clone();
+        let now = Instant::now();
-
+        let streak_start = {
-        if server_url.is_none() {
+            let mut first = self.first_failure_at.write().await;
-            log::warn!("[ConnectivityMonitor] Cannot check reachability: No server URL configured");
+            *first.get_or_insert(now)
-            let mut status = self.status.write().await;
-            status.is_server_reachable = false;
-            status.connection_error = Some("No server URL configured".to_string());
-            status.is_checking = false;
-            return false;
-        }
-
-        let url = server_url.unwrap();
-        let ping_url = format!("{}/System/Info/Public", url);
-
-        // Store previous reachability state
-        let was_reachable = {
-            let status = self.status.read().await;
-            status.is_server_reachable
         };
 
-        log::debug!("[ConnectivityMonitor] Pinging server: {}", ping_url);
+        if now.duration_since(streak_start) >= OFFLINE_CONFIRM_WINDOW {
+            log::warn!(
+                "[ConnectivityMonitor] Network failures sustained for {:?}; declaring offline",
+                OFFLINE_CONFIRM_WINDOW
+            );
+            self.set_reachable(false, error).await;
+        } else {
+            log::debug!(
+                "[ConnectivityMonitor] Network failure within debounce window; not yet offline"
+            );
+        }
+    }
 
-        // Attempt to ping the server
+    /// Apply a deliberate reachability probe result (offline recovery probe or a
-        let is_reachable = self.http_client.ping(&ping_url).await;
+    /// manual check). Unlike `report_network_failure`, a probe is an explicit
+    /// reachability test, so its result is applied immediately without debounce.
+    async fn apply_probe_result(&self, is_reachable: bool, error: Option<String>) {
+        if is_reachable {
+            *self.first_failure_at.write().await = None;
+        }
+        self.set_reachable(is_reachable, error).await;
+    }
 
-        log::debug!(
+    /// Core transition: update status and emit events only on an actual change.
-            "[ConnectivityMonitor] Ping result: {} (was: {})",
+    async fn set_reachable(&self, is_reachable: bool, error: Option<String>) {
-            if is_reachable { "SUCCESS" } else { "FAILED" },
+        let was_reachable = {
-            if was_reachable { "reachable" } else { "unreachable" }
-        );
-
-        // Update status
-        {
             let mut status = self.status.write().await;
+            let was = status.is_server_reachable;
             status.is_server_reachable = is_reachable;
             status.last_checked = Some(chrono::Utc::now().to_rfc3339());
             status.connection_error = if is_reachable {
                 None
             } else {
-                Some("Server unreachable".to_string())
+                Some(error.unwrap_or_else(|| "Server unreachable".to_string()))
             };
             status.is_checking = false;
-        }
+            was
+        };
 
-        // Emit events if reachability changed
         if is_reachable != was_reachable {
             self.emit_connectivity_change(is_reachable).await;
-        }
+            if is_reachable {
-
+                self.emit_server_reconnected().await;
-        // Emit reconnection event
-        if is_reachable && !was_reachable {
-            self.emit_server_reconnected().await;
-        }
-
-        is_reachable
-    }
-
-    /// Mark server as reachable (called after successful API call)
-    pub async fn mark_reachable(&self) {
-        let mut status = self.status.write().await;
-        let was_reachable = status.is_server_reachable;
-
-        status.is_server_reachable = true;
-        status.last_checked = Some(chrono::Utc::now().to_rfc3339());
-        status.connection_error = None;
-
-        drop(status);
-
-        if !was_reachable {
-            log::info!("[ConnectivityMonitor] Server marked as reachable (was unreachable)");
-            self.emit_connectivity_change(true).await;
-            self.emit_server_reconnected().await;
-        }
-    }
-
-    /// Mark server as unreachable (called after failed API call)
-    pub async fn mark_unreachable(&self, error: Option<String>) {
-        let mut status = self.status.write().await;
-        let was_reachable = status.is_server_reachable;
-
-        status.is_server_reachable = false;
-        status.last_checked = Some(chrono::Utc::now().to_rfc3339());
-        status.connection_error = error.or_else(|| Some("Server unreachable".to_string()));
-
-        let error_msg = status.connection_error.clone().unwrap_or_default();
-        drop(status);
-
-        if was_reachable {
-            log::warn!("[ConnectivityMonitor] Server marked as unreachable (was reachable): {}", error_msg);
-            self.emit_connectivity_change(false).await;
-        }
-    }
-
-    /// Start monitoring connectivity with adaptive polling
-    pub async fn start_monitoring(&self) {
-        if self.is_monitoring.swap(true, Ordering::SeqCst) {
-            log::info!("[ConnectivityMonitor] Already monitoring");
-            return;
-        }
-
-        log::info!("[ConnectivityMonitor] Starting connectivity monitoring");
-
-        // Perform immediate check before starting background task
-        // This ensures we get an accurate state right away instead of assuming offline
-        let is_reachable = self.check_reachability().await;
-        log::info!("[ConnectivityMonitor] Initial connectivity check: {}", if is_reachable { "ONLINE" } else { "OFFLINE" });
-
-        // Clone Arc references for the background task
-        let status = Arc::clone(&self.status);
-        let is_monitoring = Arc::clone(&self.is_monitoring);
-        let server_url = Arc::clone(&self.server_url);
-        let http_client = Arc::clone(&self.http_client);
-        let self_clone = Arc::new(ConnectivityMonitorHandle {
-            server_url,
-            http_client,
-            status,
-            app_handle: self.app_handle.clone(),
-        });
-
-        // Spawn background monitoring task
-        tokio::spawn(async move {
-            while is_monitoring.load(Ordering::SeqCst) {
-                // Determine interval based on current reachability
-                let interval_ms = {
-                    let status = self_clone.status.read().await;
-                    if status.is_server_reachable {
-                        AUTO_CHECK_INTERVAL_MS
-                    } else {
-                        RETRY_CHECK_INTERVAL_MS
-                    }
-                };
-
-                // Wait for the interval
-                tokio::time::sleep(Duration::from_millis(interval_ms)).await;
-
-                // Check if still monitoring
-                if !is_monitoring.load(Ordering::SeqCst) {
-                    break;
-                }
-
-                // Perform connectivity check
-                let _ = self_clone.check_reachability().await;
             }
-
+        }
-            log::info!("[ConnectivityMonitor] Stopped monitoring");
-        });
-    }
-
-    /// Stop monitoring connectivity
-    pub fn stop_monitoring(&self) {
-        log::info!("[ConnectivityMonitor] Stopping connectivity monitoring");
-        self.is_monitoring.store(false, Ordering::SeqCst);
     }
 
     /// Emit connectivity change event to frontend
@@ -275,87 +188,183 @@ impl ConnectivityMonitor {
     }
 }
 
-/// Handle for the background monitoring task
+/// Connectivity monitor for tracking server reachability.
-struct ConnectivityMonitorHandle {
+///
+/// Reachability is driven primarily by real repository traffic via the shared
+/// [`ConnectivityReporter`]. The monitor itself only runs an offline recovery
+/// probe (see `start_monitoring`) and serves the connectivity Tauri commands.
+pub struct ConnectivityMonitor {
     server_url: Arc<RwLock<Option<String>>>,
     http_client: Arc<HttpClient>,
-    status: Arc<RwLock<ConnectivityStatus>>,
+    reporter: ConnectivityReporter,
-    app_handle: Option<AppHandle>,
+    is_monitoring: Arc<AtomicBool>,
 }
 
-impl ConnectivityMonitorHandle {
+impl ConnectivityMonitor {
-    async fn check_reachability(&self) -> bool {
+    /// Create a new connectivity monitor
+    pub fn new(http_client: HttpClient) -> Self {
+        let status = Arc::new(RwLock::new(ConnectivityStatus::default()));
+        Self {
+            server_url: Arc::new(RwLock::new(None)),
+            http_client: Arc::new(http_client),
+            reporter: ConnectivityReporter::new(status, None),
+            is_monitoring: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// Set the Tauri app handle for event emission.
+    /// Must be called before the reporter is shared with the repository.
+    pub fn set_app_handle(&mut self, app_handle: AppHandle) {
+        self.reporter.app_handle = Some(app_handle);
+    }
+
+    /// Get a cheap, cloneable reporter so the repository can feed server
+    /// outcomes into the same reachability state the UI observes.
+    pub fn reporter(&self) -> ConnectivityReporter {
+        self.reporter.clone()
+    }
+
+    /// Update the server URL
+    pub async fn set_server_url(&self, url: String) {
+        log::info!("[ConnectivityMonitor] Setting server URL: {}", url);
+        *self.server_url.write().await = Some(url);
+
+        // Check new server immediately
+        log::info!("[ConnectivityMonitor] Checking reachability of new server...");
+        let is_reachable = self.check_reachability().await;
+        log::info!("[ConnectivityMonitor] New server is {}", if is_reachable { "REACHABLE" } else { "UNREACHABLE" });
+    }
+
+    /// Get current connectivity status
+    pub async fn get_status(&self) -> ConnectivityStatus {
+        self.reporter.status.read().await.clone()
+    }
+
+    /// Deliberately probe the server's reachability (manual check / recovery probe).
+    /// The result is applied immediately (no debounce) since this is an explicit test.
+    pub async fn check_reachability(&self) -> bool {
+        {
+            let mut status = self.reporter.status.write().await;
+            status.is_checking = true;
+        }
+
         let server_url = self.server_url.read().await.clone();
 
-        if server_url.is_none() {
+        let Some(url) = server_url else {
+            log::warn!("[ConnectivityMonitor] Cannot check reachability: No server URL configured");
+            self.reporter
+                .apply_probe_result(false, Some("No server URL configured".to_string()))
+                .await;
             return false;
-        }
-
-        let url = server_url.unwrap();
-        let ping_url = format!("{}/System/Info/Public", url);
-
-        // Store previous reachability state
-        let was_reachable = {
-            let status = self.status.read().await;
-            status.is_server_reachable
         };
 
-        // Attempt to ping the server
+        let ping_url = format!("{}/System/Info/Public", url);
+        log::debug!("[ConnectivityMonitor] Pinging server: {}", ping_url);
+
         let is_reachable = self.http_client.ping(&ping_url).await;
+        log::debug!(
+            "[ConnectivityMonitor] Ping result: {}",
+            if is_reachable { "SUCCESS" } else { "FAILED" }
+        );
 
-        // Update status
+        self.reporter.apply_probe_result(is_reachable, None).await;
-        {
-            let mut status = self.status.write().await;
-            status.is_server_reachable = is_reachable;
-            status.last_checked = Some(chrono::Utc::now().to_rfc3339());
-            status.connection_error = if is_reachable {
-                None
-            } else {
-                Some("Server unreachable".to_string())
-            };
-        }
-
-        // Emit events if reachability changed
-        if is_reachable != was_reachable {
-            self.emit_connectivity_change(is_reachable).await;
-        }
-
-        // Emit reconnection event
-        if is_reachable && !was_reachable {
-            self.emit_server_reconnected().await;
-        }
-
         is_reachable
     }
 
-    async fn emit_connectivity_change(&self, is_reachable: bool) {
+    /// Mark server as reachable (called after successful API call / login)
-        if let Some(app_handle) = &self.app_handle {
+    pub async fn mark_reachable(&self) {
-            let event = ConnectivityChangeEvent { is_reachable };
+        self.reporter.report_success().await;
-            if let Err(e) = app_handle.emit("connectivity:changed", event) {
-                log::error!("[ConnectivityMonitor] Failed to emit connectivity change event: {}", e);
-            }
-        }
     }
 
-    async fn emit_server_reconnected(&self) {
+    /// Mark server as unreachable directly.
-        if let Some(app_handle) = &self.app_handle {
+    ///
-            if let Err(e) = app_handle.emit("connectivity:reconnected", ()) {
+    /// Used by deliberate signals (e.g. a failed login/connect) where the caller
-                log::error!("[ConnectivityMonitor] Failed to emit reconnection event: {}", e);
+    /// knows the server is unreachable now. Repository traffic should prefer
-            }
+    /// `reporter().report_network_failure()` so the debounce applies.
+    pub async fn mark_unreachable(&self, error: Option<String>) {
+        self.reporter.apply_probe_result(false, error).await;
+    }
+
+    /// Start the offline recovery probe.
+    ///
+    /// While **online**, reachability is kept fresh by real traffic, so the probe
+    /// idles. While **offline**, it polls `/System/Info/Public` every
+    /// `RETRY_CHECK_INTERVAL_MS` to detect the server returning even when no user
+    /// traffic is flowing.
+    pub async fn start_monitoring(&self) {
+        if self.is_monitoring.swap(true, Ordering::SeqCst) {
+            log::info!("[ConnectivityMonitor] Already monitoring");
+            return;
         }
+
+        log::info!("[ConnectivityMonitor] Starting connectivity monitoring (offline recovery probe)");
+
+        // Perform an immediate check so startup reflects reality quickly.
+        let is_reachable = self.check_reachability().await;
+        log::info!("[ConnectivityMonitor] Initial connectivity check: {}", if is_reachable { "ONLINE" } else { "OFFLINE" });
+
+        let is_monitoring = Arc::clone(&self.is_monitoring);
+        let server_url = Arc::clone(&self.server_url);
+        let http_client = Arc::clone(&self.http_client);
+        let reporter = self.reporter.clone();
+
+        tokio::spawn(async move {
+            while is_monitoring.load(Ordering::SeqCst) {
+                tokio::time::sleep(Duration::from_millis(RETRY_CHECK_INTERVAL_MS)).await;
+
+                if !is_monitoring.load(Ordering::SeqCst) {
+                    break;
+                }
+
+                // Only probe while offline — real traffic is the signal when online.
+                if reporter.status.read().await.is_server_reachable {
+                    continue;
+                }
+
+                let Some(url) = server_url.read().await.clone() else {
+                    continue;
+                };
+                let ping_url = format!("{}/System/Info/Public", url);
+                let is_reachable = http_client.ping(&ping_url).await;
+
+                // Probe only ever recovers us to online; a failed probe leaves us
+                // offline without re-emitting (no change).
+                if is_reachable {
+                    reporter.apply_probe_result(true, None).await;
+                }
+            }
+
+            log::info!("[ConnectivityMonitor] Stopped monitoring");
+        });
+    }
+
+    /// Stop monitoring connectivity
+    pub fn stop_monitoring(&self) {
+        log::info!("[ConnectivityMonitor] Stopping connectivity monitoring");
+        self.is_monitoring.store(false, Ordering::SeqCst);
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::jellyfin::http_client::HttpConfig;
+
+    /// Build a reporter backed by a fresh (optimistic) status, with no app handle.
+    /// Event emission is a no-op without a handle, which is exactly what we want
+    /// for unit-testing the reachability state transitions.
+    fn test_reporter() -> ConnectivityReporter {
+        ConnectivityReporter::new(Arc::new(RwLock::new(ConnectivityStatus::default())), None)
+    }
+
+    async fn is_reachable(reporter: &ConnectivityReporter) -> bool {
+        reporter.status.read().await.is_server_reachable
+    }
 
     #[test]
     fn test_intervals() {
-        // Verify intervals match TypeScript
+        // Offline recovery probe interval (online has no polling).
-        assert_eq!(AUTO_CHECK_INTERVAL_MS, 30000);
         assert_eq!(RETRY_CHECK_INTERVAL_MS, 5000);
+        assert_eq!(OFFLINE_CONFIRM_WINDOW, Duration::from_secs(5));
     }
 
     #[tokio::test]
@@ -367,4 +376,120 @@ mod tests {
         assert!(status.connection_error.is_none());
         assert!(!status.is_checking);
     }
+
+    /// A single (or brief) network failure must NOT flip the app offline:
+    /// the time-window debounce keeps us online until the failure persists.
+    ///
+    /// @req-test: UR-002 - Access media when online or offline
+    #[tokio::test]
+    async fn test_single_network_failure_does_not_go_offline() {
+        let reporter = test_reporter();
+        assert!(is_reachable(&reporter).await, "starts online");
+
+        reporter
+            .report_network_failure(Some("timeout".to_string()))
+            .await;
+
+        assert!(
+            is_reachable(&reporter).await,
+            "one network failure within the debounce window stays online"
+        );
+        // But the failure streak is now being tracked.
+        assert!(reporter.first_failure_at.read().await.is_some());
+    }
+
+    /// Once failures persist past OFFLINE_CONFIRM_WINDOW, we flip offline.
+    /// We simulate elapsed time by backdating the streak start.
+    ///
+    /// @req-test: UR-002 - Access media when online or offline
+    #[tokio::test]
+    async fn test_sustained_network_failure_goes_offline() {
+        let reporter = test_reporter();
+
+        // First failure starts the streak.
+        reporter.report_network_failure(None).await;
+        assert!(is_reachable(&reporter).await);
+
+        // Backdate the streak start to before the window.
+        {
+            let mut first = reporter.first_failure_at.write().await;
+            *first = Some(Instant::now() - OFFLINE_CONFIRM_WINDOW - Duration::from_secs(1));
+        }
+
+        // Next failure now exceeds the window → offline.
+        reporter
+            .report_network_failure(Some("connection refused".to_string()))
+            .await;
+        assert!(
+            !is_reachable(&reporter).await,
+            "sustained network failure flips to offline"
+        );
+    }
+
+    /// A success during a failure streak clears the streak and keeps us online —
+    /// recovery is instant and never trips the banner.
+    #[tokio::test]
+    async fn test_success_clears_failure_streak() {
+        let reporter = test_reporter();
+
+        reporter.report_network_failure(None).await;
+        assert!(reporter.first_failure_at.read().await.is_some());
+
+        reporter.report_success().await;
+
+        assert!(is_reachable(&reporter).await);
+        assert!(
+            reporter.first_failure_at.read().await.is_none(),
+            "success resets the debounce streak"
+        );
+    }
+
+    /// First success after being offline recovers instantly (no debounce on the
+    /// way back up).
+    #[tokio::test]
+    async fn test_recovery_is_instant() {
+        let reporter = test_reporter();
+
+        // Force offline.
+        reporter.apply_probe_result(false, Some("down".to_string())).await;
+        assert!(!is_reachable(&reporter).await);
+
+        // A single success brings us straight back online.
+        reporter.report_success().await;
+        assert!(is_reachable(&reporter).await);
+        let status = reporter.status.read().await;
+        assert!(status.connection_error.is_none());
+    }
+
+    /// Server-answered errors (401/404/5xx) are reported via report_success
+    /// by the repository, because the server is demonstrably reachable. This
+    /// test documents that contract: report_success means "server is up".
+    #[tokio::test]
+    async fn test_server_answered_error_counts_as_reachable() {
+        let reporter = test_reporter();
+
+        // Simulate being offline, then the server answers (even with an error).
+        reporter.apply_probe_result(false, None).await;
+        assert!(!is_reachable(&reporter).await);
+
+        // Repository maps Authentication/NotFound/Server errors to report_success.
+        reporter.report_success().await;
+        assert!(
+            is_reachable(&reporter).await,
+            "a server that answers (even with 4xx/5xx) is reachable"
+        );
+    }
+
+    /// report_network_failure is a no-op once already offline (nothing to debounce,
+    /// no duplicate events).
+    #[tokio::test]
+    async fn test_network_failure_noop_when_already_offline() {
+        let reporter = test_reporter();
+        reporter.apply_probe_result(false, None).await;
+        assert!(!is_reachable(&reporter).await);
+
+        // Should not panic or change state.
+        reporter.report_network_failure(Some("still down".to_string())).await;
+        assert!(!is_reachable(&reporter).await);
+    }
 }

src-tauri/src/download/cache.rs

@@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize};
 use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 
 /// Smart caching configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CacheConfig {
     /// Enable queue pre-caching

src-tauri/src/download/mod.rs

@@ -77,7 +77,7 @@ impl DownloadManager {
 }
 
 /// Information about a download
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DownloadInfo {
     pub id: i64,
@@ -120,7 +120,6 @@ pub struct DownloadTask {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::player::MediaType;
 
     #[test]
     fn test_download_manager_set_max_concurrent() {

src-tauri/src/jellyfin/client.rs

@@ -381,72 +381,103 @@ fn default_true() -> bool {
 }
 
 /// Session information from Jellyfin
-#[derive(Debug, Clone, Deserialize, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, Deserialize, serde::Serialize)]
-#[serde(rename_all(deserialize = "PascalCase", serialize = "camelCase"))]
+#[serde(rename_all = "camelCase")]
 pub struct SessionInfo {
     #[serde(default)]
+    #[serde(alias = "Id")]
     pub id: Option<String>,
     #[serde(default)]
+    #[serde(alias = "UserId")]
     pub user_id: Option<String>,
     #[serde(default)]
+    #[serde(alias = "UserName")]
     pub user_name: Option<String>,
     #[serde(default)]
+    #[serde(alias = "Client")]
     pub client: Option<String>,
     #[serde(default)]
+    #[serde(alias = "DeviceName")]
     pub device_name: Option<String>,
     #[serde(default)]
+    #[serde(alias = "DeviceId")]
     pub device_id: Option<String>,
     #[serde(default)]
+    #[serde(alias = "ApplicationVersion")]
     pub application_version: Option<String>,
     #[serde(default)]
+    #[serde(alias = "IsActive")]
     pub is_active: Option<bool>,
     #[serde(default)]
+    #[serde(alias = "SupportsMediaControl")]
     pub supports_media_control: Option<bool>,
     #[serde(default = "default_true")]
+    #[serde(alias = "SupportsRemoteControl")]
     pub supports_remote_control: bool,
     #[serde(default)]
+    #[serde(alias = "NowPlayingItem")]
     pub now_playing_item: Option<NowPlayingItem>,
     #[serde(default)]
+    #[serde(alias = "PlayState")]
     pub play_state: Option<PlayState>,
     #[serde(default)]
+    #[serde(alias = "PlayableMediaTypes")]
     pub playable_media_types: Option<Vec<String>>,
     #[serde(default)]
+    #[serde(alias = "SupportedCommands")]
     pub supported_commands: Option<Vec<String>>,
 }
 
-#[derive(Debug, Clone, Deserialize, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, Deserialize, serde::Serialize)]
-#[serde(rename_all(deserialize = "PascalCase", serialize = "camelCase"))]
+#[serde(rename_all = "camelCase")]
 pub struct NowPlayingItem {
+    #[serde(alias = "Id")]
     pub id: Option<String>,
+    #[serde(alias = "Name")]
     pub name: Option<String>,
+    #[serde(alias = "RunTimeTicks")]
     pub run_time_ticks: Option<i64>,
+    #[serde(alias = "Album")]
     pub album: Option<String>,
+    #[serde(alias = "AlbumId")]
     pub album_id: Option<String>,
+    #[serde(alias = "AlbumArtist")]
     pub album_artist: Option<String>,
+    #[serde(alias = "Artists")]
     pub artists: Option<Vec<String>>,
+    #[serde(alias = "ImageTags")]
     pub image_tags: Option<std::collections::HashMap<String, String>>,
+    #[serde(alias = "PrimaryImageTag")]
     pub primary_image_tag: Option<String>,
+    #[serde(alias = "AlbumPrimaryImageTag")]
     pub album_primary_image_tag: Option<String>,
     #[serde(rename = "Type")]
     pub item_type: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, serde::Serialize)]
+#[derive(specta::Type, Debug, Clone, Deserialize, serde::Serialize)]
-#[serde(rename_all(deserialize = "PascalCase", serialize = "camelCase"))]
+#[serde(rename_all = "camelCase")]
 pub struct PlayState {
     #[serde(default)]
+    #[serde(alias = "PositionTicks")]
     pub position_ticks: Option<i64>,
     #[serde(default)]
+    #[serde(alias = "CanSeek")]
     pub can_seek: Option<bool>,
     #[serde(default)]
+    #[serde(alias = "IsPaused")]
     pub is_paused: Option<bool>,
     #[serde(default)]
+    #[serde(alias = "IsMuted")]
     pub is_muted: Option<bool>,
     #[serde(default)]
+    #[serde(alias = "VolumeLevel")]
     pub volume_level: Option<i32>,
     #[serde(default)]
+    #[serde(alias = "RepeatMode")]
     pub repeat_mode: Option<String>,
     #[serde(default)]
+    #[serde(alias = "ShuffleMode")]
     pub shuffle_mode: Option<String>,
 }
 

src-tauri/src/lib.rs

@@ -17,6 +17,7 @@ pub mod utils;
 use std::sync::{Arc, Mutex};
 use tokio::sync::Mutex as TokioMutex;
 use tauri::{Emitter, Manager};
+use tauri_specta::Builder;
 use log::{error, info};
 #[cfg(target_os = "android")]
 use log::warn;
@@ -100,6 +101,7 @@ use commands::{
     repository_report_playback_start, repository_report_playback_progress, repository_report_playback_stopped,
     repository_get_image_url, repository_mark_favorite, repository_unmark_favorite,
     repository_get_person, repository_get_items_by_person, repository_get_similar_items,
+    repository_get_subtitle_url, repository_get_video_download_url,
     // Playlist commands
     playlist_create, playlist_delete, playlist_rename, playlist_get_items,
     playlist_add_items, playlist_remove_items, playlist_move_item,
@@ -346,6 +348,243 @@ fn create_player_backend(
     }
 }
 
+/// Construct the tauri-specta command builder. Shared by `run()` and the
+/// bindings-export test so the TypeScript bindings always match the handler.
+fn specta_builder() -> Builder<tauri::Wry> {
+    Builder::<tauri::Wry>::new()
+        // Throw on error so generated `commands.*` return Promise<T> and throw,
+        // matching the existing frontend's invoke() try/catch convention.
+        .error_handling(tauri_specta::ErrorHandlingMode::Throw)
+        .commands(tauri_specta::collect_commands![
+            // Player commands
+            player_play_item,
+            player_play_queue,
+            player_play_album_track,
+            player_play_tracks,
+            player_play,
+            player_pause,
+            player_toggle,
+            player_stop,
+            player_next,
+            player_previous,
+            player_seek,
+            player_seek_video,
+            player_set_volume,
+            player_toggle_mute,
+            player_set_audio_track,
+            player_switch_audio_track,
+            player_set_subtitle_track,
+            player_toggle_shuffle,
+            player_cycle_repeat,
+            player_get_status,
+            player_get_queue,
+            player_add_to_queue,
+            player_add_track_by_id,
+            player_add_tracks_by_ids,
+            player_remove_from_queue,
+            player_move_in_queue,
+            player_skip_to,
+            player_set_audio_settings,
+            player_get_audio_settings,
+            player_set_video_settings,
+            player_get_video_settings,
+            // Sleep timer and autoplay commands
+            player_set_sleep_timer,
+            player_cancel_sleep_timer,
+            player_get_sleep_timer,
+            player_get_autoplay_settings,
+            player_set_autoplay_settings,
+            player_cancel_autoplay_countdown,
+            player_play_next_episode,
+            player_on_playback_ended,
+            // Preload commands
+            player_preload_upcoming,
+            player_set_cache_config,
+            player_get_cache_config,
+            // Jellyfin reporting commands
+            player_configure_jellyfin,
+            player_disable_jellyfin,
+            // Session management commands
+            player_get_session,
+            player_dismiss_session,
+            // Remote session control commands
+            remote_play_on_session,
+            remote_send_command,
+            remote_session_seek,
+            remote_session_set_volume,
+            remote_session_toggle_mute,
+            // Session polling commands
+            sessions_set_polling_hint,
+            sessions_poll_now,
+            // Playback mode commands
+            playback_mode_get_current,
+            playback_mode_set,
+            playback_mode_is_transferring,
+            playback_mode_transfer_to_remote,
+            playback_mode_get_remote_status,
+            playback_mode_transfer_to_local,
+            // Playback reporting commands
+            playback_reporter_init,
+            playback_reporter_destroy,
+            playback_report_start,
+            playback_report_progress,
+            playback_report_stopped,
+            playback_mark_played,
+            // Auth commands
+            auth_initialize,
+            auth_connect_to_server,
+            auth_login,
+            auth_verify_session,
+            auth_logout,
+            auth_get_session,
+            auth_set_session,
+            auth_start_verification,
+            auth_stop_verification,
+            auth_reauthenticate,
+            // Device commands
+            device_get_id,
+            device_set_id,
+            // Connectivity commands
+            connectivity_check_server,
+            connectivity_set_server_url,
+            connectivity_get_status,
+            connectivity_start_monitoring,
+            connectivity_stop_monitoring,
+            connectivity_mark_reachable,
+            connectivity_mark_unreachable,
+            // Storage commands
+            storage_init,
+            storage_get_path,
+            storage_get_size,
+            storage_get_security_status,
+            storage_save_server,
+            storage_get_servers,
+            storage_delete_server,
+            storage_save_user,
+            storage_get_users,
+            storage_set_active_user,
+            storage_get_active_user,
+            storage_get_active_session,
+            storage_get_access_token,
+            storage_delete_user,
+            // Playback progress commands
+            storage_update_playback_progress,
+            storage_update_playback_context,
+            storage_mark_played,
+            storage_get_playback_progress,
+            storage_mark_synced,
+            storage_toggle_favorite,
+            // Download commands
+            download_item,
+            download_item_and_start,
+            download_album,
+            download_video,
+            download_series,
+            download_season,
+            get_downloads,
+            pause_download,
+            resume_download,
+            cancel_download,
+            delete_download,
+            delete_all_downloads,
+            delete_album_downloads,
+            clear_stale_downloads,
+            get_download_storage_stats,
+            mark_download_completed,
+            mark_download_failed,
+            start_download,
+            get_download_manager_stats,
+            set_max_concurrent_downloads,
+            get_smart_cache_stats,
+            update_smart_cache_config,
+            get_smart_cache_config,
+            get_album_recommendations,
+            get_album_affinity_status,
+            // Pinning commands
+            pin_item,
+            unpin_item,
+            is_item_pinned,
+            // Offline commands
+            offline_is_available,
+            offline_get_items,
+            offline_search,
+            // Offline cache commands
+            storage_get_libraries,
+            storage_get_items,
+            storage_get_item,
+            storage_search_items,
+            storage_save_library,
+            storage_save_item,
+            storage_get_pending_sync_count,
+            // Sync queue commands
+            sync_queue_mutation,
+            sync_get_pending,
+            sync_mark_processing,
+            sync_mark_completed,
+            sync_mark_failed,
+            sync_get_pending_count,
+            sync_cleanup_completed,
+            sync_clear_user,
+            // Thumbnail cache and image commands
+            thumbnail_get_cached,
+            thumbnail_save,
+            thumbnail_get_stats,
+            thumbnail_set_limit,
+            thumbnail_clear_cache,
+            thumbnail_delete_item,
+            image_get_url,
+            // People cache commands
+            storage_save_person,
+            storage_get_person,
+            storage_save_item_people,
+            storage_get_item_people,
+            // Series audio preferences
+            storage_save_series_audio_preference,
+            storage_get_series_audio_preference,
+            // Repository commands
+            repository_create,
+            repository_destroy,
+            repository_get_libraries,
+            repository_get_items,
+            repository_get_item,
+            repository_get_latest_items,
+            repository_get_resume_items,
+            repository_get_next_up_episodes,
+            repository_get_recently_played_audio,
+            repository_get_resume_movies,
+            repository_get_genres,
+            repository_search,
+            repository_get_playback_info,
+            repository_get_video_stream_url,
+            repository_get_audio_stream_url,
+            repository_report_playback_start,
+            repository_report_playback_progress,
+            repository_report_playback_stopped,
+            repository_get_image_url,
+            repository_mark_favorite,
+            repository_unmark_favorite,
+            repository_get_person,
+            repository_get_items_by_person,
+            repository_get_similar_items,
+            repository_get_subtitle_url,
+            repository_get_video_download_url,
+            // Playlist commands
+            playlist_create,
+            playlist_delete,
+            playlist_rename,
+            playlist_get_items,
+            playlist_add_items,
+            playlist_remove_items,
+            playlist_move_item,
+            // Conversion commands
+            format_time_seconds,
+            format_time_seconds_long,
+            convert_ticks_to_seconds,
+            calc_progress,
+            convert_percent_to_volume,
+        ])
+}
+
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
     // Initialize logger
@@ -353,6 +592,12 @@ pub fn run() {
         .filter_level(log::LevelFilter::Info)
         .init();
 
+    // NOTE: TypeScript bindings are generated by the `export_typescript_bindings`
+    // test (`cargo test export_typescript_bindings`), NOT at runtime. Calling
+    // `.export()` here would try to write `../src/lib/api/bindings.ts` at app
+    // startup, which panics on devices (e.g. Android) where that path doesn't exist.
+    let builder = specta_builder();
+
     tauri::Builder::default()
         .plugin(tauri_plugin_opener::init())
         .plugin(tauri_plugin_os::init())
@@ -596,232 +841,22 @@ pub fn run() {
             info!("[INIT] Application setup completed successfully");
             Ok(())
         })
-        .invoke_handler(tauri::generate_handler![
+        .invoke_handler(builder.invoke_handler())
-            // Player commands
-            player_play_item,
-            player_play_queue,
-            player_play_album_track,
-            player_play_tracks,
-            player_play,
-            player_pause,
-            player_toggle,
-            player_stop,
-            player_next,
-            player_previous,
-            player_seek,
-            player_seek_video,
-            player_set_volume,
-            player_toggle_mute,
-            player_set_audio_track,
-            player_switch_audio_track,
-            player_set_subtitle_track,
-            player_toggle_shuffle,
-            player_cycle_repeat,
-            player_get_status,
-            player_get_queue,
-            player_add_to_queue,
-            player_add_track_by_id,
-            player_add_tracks_by_ids,
-            player_remove_from_queue,
-            player_move_in_queue,
-            player_skip_to,
-            player_set_audio_settings,
-            player_get_audio_settings,
-            player_set_video_settings,
-            player_get_video_settings,
-            // Sleep timer and autoplay commands
-            player_set_sleep_timer,
-            player_cancel_sleep_timer,
-            player_get_sleep_timer,
-            player_get_autoplay_settings,
-            player_set_autoplay_settings,
-            player_cancel_autoplay_countdown,
-            player_play_next_episode,
-            player_on_playback_ended,
-            // Preload commands
-            player_preload_upcoming,
-            player_set_cache_config,
-            player_get_cache_config,
-            // Jellyfin reporting commands
-            player_configure_jellyfin,
-            player_disable_jellyfin,
-            // Session management commands
-            player_get_session,
-            player_dismiss_session,
-            // Remote session control commands
-            remote_play_on_session,
-            remote_send_command,
-            remote_session_seek,
-            remote_session_set_volume,
-            remote_session_toggle_mute,
-            // Session polling commands
-            sessions_set_polling_hint,
-            sessions_poll_now,
-            // Playback mode commands
-            playback_mode_get_current,
-            playback_mode_set,
-            playback_mode_is_transferring,
-            playback_mode_transfer_to_remote,
-            playback_mode_get_remote_status,
-            playback_mode_transfer_to_local,
-            // Playback reporting commands
-            playback_reporter_init,
-            playback_reporter_destroy,
-            playback_report_start,
-            playback_report_progress,
-            playback_report_stopped,
-            playback_mark_played,
-            // Auth commands
-            auth_initialize,
-            auth_connect_to_server,
-            auth_login,
-            auth_verify_session,
-            auth_logout,
-            auth_get_session,
-            auth_set_session,
-            auth_start_verification,
-            auth_stop_verification,
-            auth_reauthenticate,
-            // Device commands
-            device_get_id,
-            device_set_id,
-            // Connectivity commands
-            connectivity_check_server,
-            connectivity_set_server_url,
-            connectivity_get_status,
-            connectivity_start_monitoring,
-            connectivity_stop_monitoring,
-            connectivity_mark_reachable,
-            connectivity_mark_unreachable,
-            // Storage commands
-            storage_init,
-            storage_get_path,
-            storage_get_size,
-            storage_get_security_status,
-            storage_save_server,
-            storage_get_servers,
-            storage_delete_server,
-            storage_save_user,
-            storage_get_users,
-            storage_set_active_user,
-            storage_get_active_user,
-            storage_get_active_session,
-            storage_get_access_token,
-            storage_delete_user,
-            // Playback progress commands
-            storage_update_playback_progress,
-            storage_update_playback_context,
-            storage_mark_played,
-            storage_get_playback_progress,
-            storage_mark_synced,
-            storage_toggle_favorite,
-            // Download commands
-            download_item,
-            download_item_and_start,
-            download_album,
-            download_video,
-            download_series,
-            download_season,
-            get_downloads,
-            pause_download,
-            resume_download,
-            cancel_download,
-            delete_download,
-            delete_all_downloads,
-            delete_album_downloads,
-            clear_stale_downloads,
-            get_download_storage_stats,
-            mark_download_completed,
-            mark_download_failed,
-            start_download,
-            get_download_manager_stats,
-            set_max_concurrent_downloads,
-            get_smart_cache_stats,
-            update_smart_cache_config,
-            get_smart_cache_config,
-            get_album_recommendations,
-            get_album_affinity_status,
-            // Pinning commands
-            pin_item,
-            unpin_item,
-            is_item_pinned,
-            // Offline commands
-            offline_is_available,
-            offline_get_items,
-            offline_search,
-            // Offline cache commands
-            storage_get_libraries,
-            storage_get_items,
-            storage_get_item,
-            storage_search_items,
-            storage_save_library,
-            storage_save_item,
-            storage_get_pending_sync_count,
-            // Sync queue commands
-            sync_queue_mutation,
-            sync_get_pending,
-            sync_mark_processing,
-            sync_mark_completed,
-            sync_mark_failed,
-            sync_get_pending_count,
-            sync_cleanup_completed,
-            sync_clear_user,
-            // Thumbnail cache and image commands
-            thumbnail_get_cached,
-            thumbnail_save,
-            thumbnail_get_stats,
-            thumbnail_set_limit,
-            thumbnail_clear_cache,
-            thumbnail_delete_item,
-            image_get_url,
-            // People cache commands
-            storage_save_person,
-            storage_get_person,
-            storage_save_item_people,
-            storage_get_item_people,
-            // Series audio preferences
-            storage_save_series_audio_preference,
-            storage_get_series_audio_preference,
-            // Repository commands
-            repository_create,
-            repository_destroy,
-            repository_get_libraries,
-            repository_get_items,
-            repository_get_item,
-            repository_get_latest_items,
-            repository_get_resume_items,
-            repository_get_next_up_episodes,
-            repository_get_recently_played_audio,
-            repository_get_resume_movies,
-            repository_get_genres,
-            repository_search,
-            repository_get_playback_info,
-            repository_get_video_stream_url,
-            repository_get_audio_stream_url,
-            repository_report_playback_start,
-            repository_report_playback_progress,
-            repository_report_playback_stopped,
-            repository_get_image_url,
-            repository_mark_favorite,
-            repository_unmark_favorite,
-            repository_get_person,
-            repository_get_items_by_person,
-            repository_get_similar_items,
-            // Playlist commands
-            playlist_create,
-            playlist_delete,
-            playlist_rename,
-            playlist_get_items,
-            playlist_add_items,
-            playlist_remove_items,
-            playlist_move_item,
-            // Conversion commands
-            format_time_seconds,
-            format_time_seconds_long,
-            convert_ticks_to_seconds,
-            calc_progress,
-            convert_percent_to_volume,
-        ])
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }
+
+
+#[cfg(test)]
+mod specta_bindings {
+    /// Generates `src/lib/api/bindings.ts`. Run with `cargo test export_typescript_bindings`.
+    #[test]
+    fn export_typescript_bindings() {
+        super::specta_builder()
+            .export(
+                specta_typescript::Typescript::default().bigint(specta_typescript::BigIntExportBehavior::Number),
+                "../src/lib/api/bindings.ts",
+            )
+            .expect("failed to export typescript bindings");
+    }
+}

src-tauri/src/playback_mode/mod.rs

@@ -12,7 +12,7 @@ use crate::jellyfin::JellyfinClient;
 use crate::player::{PlayerController, QueueContext};
 
 /// Playback mode - local device, remote session, or idle
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum PlaybackMode {
     Local,

src-tauri/src/player/autoplay.rs

@@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize};
 use crate::repository::types::MediaItem;
 
 /// Autoplay decision result - determines what happens after playback ends
-#[derive(Debug, Clone, Serialize)]
+#[derive(specta::Type, Debug, Clone, Serialize)]
 #[serde(tag = "action", rename_all = "camelCase")]
 pub enum AutoplayDecision {
     /// Stop playback (no next item or timer expired)
@@ -21,7 +21,7 @@ pub enum AutoplayDecision {
 }
 
 /// Autoplay settings (controls next episode behavior)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AutoplaySettings {
     /// Whether autoplay is enabled for next episodes

src-tauri/src/player/events.rs

@@ -172,10 +172,6 @@ mod tests {
         pub fn events(&self) -> Vec<PlayerStatusEvent> {
             self.events.lock_safe().clone()
         }
-
-        pub fn clear(&self) {
-            self.events.lock_safe().clear();
-        }
     }
 
     impl PlayerEventEmitter for TestEventEmitter {

src-tauri/src/player/media.rs

@@ -3,7 +3,7 @@ use std::path::PathBuf;
 
 /// Context for the current queue - where did the queue items come from?
 /// This is used for remote playback transfer to send album/playlist context.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum QueueContext {
     /// Playing from a specific album
@@ -23,7 +23,7 @@ pub enum QueueContext {
 }
 
 /// Represents a subtitle track
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct SubtitleTrack {
     /// Stream index in the media source
     pub index: i32,
@@ -40,8 +40,9 @@ pub struct SubtitleTrack {
 /// Represents a media item that can be played
 ///
 /// TRACES: UR-003, UR-004 | DR-002
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
+#[specta(rename = "PlayerMediaItem")]
 pub struct MediaItem {
     /// Unique identifier
     pub id: String,
@@ -106,7 +107,7 @@ pub struct MediaItem {
     pub server_id: Option<String>,
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum MediaType {
     Audio,
@@ -114,8 +115,9 @@ pub enum MediaType {
 }
 
 /// TRACES: UR-002, UR-003, UR-004, UR-011 | DR-003
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "type", rename_all = "lowercase")]
+#[specta(rename = "PlayerMediaSource")]
 pub enum MediaSource {
     /// Streaming from Jellyfin server
     Remote {

src-tauri/src/player/mod.rs

@@ -212,6 +212,23 @@ impl PlayerController {
         Ok(())
     }
 
+    /// Set the current queue item without loading it into the playback backend.
+    ///
+    /// Used on platforms where video is rendered outside the native backend
+    /// (Linux WebKitGTK HTML5 <video>): the queue/UI state must reflect the
+    /// item, but MPV must not start a redundant decode for it.
+    #[cfg(target_os = "linux")]
+    pub fn set_current_item(&self, item: MediaItem) -> Result<(), PlayerError> {
+        debug!("[PlayerController] set_current_item (no backend load): {}", item.title);
+
+        self.reset_autoplay_count();
+
+        let mut queue = self.queue.lock_safe();
+        queue.set_queue(vec![item], 0);
+
+        Ok(())
+    }
+
     /// Load and play an item without modifying the queue
     /// Use this when the queue is already set up and you just want to play a specific item from it
     pub fn load_and_play(&self, item: &MediaItem) -> Result<(), PlayerError> {

src-tauri/src/player/queue.rs

@@ -6,7 +6,7 @@ use super::media::{MediaItem, MediaSource, QueueContext};
 /// Repeat mode for the queue
 ///
 /// TRACES: UR-005 | DR-005
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum RepeatMode {
     #[default]
@@ -18,7 +18,7 @@ pub enum RepeatMode {
 /// Queue manager for playlist functionality
 ///
 /// TRACES: UR-005, UR-015 | DR-005, DR-020
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 pub struct QueueManager {
     /// All items in the queue
     items: Vec<MediaItem>,

src-tauri/src/player/session.rs

@@ -5,7 +5,7 @@
  * beyond individual playback states. Enables persistent UI (miniplayer) and
  * proper transitions between content types.
  *
- * See software-architecture.md Section 2.1 for state machine diagram.
+ * See docs/architecture/01-rust-backend.md for the state machine diagram.
  */
 
 use log::info;
@@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize};
 use super::media::MediaItem;
 
 /// Media session type tracking the high-level playback context
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum MediaSessionType {
     /// No active session - browsing library

src-tauri/src/player/sleep_timer.rs

@@ -2,7 +2,7 @@ use serde::{Deserialize, Serialize};
 
 /// Sleep timer mode - determines when playback should stop
 /// TRACES: UR-026 | DR-029
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "kind", rename_all = "camelCase")]
 pub enum SleepTimerMode {
     /// Timer is off
@@ -19,7 +19,7 @@ pub enum SleepTimerMode {
 }
 
 /// Sleep timer state
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SleepTimerState {
     pub mode: SleepTimerMode,

src-tauri/src/player/state.rs

@@ -5,7 +5,7 @@ use super::media::MediaItem;
 /// Tracks why playback ended to determine autoplay behavior
 ///
 /// TRACES: UR-005 | DR-001
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum EndReason {
     /// Track played to completion (natural end) - trigger autoplay
@@ -23,7 +23,7 @@ pub enum EndReason {
 /// Player state machine (6 states: Idle, Loading, Playing, Paused, Seeking, Error)
 ///
 /// TRACES: UR-005 | DR-001
-#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(tag = "kind", rename_all = "lowercase")]
 pub enum PlayerState {
     #[default]

src-tauri/src/repository/online.rs

@@ -7,6 +7,7 @@ use log::{debug, error, info};
 use log::warn;
 use serde::{Deserialize, Serialize};
 
+use crate::connectivity::ConnectivityReporter;
 use crate::jellyfin::HttpClient;
 use super::{MediaRepository, types::*};
 
@@ -16,6 +17,10 @@ pub struct OnlineRepository {
     server_url: String,
     user_id: String,
     access_token: String,
+    /// Reports the outcome of every server request to the connectivity monitor.
+    /// This is the source of truth for the offline/online banner. `None` in
+    /// tests / contexts where connectivity tracking isn't wired up.
+    connectivity: Option<ConnectivityReporter>,
 }
 
 impl OnlineRepository {
@@ -30,6 +35,44 @@ impl OnlineRepository {
             server_url,
             user_id,
             access_token,
+            connectivity: None,
+        }
+    }
+
+    /// Attach a connectivity reporter so server outcomes drive the reachability
+    /// state observed by the UI. See `report_outcome`.
+    pub fn with_connectivity(mut self, reporter: ConnectivityReporter) -> Self {
+        self.connectivity = Some(reporter);
+        self
+    }
+
+    /// Feed a request outcome into the connectivity monitor.
+    ///
+    /// Classification (matches docs/architecture/07-connectivity.md):
+    /// - `Ok` / `Authentication` / `NotFound` / `Server` → the server answered,
+    ///   so it is reachable → `report_success` (instant recovery).
+    /// - `Network` → connection-level failure → `report_network_failure`
+    ///   (subject to the time-window debounce before going offline).
+    /// - `Database` → not a server signal → ignored.
+    async fn report_outcome<T>(&self, result: &Result<T, RepoError>) {
+        let Some(reporter) = &self.connectivity else {
+            return;
+        };
+
+        match result {
+            Ok(_)
+            | Err(RepoError::Authentication { .. })
+            | Err(RepoError::NotFound { .. })
+            | Err(RepoError::Server { .. }) => {
+                reporter.report_success().await;
+            }
+            Err(RepoError::Network { message }) => {
+                reporter.report_network_failure(Some(message.clone())).await;
+            }
+            Err(RepoError::Database { .. }) | Err(RepoError::Offline) => {
+                // Local-side errors (cache failure / already-offline) — not a
+                // statement about the server's reachability, so ignore them.
+            }
         }
     }
 
@@ -63,6 +106,12 @@ impl OnlineRepository {
 
     /// Make authenticated GET request
     async fn get_json<T: for<'de> Deserialize<'de>>(&self, endpoint: &str) -> Result<T, RepoError> {
+        let result = self.get_json_inner(endpoint).await;
+        self.report_outcome(&result).await;
+        result
+    }
+
+    async fn get_json_inner<T: for<'de> Deserialize<'de>>(&self, endpoint: &str) -> Result<T, RepoError> {
         let url = format!("{}{}", self.server_url, endpoint);
 
         let request = self.http_client.client.get(&url)
@@ -110,6 +159,12 @@ impl OnlineRepository {
 
     /// Make authenticated POST request
     async fn post_json<T: Serialize>(&self, endpoint: &str, body: &T) -> Result<(), RepoError> {
+        let result = self.post_json_inner(endpoint, body).await;
+        self.report_outcome(&result).await;
+        result
+    }
+
+    async fn post_json_inner<T: Serialize>(&self, endpoint: &str, body: &T) -> Result<(), RepoError> {
         let url = format!("{}{}", self.server_url, endpoint);
 
         let request = self.http_client.client.post(&url)
@@ -145,6 +200,16 @@ impl OnlineRepository {
         &self,
         endpoint: &str,
         body: &T,
+    ) -> Result<R, RepoError> {
+        let result = self.post_json_response_inner(endpoint, body).await;
+        self.report_outcome(&result).await;
+        result
+    }
+
+    async fn post_json_response_inner<T: Serialize, R: for<'de> Deserialize<'de>>(
+        &self,
+        endpoint: &str,
+        body: &T,
     ) -> Result<R, RepoError> {
         let url = format!("{}{}", self.server_url, endpoint);
 
@@ -193,9 +258,16 @@ impl OnlineRepository {
         })
     }
 
-    /// Get a video stream URL for playback with optional seeking support.
+    /// Get a video stream URL for playback at an arbitrary position (resume,
-    /// For direct streams, uses /Videos/{id}/stream.mp4 with transcoding to support seeking.
+    /// transcoded seeking, audio-track switching).
-    /// For transcoded streams (HEVC/10-bit), includes StartTimeTicks parameter.
+    ///
+    /// Returns an HLS master playlist (`/Videos/{id}/master.m3u8`) transcoded to
+    /// h264/aac. HLS is used rather than a progressive `stream.mp4` because the
+    /// HTML5 `<video>` element (via HLS.js) starts playing within seconds and can
+    /// seek within the stream, whereas a progressive MP4 transcode of HEVC source
+    /// forces the server to transcode the whole file before playback can begin —
+    /// which manifests as playback never starting. `StartTimeTicks` makes the
+    /// server begin the transcode at the requested position.
     pub async fn get_video_stream_url(
         &self,
         item_id: &str,
@@ -210,12 +282,11 @@ impl OnlineRepository {
         // Use provided audio stream index, or default to 0
         let audio_index = audio_stream_index.unwrap_or(0).to_string();
 
-        // Build URL with progressive MP4 transcoding for seeking support
+        // Build an HLS transcode URL. VideoCodec lists h264 first so the server
-        // This works for both direct streams and HEVC content
+        // transcodes HEVC/10-bit/unsupported sources to h264 the WebView can decode.
         let mut params = vec![
             ("api_key", self.access_token.clone()),
             ("DeviceId", "jellytau-tauri".to_string()),
-            ("Container", "mp4".to_string()),
             ("VideoCodec", "h264".to_string()),
             ("AudioCodec", "aac".to_string()),
             ("AudioStreamIndex", audio_index),
@@ -223,6 +294,9 @@ impl OnlineRepository {
             ("VideoBitrate", "18000000".to_string()),
             ("AudioBitrate", "384000".to_string()),
             ("TranscodingMaxAudioChannels", "2".to_string()),
+            ("SegmentContainer", "ts".to_string()),
+            ("TranscodingContainer", "ts".to_string()),
+            ("TranscodingProtocol", "hls".to_string()),
         ];
 
         if let Some(source_id) = media_source_id {
@@ -241,7 +315,7 @@ impl OnlineRepository {
             .join("&");
 
         let url = format!(
-            "{}/Videos/{}/stream.mp4?{}",
+            "{}/Videos/{}/master.m3u8?{}",
             self.server_url, item_id, query
         );
 
@@ -859,7 +933,18 @@ impl MediaRepository for OnlineRepository {
                 ("h264,hevc".to_string(), "aac,mp3".to_string())
             });
 
-        #[cfg(not(target_os = "android"))]
+        // Linux desktop plays video through the WebKitGTK HTML5 <video> element,
+        // which cannot reliably decode HEVC/AV1/VP9. Advertise only codecs the
+        // WebView can decode so Jellyfin transcodes anything else to h264 HLS.
+        // (Audio-only files still direct-play via MPV, but the PlaybackInfo
+        // profile is shared, so we keep the broadly-supported audio codecs.)
+        #[cfg(all(not(target_os = "android"), target_os = "linux"))]
+        let (video_codecs, audio_codecs) = (
+            "h264".to_string(),
+            "aac,mp3,opus,vorbis,flac".to_string(),
+        );
+
+        #[cfg(all(not(target_os = "android"), not(target_os = "linux")))]
         let (video_codecs, audio_codecs) = (
             "h264,hevc,vp8,vp9,av1,mpeg4".to_string(),
             "aac,mp3,opus,vorbis,flac".to_string(),
@@ -1136,23 +1221,29 @@ impl MediaRepository for OnlineRepository {
         let endpoint = format!("/Users/{}/FavoriteItems/{}", self.user_id, item_id);
         let url = format!("{}{}", self.server_url, endpoint);
 
-        let request = self.http_client.client.delete(&url)
+        let result = async {
-            .header("X-Emby-Authorization", self.auth_header())
+            let request = self.http_client.client.delete(&url)
-            .build()
+                .header("X-Emby-Authorization", self.auth_header())
-            .map_err(|e| RepoError::Network {
+                .build()
-                message: format!("Failed to build request: {}", e),
+                .map_err(|e| RepoError::Network {
-            })?;
+                    message: format!("Failed to build request: {}", e),
+                })?;
 
-        let response = self.http_client.request_with_retry(request).await
+            let response = self.http_client.request_with_retry(request).await
-            .map_err(|e| RepoError::Network { message: e.to_string() })?;
+                .map_err(|e| RepoError::Network { message: e.to_string() })?;
 
-        if !response.status().is_success() {
+            if !response.status().is_success() {
-            return Err(RepoError::Server {
+                return Err(RepoError::Server {
-                message: format!("HTTP {}", response.status()),
+                    message: format!("HTTP {}", response.status()),
-            });
+                });
+            }
+
+            Ok(())
         }
+        .await;
 
-        Ok(())
+        self.report_outcome(&result).await;
+        result
     }
 
     async fn get_person(&self, person_id: &str) -> Result<MediaItem, RepoError> {
@@ -1377,6 +1468,91 @@ mod tests {
         )
     }
 
+    /// Build a repository wired to a real ConnectivityReporter so we can assert
+    /// how `report_outcome` classifies each `RepoError` into reachability.
+    /// (No app handle → event emission is a harmless no-op.)
+    fn create_test_repository_with_connectivity(
+    ) -> (OnlineRepository, crate::connectivity::ConnectivityReporter) {
+        let monitor_http = HttpClient::new(crate::jellyfin::HttpConfig::default())
+            .expect("Failed to create HTTP client for monitor");
+        let monitor = crate::connectivity::ConnectivityMonitor::new(monitor_http);
+        let reporter = monitor.reporter();
+        let repo = create_test_repository().with_connectivity(reporter.clone());
+        (repo, reporter)
+    }
+
+    /// `report_outcome` is the seam between repository traffic and the
+    /// connectivity monitor. Verify each `RepoError` variant routes correctly:
+    /// - the server answering at all (Ok / 401 / 404 / 5xx) ⇒ reachable
+    /// - a network-level failure ⇒ marked unreachable (debounce reduced for test)
+    /// - local-side errors (Database / Offline) ⇒ no effect on reachability
+    ///
+    /// @req-test: UR-002 - Access media when online or offline
+    /// @req-test: DR-013 - Repository pattern for online/offline data access
+    #[tokio::test]
+    async fn test_report_outcome_classifies_server_answered_as_reachable() {
+        let (repo, reporter) = create_test_repository_with_connectivity();
+
+        // Drive offline first so we can observe "recover to reachable".
+        for err in [
+            RepoError::Authentication { message: "401".into() },
+            RepoError::NotFound { message: "404".into() },
+            RepoError::Server { message: "500".into() },
+        ] {
+            reporter.mark_unreachable_for_test().await;
+            assert!(!reporter.is_reachable().await, "precondition: offline");
+
+            let result: Result<(), RepoError> = Err(err);
+            repo.report_outcome(&result).await;
+
+            assert!(
+                reporter.is_reachable().await,
+                "a server that answers should be reported reachable"
+            );
+        }
+
+        // Ok should also report reachable.
+        reporter.mark_unreachable_for_test().await;
+        let ok: Result<(), RepoError> = Ok(());
+        repo.report_outcome(&ok).await;
+        assert!(reporter.is_reachable().await, "Ok ⇒ reachable");
+    }
+
+    /// Local-side errors must NOT flip reachability — they say nothing about the
+    /// server.
+    #[tokio::test]
+    async fn test_report_outcome_ignores_local_errors() {
+        let (repo, reporter) = create_test_repository_with_connectivity();
+
+        // Force offline, then a Database/Offline error must leave it offline
+        // (not falsely report reachable).
+        reporter.mark_unreachable_for_test().await;
+        for err in [RepoError::Database { message: "cache".into() }, RepoError::Offline] {
+            let result: Result<(), RepoError> = Err(err);
+            repo.report_outcome(&result).await;
+            assert!(
+                !reporter.is_reachable().await,
+                "local-side error must not change reachability"
+            );
+        }
+    }
+
+    /// A network error routes through the debounced path. A single failure stays
+    /// online (debounce window not yet elapsed).
+    #[tokio::test]
+    async fn test_report_outcome_network_error_is_debounced() {
+        let (repo, reporter) = create_test_repository_with_connectivity();
+        assert!(reporter.is_reachable().await, "starts online");
+
+        let result: Result<(), RepoError> = Err(RepoError::Network { message: "timeout".into() });
+        repo.report_outcome(&result).await;
+
+        assert!(
+            reporter.is_reachable().await,
+            "a single network failure stays online (debounced)"
+        );
+    }
+
     #[tokio::test]
     async fn test_get_audio_stream_url_formats_correctly() {
         let repo = create_test_repository();
@@ -1392,6 +1568,46 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn test_get_video_stream_url_returns_hls_with_position() {
+        // Transcoded video resume/seek must produce an HLS master playlist with
+        // StartTimeTicks, not a progressive stream.mp4 (which never starts playing
+        // for HEVC sources). See get_video_stream_url docs.
+        let repo = create_test_repository();
+
+        let url = repo
+            .get_video_stream_url("vid-1", Some("source-1"), Some(193.0), Some(1))
+            .await
+            .unwrap();
+
+        assert!(
+            url.starts_with("https://test.server.com/Videos/vid-1/master.m3u8?"),
+            "expected HLS master playlist, got: {url}"
+        );
+        assert!(url.contains("VideoCodec=h264"));
+        assert!(url.contains("MediaSourceId=source-1"));
+        assert!(url.contains("AudioStreamIndex=1"));
+        // 193.0 seconds * 10_000_000 ticks/sec
+        assert!(url.contains("StartTimeTicks=1930000000"), "url: {url}");
+        assert!(!url.contains("stream.mp4"));
+    }
+
+    #[tokio::test]
+    async fn test_get_video_stream_url_omits_position_when_absent() {
+        let repo = create_test_repository();
+
+        let url = repo
+            .get_video_stream_url("vid-1", None, None, None)
+            .await
+            .unwrap();
+
+        assert!(url.starts_with("https://test.server.com/Videos/vid-1/master.m3u8?"));
+        assert!(!url.contains("StartTimeTicks"));
+        assert!(!url.contains("MediaSourceId"));
+        // Defaults to first audio stream
+        assert!(url.contains("AudioStreamIndex=0"));
+    }
+
     #[tokio::test]
     async fn test_get_audio_stream_url_with_special_characters() {
         let repo = create_test_repository();

src-tauri/src/repository/types.rs

@@ -1,7 +1,7 @@
 use serde::{Deserialize, Serialize};
 
 /// Error types for repository operations
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum RepoError {
     Network { message: String },
@@ -28,7 +28,7 @@ impl std::fmt::Display for RepoError {
 impl std::error::Error for RepoError {}
 
 /// Library (media collection)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Library {
     pub id: String,
@@ -39,7 +39,7 @@ pub struct Library {
 }
 
 /// User-specific data for an item (playback state, favorites, etc.)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UserData {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -59,15 +59,17 @@ pub struct UserData {
 }
 
 /// Artist item with ID and name (for clickable artist links)
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "PascalCase")]
+#[serde(rename_all = "camelCase")]
 pub struct ArtistItem {
+    #[serde(alias = "Id")]
     pub id: String,
+    #[serde(alias = "Name")]
     pub name: String,
 }
 
 /// Person (cast/crew member) - for movies, series, and episodes
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 pub struct Person {
     /// Deserializes from API's "Id" field (PascalCase), serializes as "id" (camelCase to frontend)
@@ -95,7 +97,7 @@ pub struct Person {
 }
 
 /// Media item
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MediaItem {
     pub id: String,
@@ -118,6 +120,7 @@ pub struct MediaItem {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub official_rating: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(rename = "runTimeTicks")]
     pub runtime_ticks: Option<i64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub primary_image_tag: Option<String>,
@@ -158,7 +161,7 @@ pub struct MediaItem {
 }
 
 /// Media stream information (audio, video, subtitle tracks)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MediaStream {
     #[serde(rename = "type")]
@@ -175,7 +178,7 @@ pub struct MediaStream {
 }
 
 /// Media source information
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MediaSource {
     pub id: String,
@@ -194,7 +197,7 @@ pub struct MediaSource {
 }
 
 /// Search result with pagination
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SearchResult {
     pub items: Vec<MediaItem>,
@@ -202,7 +205,7 @@ pub struct SearchResult {
 }
 
 /// Options for querying items
-#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct GetItemsOptions {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -224,7 +227,7 @@ pub struct GetItemsOptions {
 }
 
 /// Options for search queries
-#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct SearchOptions {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -236,7 +239,7 @@ pub struct SearchOptions {
 }
 
 /// Playback information
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlaybackInfo {
     pub media_source_id: String,
@@ -247,7 +250,7 @@ pub struct PlaybackInfo {
 }
 
 /// Genre
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Genre {
     pub id: String,
@@ -255,7 +258,7 @@ pub struct Genre {
 }
 
 /// Image type
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 pub enum ImageType {
     Primary,
     Backdrop,
@@ -277,7 +280,7 @@ impl ImageType {
 }
 
 /// Image options
-#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct ImageOptions {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -335,7 +338,7 @@ impl MeaningfulContent for PlaybackInfo {
 /// needed for remove/reorder operations (distinct from the media item's ID)
 ///
 /// @req: UR-014 - Make and edit playlists of music that sync back to Jellyfin
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlaylistEntry {
     /// The playlist-scoped entry ID (Jellyfin's PlaylistItemId)
@@ -348,7 +351,7 @@ pub struct PlaylistEntry {
 /// Result of creating a playlist
 ///
 /// @req: JA-019 - Get/create/update playlists
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PlaylistCreatedResult {
     pub id: String,
@@ -402,15 +405,21 @@ mod tests {
 
     #[test]
     fn test_artist_item_serialize() {
-        // Test that ArtistItem serializes to PascalCase for consistency
+        // ArtistItem serializes to camelCase for the frontend; it still accepts
+        // Jellyfin's PascalCase on deserialize via #[serde(alias = ...)].
         let artist = ArtistItem {
             id: "test-id".to_string(),
             name: "Test Artist".to_string(),
         };
 
         let json = serde_json::to_string(&artist).expect("Failed to serialize");
-        assert!(json.contains(r#""Id":"test-id""#));
+        assert!(json.contains(r#""id":"test-id""#));
-        assert!(json.contains(r#""Name":"Test Artist""#));
+        assert!(json.contains(r#""name":"Test Artist""#));
+
+        let from_pascal: ArtistItem =
+            serde_json::from_str(r#"{"Id":"x","Name":"Y"}"#).expect("Failed to deserialize");
+        assert_eq!(from_pascal.id, "x");
+        assert_eq!(from_pascal.name, "Y");
     }
 
     #[test]

src-tauri/src/settings.rs

@@ -3,7 +3,7 @@
 use serde::{Deserialize, Serialize};
 
 /// Volume normalization levels matching Spotify's presets
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
+#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum VolumeLevel {
     /// Louder output (-11 LUFS)
@@ -27,7 +27,7 @@ impl VolumeLevel {
 }
 
 /// Audio playback settings
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AudioSettings {
     /// Crossfade duration in seconds (0 = disabled, max 12)
@@ -60,7 +60,7 @@ impl AudioSettings {
 }
 
 /// Video playback settings
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct VideoSettings {
     /// Enable auto-play of next episode (with countdown)

src-tauri/src/thumbnail/cache.rs

@@ -344,7 +344,6 @@ mod tests {
     use super::*;
     use crate::storage::db_service::RusqliteService;
     use rusqlite::Connection;
-    use std::io::Write;
     use std::sync::{Arc, Mutex};
     use tempfile::TempDir;
 

src-tauri/src/thumbnail/mod.rs

@@ -13,7 +13,7 @@ pub use cache::{CacheConfig, ThumbnailCache};
 pub use worker::ThumbnailWorker;
 
 /// Statistics about the thumbnail cache
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ThumbnailCacheStats {
     pub total_size_bytes: u64,

src/app.css

@@ -1,5 +1,10 @@
 @import "tailwindcss";
 
+/* Exclude the generated tauri-specta bindings from Tailwind's content scan.
+   It contains no CSS classes (only TS types/command wrappers), and scanning a
+   large generated file can confuse Tailwind v4's automatic class detection. */
+@source not "./lib/api/bindings.ts";
+
 /* Custom theme variables for JellyTau */
 @theme {
   --color-jellyfin: #00a4dc;

src/lib/api/autoplay.test.ts

@@ -10,6 +10,7 @@ import {
   playNextEpisode,
   type AutoplaySettings,
 } from "./autoplay";
+import type { PlayItemRequest } from "./bindings";
 
 vi.mock("@tauri-apps/api/core", () => ({
   invoke: vi.fn(async (command: string, args?: any) => {
@@ -33,6 +34,23 @@ vi.mock("@tauri-apps/api/core", () => ({
   }),
 }));
 
+// setAutoplaySettings sources the user id from the auth store
+vi.mock("$lib/stores/auth", () => ({
+  auth: { getUserId: () => "user-1" },
+}));
+
+// Minimal valid PlayItemRequest for playNextEpisode tests
+function makeItem(overrides: Partial<PlayItemRequest> = {}): PlayItemRequest {
+  return {
+    id: "item-123",
+    title: "Episode 1",
+    streamUrl: "http://example/stream",
+    videoCodec: "h264",
+    needsTranscoding: false,
+    ...overrides,
+  };
+}
+
 describe("autoplay API", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -98,7 +116,7 @@ describe("autoplay API", () => {
         (c) => c[0] === "player_set_autoplay_settings"
       );
       expect(call).toBeDefined();
-      expect(call![1]).toEqual({ settings });
+      expect(call![1]).toEqual({ userId: "user-1", settings });
     });
 
     it("should support different countdown values", async () => {
@@ -130,11 +148,7 @@ describe("autoplay API", () => {
 
   describe("playNextEpisode", () => {
     it("should play next episode with item", async () => {
-      const mockItem = {
+      const mockItem = makeItem();
-        id: "item-123",
-        name: "Episode 1",
-        seriesId: "series-456",
-      };
 
       await playNextEpisode(mockItem);
 
@@ -150,9 +164,9 @@ describe("autoplay API", () => {
 
     it("should handle different item types", async () => {
       const items = [
-        { id: "1", name: "Episode 1" },
+        makeItem({ id: "1", title: "Episode 1" }),
-        { id: "2", name: "Episode 2", seasonNumber: 1 },
+        makeItem({ id: "2", title: "Episode 2" }),
-        { id: "3", name: "Episode 3", episodeNumber: 5 },
+        makeItem({ id: "3", title: "Episode 3" }),
       ];
 
       for (const item of items) {

src/lib/api/autoplay.ts

@@ -4,28 +4,26 @@
  * Functions to control autoplay in the backend.
  */
 
-import { invoke } from "@tauri-apps/api/core";
+import { commands } from "$lib/api/bindings";
+import type { PlayItemRequest, AutoplaySettings } from "$lib/api/bindings";
+import { auth } from "$lib/stores/auth";
 
-export interface AutoplaySettings {
+export type { AutoplaySettings };
-  enabled: boolean;
-  countdownSeconds: number;
-  maxEpisodes: number;
-}
 
 export async function getAutoplaySettings(): Promise<AutoplaySettings> {
-  return invoke("player_get_autoplay_settings");
+  return commands.playerGetAutoplaySettings();
 }
 
 export async function setAutoplaySettings(
   settings: AutoplaySettings
 ): Promise<AutoplaySettings> {
-  return invoke("player_set_autoplay_settings", { settings });
+  return commands.playerSetAutoplaySettings(auth.getUserId() ?? "", settings);
 }
 
 export async function cancelAutoplayCountdown(): Promise<void> {
-  return invoke("player_cancel_autoplay_countdown");
+  await commands.playerCancelAutoplayCountdown();
 }
 
-export async function playNextEpisode(item: any): Promise<void> {
+export async function playNextEpisode(item: PlayItemRequest): Promise<void> {
-  return invoke("player_play_next_episode", { item });
+  await commands.playerPlayNextEpisode(item);
 }

src/lib/api/repository-client.ts

@@ -2,9 +2,8 @@
 // All API calls go through Tauri commands in src-tauri/src/commands/repository.rs
 // NO direct HTTP calls - everything routes through Rust backend
 
-import { invoke } from "@tauri-apps/api/core";
+import { commands } from "./bindings";
 import type { QualityPreset } from "./quality-presets";
-import { QUALITY_PRESETS } from "./quality-presets";
 import type {
   Library,
   MediaItem,
@@ -39,12 +38,7 @@ export class RepositoryClient {
     serverId: string
   ): Promise<string> {
     console.log("[RepositoryClient] Creating Rust repository...");
-    this.handle = await invoke<string>("repository_create", {
+    this.handle = await commands.repositoryCreate(serverUrl, userId, accessToken, serverId);
-      serverUrl,
-      userId,
-      accessToken,
-      serverId,
-    });
 
     // Store for URL construction
     this._serverUrl = serverUrl;
@@ -60,7 +54,7 @@ export class RepositoryClient {
    */
   async destroy(): Promise<void> {
     if (this.handle) {
-      await invoke("repository_destroy", { handle: this.handle });
+      await commands.repositoryDestroy(this.handle);
       this.handle = null;
       this._serverUrl = null;
       this._accessToken = null;
@@ -84,119 +78,67 @@ export class RepositoryClient {
   // ===== Library Methods (all via Rust) =====
 
   async getLibraries(): Promise<Library[]> {
-    return invoke<Library[]>("repository_get_libraries", {
+    return commands.repositoryGetLibraries(this.ensureHandle());
-      handle: this.ensureHandle(),
-    });
   }
 
   async getItems(parentId: string, options?: GetItemsOptions): Promise<SearchResult> {
-    return invoke<SearchResult>("repository_get_items", {
+    return commands.repositoryGetItems(this.ensureHandle(), parentId, options ?? null);
-      handle: this.ensureHandle(),
-      parentId,
-      options: options ?? null,
-    });
   }
 
   async getItem(itemId: string): Promise<MediaItem> {
-    return invoke<MediaItem>("repository_get_item", {
+    return commands.repositoryGetItem(this.ensureHandle(), itemId);
-      handle: this.ensureHandle(),
-      itemId,
-    });
   }
 
   async getLatestItems(parentId: string, limit?: number): Promise<MediaItem[]> {
-    return invoke<MediaItem[]>("repository_get_latest_items", {
+    return commands.repositoryGetLatestItems(this.ensureHandle(), parentId, limit ?? null);
-      handle: this.ensureHandle(),
-      parentId,
-      limit: limit ?? null,
-    });
   }
 
   async getResumeItems(parentId?: string, limit?: number): Promise<MediaItem[]> {
-    return invoke<MediaItem[]>("repository_get_resume_items", {
+    return commands.repositoryGetResumeItems(this.ensureHandle(), parentId ?? null, limit ?? null);
-      handle: this.ensureHandle(),
-      parentId: parentId ?? null,
-      limit: limit ?? null,
-    });
   }
 
   async getNextUpEpisodes(seriesId?: string, limit?: number): Promise<MediaItem[]> {
-    return invoke<MediaItem[]>("repository_get_next_up_episodes", {
+    return commands.repositoryGetNextUpEpisodes(this.ensureHandle(), seriesId ?? null, limit ?? null);
-      handle: this.ensureHandle(),
-      seriesId: seriesId ?? null,
-      limit: limit ?? null,
-    });
   }
 
   async getRecentlyPlayedAudio(limit?: number): Promise<MediaItem[]> {
-    return invoke<MediaItem[]>("repository_get_recently_played_audio", {
+    return commands.repositoryGetRecentlyPlayedAudio(this.ensureHandle(), limit ?? null);
-      handle: this.ensureHandle(),
-      limit: limit ?? null,
-    });
   }
 
   async getResumeMovies(limit?: number): Promise<MediaItem[]> {
-    return invoke<MediaItem[]>("repository_get_resume_movies", {
+    return commands.repositoryGetResumeMovies(this.ensureHandle(), limit ?? null);
-      handle: this.ensureHandle(),
-      limit: limit ?? null,
-    });
   }
 
   async getGenres(parentId?: string): Promise<Genre[]> {
-    return invoke<Genre[]>("repository_get_genres", {
+    return commands.repositoryGetGenres(this.ensureHandle(), parentId ?? null);
-      handle: this.ensureHandle(),
-      parentId: parentId ?? null,
-    });
   }
 
   async search(query: string, options?: SearchOptions): Promise<SearchResult> {
-    return invoke<SearchResult>("repository_search", {
+    return commands.repositorySearch(this.ensureHandle(), query, options ?? null);
-      handle: this.ensureHandle(),
-      query,
-      options: options ?? null,
-    });
   }
 
   // ===== Playback Methods (all via Rust) =====
 
   async getPlaybackInfo(itemId: string): Promise<PlaybackInfo> {
-    return invoke<PlaybackInfo>("repository_get_playback_info", {
+    return commands.repositoryGetPlaybackInfo(this.ensureHandle(), itemId);
-      handle: this.ensureHandle(),
-      itemId,
-    });
   }
 
   async reportPlaybackStart(itemId: string, positionTicks: number): Promise<void> {
-    return invoke("repository_report_playback_start", {
+    await commands.repositoryReportPlaybackStart(this.ensureHandle(), itemId, positionTicks);
-      handle: this.ensureHandle(),
-      itemId,
-      positionTicks,
-    });
   }
 
   async reportPlaybackProgress(itemId: string, positionTicks: number): Promise<void> {
-    return invoke("repository_report_playback_progress", {
+    await commands.repositoryReportPlaybackProgress(this.ensureHandle(), itemId, positionTicks);
-      handle: this.ensureHandle(),
-      itemId,
-      positionTicks,
-    });
   }
 
   async reportPlaybackStopped(itemId: string, positionTicks: number): Promise<void> {
-    return invoke("repository_report_playback_stopped", {
+    await commands.repositoryReportPlaybackStopped(this.ensureHandle(), itemId, positionTicks);
-      handle: this.ensureHandle(),
-      itemId,
-      positionTicks,
-    });
   }
 
   // ===== Stream URL Methods (via Rust) =====
 
   async getAudioStreamUrl(itemId: string): Promise<string> {
-    return invoke<string>("repository_get_audio_stream_url", {
+    return commands.repositoryGetAudioStreamUrl(this.ensureHandle(), itemId);
-      handle: this.ensureHandle(),
-      itemId,
-    });
   }
 
   async getVideoStreamUrl(
@@ -205,13 +147,13 @@ export class RepositoryClient {
     startTimeSeconds?: number,
     audioStreamIndex?: number
   ): Promise<string> {
-    return invoke<string>("repository_get_video_stream_url", {
+    return commands.repositoryGetVideoStreamUrl(
-      handle: this.ensureHandle(),
+      this.ensureHandle(),
       itemId,
-      mediaSourceId: mediaSourceId ?? null,
+      mediaSourceId ?? null,
-      startTimeSeconds: startTimeSeconds ?? null,
+      startTimeSeconds ?? null,
-      audioStreamIndex: audioStreamIndex ?? null,
+      audioStreamIndex ?? null
-    });
+    );
   }
 
   // ===== URL Construction Methods (sync, no server call) =====
@@ -221,12 +163,7 @@ export class RepositoryClient {
    * The Rust backend constructs and returns the URL with proper credentials handling
    */
   async getImageUrl(itemId: string, imageType: ImageType = "Primary", options?: ImageOptions): Promise<string> {
-    return invoke<string>("repository_get_image_url", {
+    return commands.repositoryGetImageUrl(this.ensureHandle(), itemId, imageType, options ?? null);
-      handle: this.ensureHandle(),
-      itemId,
-      imageType,
-      options: options ?? null,
-    });
   }
 
   /**
@@ -239,13 +176,7 @@ export class RepositoryClient {
     streamIndex: number,
     format: string = "vtt"
   ): Promise<string> {
-    return invoke<string>("repository_get_subtitle_url", {
+    return commands.repositoryGetSubtitleUrl(this.ensureHandle(), itemId, mediaSourceId, streamIndex, format);
-      handle: this.ensureHandle(),
-      itemId,
-      mediaSourceId,
-      streamIndex,
-      format,
-    });
   }
 
   /**
@@ -258,110 +189,61 @@ export class RepositoryClient {
     quality: QualityPreset = "original",
     mediaSourceId?: string
   ): Promise<string> {
-    return invoke<string>("repository_get_video_download_url", {
+    return commands.repositoryGetVideoDownloadUrl(this.ensureHandle(), itemId, quality, mediaSourceId ?? null);
-      handle: this.ensureHandle(),
-      itemId,
-      quality,
-      mediaSourceId: mediaSourceId ?? null,
-    });
   }
 
   // ===== Favorite Methods (via Rust) =====
 
   async markFavorite(itemId: string): Promise<void> {
-    return invoke("repository_mark_favorite", {
+    await commands.repositoryMarkFavorite(this.ensureHandle(), itemId);
-      handle: this.ensureHandle(),
-      itemId,
-    });
   }
 
   async unmarkFavorite(itemId: string): Promise<void> {
-    return invoke("repository_unmark_favorite", {
+    await commands.repositoryUnmarkFavorite(this.ensureHandle(), itemId);
-      handle: this.ensureHandle(),
-      itemId,
-    });
   }
 
   // ===== Person Methods (via Rust) =====
 
   async getPerson(personId: string): Promise<MediaItem> {
-    return invoke<MediaItem>("repository_get_person", {
+    return commands.repositoryGetPerson(this.ensureHandle(), personId);
-      handle: this.ensureHandle(),
-      personId,
-    });
   }
 
   async getItemsByPerson(personId: string, options?: GetItemsOptions): Promise<SearchResult> {
-    return invoke<SearchResult>("repository_get_items_by_person", {
+    return commands.repositoryGetItemsByPerson(this.ensureHandle(), personId, options ?? null);
-      handle: this.ensureHandle(),
-      personId,
-      options: options ?? null,
-    });
   }
 
   async getSimilarItems(itemId: string, limit?: number): Promise<SearchResult> {
-    return invoke<SearchResult>("repository_get_similar_items", {
+    return commands.repositoryGetSimilarItems(this.ensureHandle(), itemId, limit ?? null);
-      handle: this.ensureHandle(),
-      itemId,
-      limit: limit ?? null,
-    });
   }
 
   // ===== Playlist Methods (via Rust) =====
 
   async createPlaylist(name: string, itemIds?: string[]): Promise<PlaylistCreatedResult> {
-    return invoke<PlaylistCreatedResult>("playlist_create", {
+    return commands.playlistCreate(this.ensureHandle(), name, itemIds ?? null);
-      handle: this.ensureHandle(),
-      name,
-      itemIds: itemIds ?? null,
-    });
   }
 
   async deletePlaylist(playlistId: string): Promise<void> {
-    return invoke("playlist_delete", {
+    await commands.playlistDelete(this.ensureHandle(), playlistId);
-      handle: this.ensureHandle(),
-      playlistId,
-    });
   }
 
   async renamePlaylist(playlistId: string, name: string): Promise<void> {
-    return invoke("playlist_rename", {
+    await commands.playlistRename(this.ensureHandle(), playlistId, name);
-      handle: this.ensureHandle(),
-      playlistId,
-      name,
-    });
   }
 
   async getPlaylistItems(playlistId: string): Promise<PlaylistEntry[]> {
-    return invoke<PlaylistEntry[]>("playlist_get_items", {
+    return commands.playlistGetItems(this.ensureHandle(), playlistId);
-      handle: this.ensureHandle(),
-      playlistId,
-    });
   }
 
   async addToPlaylist(playlistId: string, itemIds: string[]): Promise<void> {
-    return invoke("playlist_add_items", {
+    await commands.playlistAddItems(this.ensureHandle(), playlistId, itemIds);
-      handle: this.ensureHandle(),
-      playlistId,
-      itemIds,
-    });
   }
 
   async removeFromPlaylist(playlistId: string, entryIds: string[]): Promise<void> {
-    return invoke("playlist_remove_items", {
+    await commands.playlistRemoveItems(this.ensureHandle(), playlistId, entryIds);
-      handle: this.ensureHandle(),
-      playlistId,
-      entryIds,
-    });
   }
 
   async movePlaylistItem(playlistId: string, itemId: string, newIndex: number): Promise<void> {
-    return invoke("playlist_move_item", {
+    await commands.playlistMoveItem(this.ensureHandle(), playlistId, itemId, newIndex);
-      handle: this.ensureHandle(),
-      playlistId,
-      itemId,
-      newIndex,
-    });
   }
 
   // ===== Getters =====

src/lib/api/types.ts

@@ -1,76 +1,41 @@
-// Jellyfin API Types
+// Frontend type layer.
+//
+// Wire types are the single source of truth, generated from Rust by tauri-specta
+// in ./bindings.ts. This module re-exports them under the names the frontend uses
+// and adds frontend-only unions/helpers that have no backend equivalent.
 
-export interface ServerInfo {
+export type {
-  id: string;
+  AuthResult,
-  name: string;
+  Genre,
-  url: string;
+  GetItemsOptions,
-}
+  ImageOptions,
+  ImageType,
+  Library,
+  MediaItem,
+  MediaSource,
+  MediaStream,
+  Person,
+  PlaybackInfo,
+  PlaylistCreatedResult,
+  PlaylistEntry,
+  PlayState,
+  SearchOptions,
+  SearchResult,
+  ServerInfo,
+  User,
+  UserData,
+} from "./bindings";
 
-export interface User {
+import type { SessionInfo } from "./bindings";
-  id: string;
-  name: string;
-  serverId: string;
-  primaryImageTag?: string;
-}
 
-export interface AuthResult {
+// The frontend's "Session" is the backend remote-control session (SessionInfo).
-  user: User;
+// (Note: bindings also has a `Session` type — that's the auth/login session, a
-  accessToken: string;
+// different concept — so we alias explicitly here rather than re-export it.)
-  serverId: string;
+export type Session = SessionInfo;
-}
 
-export interface Library {
+// ---------------------------------------------------------------------------
-  id: string;
+// Frontend-only types (not part of the Rust command surface)
-  name: string;
+// ---------------------------------------------------------------------------
-  collectionType: LibraryType;
-  imageTag?: string;
-}
-
-export type LibraryType = "movies" | "tvshows" | "music" | "books" | "photos" | "homevideos" | "boxsets" | "playlists" | "channels" | "unknown";
-
-export interface MediaItem {
-  id: string;
-  name: string;
-  type: ItemType;
-  serverId: string;
-
-  // Common fields
-  overview?: string;
-  productionYear?: number;
-  communityRating?: number;
-  officialRating?: string;
-  runTimeTicks?: number;
-
-  // Images
-  primaryImageTag?: string;
-  backdropImageTags?: string[];
-  parentBackdropImageTags?: string[];
-
-  // For audio
-  albumId?: string;
-  albumName?: string;
-  artists?: string[];
-  artistItems?: { id: string; name: string }[];
-  indexNumber?: number; // Track number
-  parentIndexNumber?: number; // Disc number
-
-  // For video
-  seriesId?: string;
-  seriesName?: string;
-  seasonId?: string;
-  seasonName?: string;
-
-  // Playback
-  userData?: UserData;
-  mediaStreams?: MediaStream[];
-  mediaSources?: MediaSource[];
-
-  // Cast & Crew
-  people?: Person[];
-
-  // Genres
-  genres?: string[];
-}
 
 export type ItemType =
   | "Movie"
@@ -87,7 +52,18 @@ export type ItemType =
   | "ChannelFolderItem"
   | "Person";
 
-// Person/Cast types
+export type LibraryType =
+  | "movies"
+  | "tvshows"
+  | "music"
+  | "books"
+  | "photos"
+  | "homevideos"
+  | "boxsets"
+  | "playlists"
+  | "channels"
+  | "unknown";
+
 export type PersonType =
   | "Actor"
   | "Director"
@@ -99,81 +75,6 @@ export type PersonType =
   | "Conductor"
   | "Lyricist";
 
-export interface Person {
-  id: string;
-  name: string;
-  role?: string; // Character name for actors
-  type: PersonType;
-  primaryImageTag?: string;
-}
-
-export interface UserData {
-  playbackPositionTicks: number;
-  playCount: number;
-  isFavorite: boolean;
-  played: boolean;
-  lastPlayedDate?: string;
-}
-
-export interface MediaStream {
-  type: "Video" | "Audio" | "Subtitle";
-  codec?: string;
-  language?: string;
-  displayTitle?: string;
-  index: number;
-  isDefault: boolean;
-  isForced: boolean;
-}
-
-export interface MediaSource {
-  id: string;
-  name: string;
-  container?: string;
-  size?: number;
-  bitrate?: number;
-  supportsDirectPlay: boolean;
-  supportsDirectStream: boolean;
-  supportsTranscoding: boolean;
-  directStreamUrl?: string;
-}
-
-export interface PlaybackInfo {
-  mediaSourceId: string;
-  playSessionId: string;
-  streamUrl: string;
-  directPlay: boolean;
-  /** True if content requires transcoding (HEVC, 10-bit) - seeking requires server-side StartTimeTicks */
-  needsTranscoding: boolean;
-}
-
-// Remote session control types
-export interface Session {
-  id: string;
-  userId: string;
-  userName: string;
-  client: string;
-  deviceName: string;
-  deviceId: string;
-  applicationVersion: string;
-  isActive: boolean;
-  supportsMediaControl: boolean;
-  supportsRemoteControl: boolean;
-  playState: PlayState | null;
-  nowPlayingItem: MediaItem | null;
-  playableMediaTypes: string[];
-  supportedCommands: string[];
-}
-
-export interface PlayState {
-  positionTicks: number;
-  canSeek: boolean;
-  isPaused: boolean;
-  isMuted: boolean;
-  volumeLevel: number;
-  repeatMode: string;
-  shuffleMode: string;
-}
-
 export type SessionCommand =
   | "PlayPause"
   | "Stop"
@@ -183,94 +84,3 @@ export type SessionCommand =
   | "PreviousTrack"
   | "Mute"
   | "Unmute";
-
-export interface SearchResult {
-  items: MediaItem[];
-  totalRecordCount: number;
-}
-
-// Repository pattern for offline support
-export interface MediaRepository {
-  // Libraries
-  getLibraries(): Promise<Library[]>;
-
-  // Items
-  getItems(parentId: string, options?: GetItemsOptions): Promise<SearchResult>;
-  getItem(itemId: string): Promise<MediaItem>;
-  getLatestItems(parentId: string, limit?: number): Promise<MediaItem[]>;
-
-  // Home screen
-  getResumeItems(parentId?: string, limit?: number): Promise<MediaItem[]>;
-  getNextUpEpisodes(seriesId?: string, limit?: number): Promise<MediaItem[]>;
-  getRecentlyPlayedAudio(limit?: number): Promise<MediaItem[]>;
-  getResumeMovies(limit?: number): Promise<MediaItem[]>;
-
-  // Genres
-  getGenres(parentId?: string): Promise<Genre[]>;
-
-  // Search
-  search(query: string, options?: SearchOptions): Promise<SearchResult>;
-
-  // Playback
-  getPlaybackInfo(itemId: string): Promise<PlaybackInfo>;
-  reportPlaybackStart(itemId: string, positionTicks: number): Promise<void>;
-  reportPlaybackProgress(itemId: string, positionTicks: number): Promise<void>;
-  reportPlaybackStopped(itemId: string, positionTicks: number): Promise<void>;
-
-  // Images
-  getImageUrl(itemId: string, imageType: ImageType, options?: ImageOptions): string;
-
-  // Subtitles
-  getSubtitleUrl(itemId: string, mediaSourceId: string, streamIndex: number, format?: string): string;
-
-  // Favorites
-  markFavorite(itemId: string): Promise<void>;
-  unmarkFavorite(itemId: string): Promise<void>;
-
-  // People/Cast
-  getPerson(personId: string): Promise<MediaItem>;
-  getItemsByPerson(personId: string, options?: GetItemsOptions): Promise<SearchResult>;
-
-  // Related Content
-  getSimilarItems(itemId: string, limit?: number): Promise<SearchResult>;
-}
-
-export interface Genre {
-  id: string;
-  name: string;
-}
-
-// Playlist types
-export interface PlaylistEntry extends MediaItem {
-  playlistItemId: string;
-}
-
-export interface PlaylistCreatedResult {
-  id: string;
-}
-
-export interface GetItemsOptions {
-  startIndex?: number;
-  limit?: number;
-  sortBy?: string;
-  sortOrder?: "Ascending" | "Descending";
-  includeItemTypes?: ItemType[];
-  recursive?: boolean;
-  fields?: string[];
-  genres?: string[];
-}
-
-export interface SearchOptions {
-  limit?: number;
-  includeItemTypes?: ItemType[];
-  searchTerm?: string;
-}
-
-export type ImageType = "Primary" | "Backdrop" | "Banner" | "Thumb" | "Logo";
-
-export interface ImageOptions {
-  maxWidth?: number;
-  maxHeight?: number;
-  quality?: number;
-  tag?: string;
-}

src/lib/components/common/CachedImage.svelte

@@ -1,12 +1,12 @@
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { auth } from "$lib/stores/auth";
   import { get } from "svelte/store";
 
   interface Props {
     itemId: string;
     imageType?: string;
-    tag?: string;
+    tag?: string | null;
     maxWidth?: number;
     maxHeight?: number;
     class?: string;
@@ -47,15 +47,12 @@
       const repositoryHandle = repository.getHandle();
 
       // Call Rust to get image as base64 data URL
-      const dataUrl = await invoke<string>("image_get_url", {
+      const dataUrl = await commands.imageGetUrl(repositoryHandle, {
-        repositoryHandle,
+        itemId,
-        request: {
+        imageType,
-          itemId,
+        maxWidth,
-          imageType,
+        maxHeight,
-          maxWidth,
+        tag,
-          maxHeight,
-          tag,
-        },
       });
 
       // Use data URL directly

src/lib/components/downloads/StorageManagement.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { auth } from "$lib/stores/auth";
   import { downloads } from "$lib/stores/downloads";
   import { goto } from "$app/navigation";
@@ -34,7 +34,7 @@
       loading = true;
       const userId = $auth.user?.id;
       if (userId) {
-        stats = await invoke<StorageStats>("get_download_storage_stats", { userId });
+        stats = await commands.getDownloadStorageStats(userId);
       }
     } catch (error) {
       console.error("Failed to load storage stats:", error);
@@ -56,7 +56,7 @@
       deleting = true;
       const userId = $auth.user?.id;
       if (userId) {
-        await invoke("delete_all_downloads", { userId });
+        await commands.deleteAllDownloads(userId);
         await downloads.refresh(userId);
         await loadStats();
       }
@@ -73,7 +73,7 @@
       deletingAlbum = albumId;
       const userId = $auth.user?.id;
       if (userId) {
-        await invoke("delete_album_downloads", { albumId, userId });
+        await commands.deleteAlbumDownloads(albumId, userId);
         await downloads.refresh(userId);
         await loadStats();
       }

src/lib/components/library/AlbumDownloadButton.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { downloads } from "$lib/stores/downloads";
   import { auth } from "$lib/stores/auth";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import type { MediaItem } from "$lib/api/types";
 
   interface Props {
@@ -89,18 +89,14 @@
         const downloadIds = await downloads.downloadAlbum(albumId, userId, basePath);
 
         // Get target directory for downloads
-        const targetDir = await invoke<string>("storage_get_path");
+        const targetDir = await commands.storageGetPath();
 
         // Start each queued track download
         for (let i = 0; i < tracks.length && i < downloadIds.length; i++) {
           try {
             const streamUrl = await repo.getAudioStreamUrl(tracks[i].id);
             if (streamUrl) {
-              await invoke("start_download", {
+              await commands.startDownload(downloadIds[i], streamUrl, targetDir);
-                downloadId: downloadIds[i],
-                streamUrl,
-                targetDir,
-              });
             }
           } catch (e) {
             console.error(`Failed to start download for track ${tracks[i].id}:`, e);

src/lib/components/library/CastSection.svelte

@@ -28,6 +28,7 @@
         continue;
       }
       const type = person.type;
+      if (!type) continue;
       if (type in groups) {
         groups[type].push(person);
       } else {
@@ -84,7 +85,7 @@
               <!-- Person image -->
               <div class="w-24 h-24 rounded-full overflow-hidden bg-[var(--color-surface)] mb-2">
                 <CachedImage
-                  itemId={person.id}
+                  itemId={person.id ?? ""}
                   imageType="Primary"
                   tag={person.primaryImageTag}
                   maxWidth={200}

src/lib/components/library/CrewLinks.svelte

@@ -55,7 +55,7 @@
     <div class="flex flex-wrap gap-1">
       {#each filteredPeople as person, index (person.id)}
         <button
-          onclick={(e) => handlePersonClick(person.id, e)}
+          onclick={(e) => handlePersonClick(person.id ?? "", e)}
           class="text-[var(--color-jellyfin)] hover:underline"
         >
           {person.name}

src/lib/components/library/DownloadButton.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { downloads } from "$lib/stores/downloads";
   import { auth } from "$lib/stores/auth";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import DownloadButtonCore from "./DownloadButtonCore.svelte";
   import type { DownloadState } from "./DownloadButtonCore.svelte";
 
@@ -80,18 +80,18 @@
           }
 
           // Get target directory
-          const targetDir = await invoke<string>("storage_get_path");
+          const targetDir = await commands.storageGetPath();
           console.log("   Target directory:", targetDir);
 
           // Queue and start download in single atomic operation
-          const downloadId = await invoke<number>("download_item_and_start", {
+          const downloadId = await commands.downloadItemAndStart({
             itemId,
             userId,
             streamUrl,
             targetDir,
-            itemName: itemName || undefined,
+            itemName: itemName || null,
-            artistName: artistName || undefined,
+            artistName: artistName || null,
-            albumName: albumName || undefined,
+            albumName: albumName || null,
           });
           console.log("   Download queued and started with ID:", downloadId);
 

src/lib/components/library/EpisodeFocusView.svelte

@@ -84,7 +84,7 @@
     return null;
   });
 
-  function formatDuration(ticks?: number): string {
+  function formatDuration(ticks?: number | null): string {
     if (!ticks) return "";
     const seconds = Math.floor(ticks / 10000000);
     const hours = Math.floor(seconds / 3600);
@@ -100,7 +100,7 @@
     if (!ep.userData || !ep.runTimeTicks) {
       return 0;
     }
-    return (ep.userData.playbackPositionTicks / ep.runTimeTicks) * 100;
+    return ((ep.userData.playbackPositionTicks ?? 0) / ep.runTimeTicks) * 100;
   }
 
   function handlePlay() {
@@ -178,7 +178,7 @@
               {episode.communityRating.toFixed(1)}
             </span>
           {/if}
-          {#if episode.userData?.played}
+          {#if episode.userData?.isPlayed}
             <span class="flex items-center gap-1 text-[var(--color-jellyfin)]">
               <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
                 <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>
@@ -281,7 +281,7 @@
             {/if}
 
             <!-- Played indicator -->
-            {#if ep.userData?.played}
+            {#if ep.userData?.isPlayed}
               <div class="absolute top-2 right-2">
                 <svg class="w-5 h-5 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24">
                   <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>

src/lib/components/library/EpisodeRow.svelte

@@ -40,7 +40,7 @@
     if (!episode.userData || !episode.runTimeTicks) {
       return 0;
     }
-    return (episode.userData.playbackPositionTicks / episode.runTimeTicks) * 100;
+    return ((episode.userData.playbackPositionTicks ?? 0) / episode.runTimeTicks) * 100;
   });
 
   const duration = $derived(formatDuration(episode.runTimeTicks));
@@ -137,7 +137,7 @@
             {episode.name}
           </h3>
           <!-- Played indicator -->
-          {#if episode.userData?.played}
+          {#if episode.userData?.isPlayed}
             <svg class="w-4 h-4 flex-shrink-0 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24">
               <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>
             </svg>
@@ -164,10 +164,10 @@
           <VideoDownloadButton
             itemId={episode.id}
             itemName={episode.name}
-            seriesName={episode.seriesName}
+            seriesName={episode.seriesName ?? undefined}
-            seasonName={episode.seasonName}
+            seasonName={episode.seasonName ?? undefined}
-            episodeNumber={episode.indexNumber}
+            episodeNumber={episode.indexNumber ?? undefined}
-            seasonNumber={episode.parentIndexNumber}
+            seasonNumber={episode.parentIndexNumber ?? undefined}
             size="sm"
           />
         </div>

src/lib/components/library/LibraryListView.svelte

@@ -18,7 +18,7 @@
   }
 
   function getImageTag(item: MediaItem | Library): string | undefined {
-    return "primaryImageTag" in item ? item.primaryImageTag : ("imageTag" in item ? item.imageTag : undefined);
+    return "primaryImageTag" in item ? (item.primaryImageTag ?? undefined) : ("imageTag" in item ? (item.imageTag ?? undefined) : undefined);
   }
 
   function getSubtitle(item: MediaItem | Library): string {
@@ -44,7 +44,7 @@
     if (!showProgress || !("userData" in item) || !item.userData || !("runTimeTicks" in item) || !item.runTimeTicks) {
       return 0;
     }
-    return (item.userData.playbackPositionTicks / item.runTimeTicks) * 100;
+    return ((item.userData.playbackPositionTicks ?? 0) / item.runTimeTicks) * 100;
   }
 
   function getTrackNumber(item: MediaItem | Library): string {
@@ -61,7 +61,7 @@
     {@const duration = "runTimeTicks" in item ? formatDuration(item.runTimeTicks) : ""}
     {@const progress = getProgress(item)}
     {@const trackNum = getTrackNumber(item)}
-    {@const isPlayed = "userData" in item && item.userData?.played}
+    {@const isPlayed = "userData" in item && item.userData?.isPlayed}
     {@const downloadInfo = getDownloadInfo(item.id)}
     {@const isDownloaded = downloadInfo?.status === "completed"}
     {@const isDownloading = downloadInfo?.status === "downloading" || downloadInfo?.status === "pending"}

src/lib/components/library/MediaCard.svelte

@@ -52,7 +52,7 @@
     if (!showProgress || !("userData" in item) || !item.userData || !item.runTimeTicks) {
       return 0;
     }
-    return (item.userData.playbackPositionTicks / item.runTimeTicks) * 100;
+    return ((item.userData.playbackPositionTicks ?? 0) / item.runTimeTicks) * 100;
   });
 
   const subtitle = $derived(() => {
@@ -112,7 +112,7 @@
     {/if}
 
     <!-- Played indicator -->
-    {#if "userData" in item && item.userData?.played}
+    {#if "userData" in item && item.userData?.isPlayed}
       <div class="absolute top-2 right-2">
         <svg class="w-5 h-5 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24">
           <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>

src/lib/components/library/PlaylistDetailView.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { onMount } from "svelte";
   import { goto } from "$app/navigation";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import type { MediaItem, PlaylistEntry } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
   import { toast } from "$lib/stores/toast";
@@ -51,17 +51,14 @@
       const repo = auth.getRepository();
       const repositoryHandle = repo.getHandle();
       const trackIds = entries.map(e => e.id);
-      await invoke("player_play_tracks", {
+      await commands.playerPlayTracks(repositoryHandle, {
-        repositoryHandle,
+        trackIds,
-        request: {
+        startIndex: 0,
-          trackIds,
+        shuffle: false,
-          startIndex: 0,
+        context: {
-          shuffle: false,
+          type: "playlist",
-          context: {
+          playlistId: playlist.id,
-            type: "playlist",
+          playlistName: playlist.name,
-            playlistId: playlist.id,
-            playlistName: playlist.name,
-          },
         },
       });
     } catch (e) {
@@ -76,17 +73,14 @@
       const repo = auth.getRepository();
       const repositoryHandle = repo.getHandle();
       const trackIds = entries.map(e => e.id);
-      await invoke("player_play_tracks", {
+      await commands.playerPlayTracks(repositoryHandle, {
-        repositoryHandle,
+        trackIds,
-        request: {
+        startIndex: 0,
-          trackIds,
+        shuffle: true,
-          startIndex: 0,
+        context: {
-          shuffle: true,
+          type: "playlist",
-          context: {
+          playlistId: playlist.id,
-            type: "playlist",
+          playlistName: playlist.name,
-            playlistId: playlist.id,
-            playlistName: playlist.name,
-          },
         },
       });
     } catch (e) {

src/lib/components/library/SeasonDownloadButton.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { downloads, videoDownloads } from "$lib/stores/downloads";
   import { auth } from "$lib/stores/auth";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { QUALITY_PRESETS, type QualityPreset } from "$lib/api/quality-presets";
 
   interface Props {
@@ -53,7 +53,7 @@
       console.log("📺 Starting season download for:", seasonName, "quality:", quality);
 
       // Get target directory
-      const targetDir = await invoke<string>("storage_get_path");
+      const targetDir = await commands.storageGetPath();
       const basePath = `${targetDir}/videos`;
 
       // Queue all episodes in this season

src/lib/components/library/SeriesDownloadButton.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { downloads, videoDownloads } from "$lib/stores/downloads";
   import { auth } from "$lib/stores/auth";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { QUALITY_PRESETS, type QualityPreset } from "$lib/api/quality-presets";
 
   interface Props {
@@ -47,7 +47,7 @@
       console.log("📺 Starting series download for:", seriesName, "quality:", quality);
 
       // Get target directory
-      const targetDir = await invoke<string>("storage_get_path");
+      const targetDir = await commands.storageGetPath();
       const basePath = `${targetDir}/videos`;
 
       // Queue all episodes

src/lib/components/library/TrackList.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
+  import type { PlayTracksContext } from "$lib/api/bindings";
   import { goto } from "$app/navigation";
   import { queue } from "$lib/stores/queue";
   import { auth } from "$lib/stores/auth";
@@ -62,14 +63,11 @@
       if (context && context.type === "album") {
         const repositoryHandle = repo.getHandle();
         console.log(`[TrackList] Playing track: "${track.name}" (ID: ${track.id}, index in list: ${index})`);
-        await invoke("player_play_album_track", {
+        await commands.playerPlayAlbumTrack(repositoryHandle, {
-          repositoryHandle,
+          albumId: context.albumId,
-          request: {
+          albumName: context.albumName,
-            albumId: context.albumId,
+          trackId: track.id,
-            albumName: context.albumName,
+          shuffle: false,
-            trackId: track.id,
-            shuffle: false,
-          },
         });
         return;
       }
@@ -80,7 +78,7 @@
       const trackIds = tracks.map((t) => t.id);
 
       // Determine context for queue
-      let playContext;
+      let playContext: PlayTracksContext;
       if (context?.type === "playlist") {
         playContext = {
           type: "playlist",
@@ -88,17 +86,14 @@
           playlistName: context.playlistName,
         };
       } else {
-        playContext = { type: "custom" };
+        playContext = { type: "custom", label: null };
       }
 
-      await invoke("player_play_tracks", {
+      await commands.playerPlayTracks(repositoryHandle, {
-        repositoryHandle,
+        trackIds,
-        request: {
+        startIndex: index,
-          trackIds,
+        shuffle: false,
-          startIndex: index,
+        context: playContext,
-          shuffle: false,
-          context: playContext,
-        },
       });
 
       // Queue will auto-update from Rust backend event
@@ -145,7 +140,7 @@
     goto(`/library/${artistId}`);
   }
 
-  function handleAlbumClick(albumId: string | undefined, e: Event) {
+  function handleAlbumClick(albumId: string | null | undefined, e: Event) {
     if (!albumId) return;
     e.stopPropagation();
     goto(`/library/${albumId}`);

src/lib/components/library/VideoDownloadButton.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { downloads } from "$lib/stores/downloads";
   import { auth } from "$lib/stores/auth";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { QUALITY_PRESETS, type QualityPreset } from "$lib/api/quality-presets";
 
   interface Props {
@@ -66,11 +66,11 @@
       console.log("🎬 Starting video download for item:", itemId, "quality:", quality);
 
       // Get stream URL based on quality
-      const streamUrl = repo.getVideoDownloadUrl(itemId, quality);
+      const streamUrl = await repo.getVideoDownloadUrl(itemId, quality);
       console.log("   Stream URL obtained");
 
       // Get target directory
-      const targetDir = await invoke<string>("storage_get_path");
+      const targetDir = await commands.storageGetPath();
 
       // Create file path
       const safeName = (itemName || itemId).replace(/[/\\:*?"<>|]/g, "_");
@@ -107,11 +107,7 @@
       await downloads.pinItem(itemId);
 
       // Actually start the download
-      await invoke("start_download", {
+      await commands.startDownload(downloadId, streamUrl, targetDir);
-        downloadId,
-        streamUrl,
-        targetDir,
-      });
       console.log("   Download started");
     } catch (error) {
       console.error("Failed to start video download:", error);

src/lib/components/player/AudioPlayer.svelte

@@ -1,6 +1,6 @@
 <!-- TRACES: UR-004, UR-005, UR-028 | DR-009 -->
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { goto } from "$app/navigation";
   import type { MediaItem } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
@@ -74,28 +74,28 @@
   async function handleSeekEnd() {
     seeking = false;
     seekPending = true; // Keep showing target position until backend catches up
-    await invoke("player_seek", { position: seekValue });
+    await commands.playerSeek(seekValue);
   }
 
   // Control handlers for Controls component
   async function handlePlayPause() {
-    await invoke("player_toggle");
+    await commands.playerToggle();
   }
 
   async function handlePrevious() {
-    await invoke("player_previous");
+    await commands.playerPrevious();
   }
 
   async function handleNext() {
-    await invoke("player_next");
+    await commands.playerNext();
   }
 
   async function handleToggleShuffle() {
-    await invoke("player_toggle_shuffle");
+    await commands.playerToggleShuffle();
   }
 
   async function handleCycleRepeat() {
-    await invoke("player_cycle_repeat");
+    await commands.playerCycleRepeat();
   }
 
   // Prefer album ID for artwork (all tracks in an album share the same cover)
@@ -128,7 +128,7 @@
   async function handleQueueItemClick(index: number) {
     try {
       queue.skipTo(index);
-      await invoke("player_skip_to", { index });
+      await commands.playerSkipTo(index);
     } catch (e) {
       console.error("Failed to skip to queue item:", e);
     }

src/lib/components/player/MiniPlayer.svelte

@@ -14,7 +14,7 @@
    * @req: UR-010 - Control playback of Jellyfin remote sessions
    */
 
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { goto } from "$app/navigation";
   import type { MediaItem } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
@@ -105,23 +105,23 @@
 
   // Control handlers for Controls component
   async function handlePlayPause() {
-    await invoke("player_toggle");
+    await commands.playerToggle();
   }
 
   async function handlePrevious() {
-    await invoke("player_previous");
+    await commands.playerPrevious();
   }
 
   async function handleNext() {
-    await invoke("player_next");
+    await commands.playerNext();
   }
 
   async function handleToggleShuffle() {
-    await invoke("player_toggle_shuffle");
+    await commands.playerToggleShuffle();
   }
 
   async function handleCycleRepeat() {
-    await invoke("player_cycle_repeat");
+    await commands.playerCycleRepeat();
   }
 
   // Scrubbing (seek) handler
@@ -133,7 +133,7 @@
     const newPosition = percent * displayDuration;
 
     try {
-      await invoke("player_seek", { position: newPosition });
+      await commands.playerSeek(newPosition);
       haptics.tap();
     } catch (err) {
       console.error("Failed to seek:", err);

src/lib/components/player/Queue.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { dndzone, SOURCES, TRIGGERS } from "svelte-dnd-action";
   import type { MediaItem } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
@@ -35,7 +35,7 @@
   let dragDisabled = $state(true);
   const flipDurationMs = 200;
 
-  function formatDuration(ticks?: number): string {
+  function formatDuration(ticks?: number | null): string {
     if (!ticks) return "";
     const seconds = Math.floor(ticks / 10000000);
     const mins = Math.floor(seconds / 60);
@@ -79,10 +79,7 @@
         queue.moveInQueue(fromIndex, toIndex);
 
         // Sync with backend
-        await invoke("player_move_in_queue", {
+        await commands.playerMoveInQueue(fromIndex, toIndex);
-          fromIndex,
-          toIndex,
-        });
       } catch (e) {
         console.error("Failed to move queue item:", e);
         // The store already updated optimistically, refresh if needed
@@ -109,7 +106,7 @@
     e.stopPropagation();
     try {
       queue.removeFromQueue(index);
-      await invoke("player_remove_from_queue", { index });
+      await commands.playerRemoveFromQueue(index);
     } catch (err) {
       console.error("Failed to remove from queue:", err);
     }

src/lib/components/player/VideoPlayer.svelte

@@ -1,7 +1,7 @@
 <!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026 | DR-010, DR-023, DR-024 -->
 <script lang="ts">
-  import { onMount, onDestroy } from "svelte";
+  import { onMount, onDestroy, untrack } from "svelte";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { listen } from "@tauri-apps/api/event";
   import Hls from "hls.js";
   import type { MediaItem } from "$lib/api/types";
@@ -20,9 +20,13 @@
     needsTranscoding?: boolean; // Whether content needs transcoding (HEVC/10-bit) - affects seeking behavior
     onClose: () => void;
     onSeek?: (positionSeconds: number, audioStreamIndex?: number) => Promise<string>; // Returns new stream URL for transcoded seeking
-    onReportProgress?: (positionSeconds: number, isPaused: boolean) => void;
+    // Reporting callbacks pass the played media's id explicitly so a late
-    onReportStart?: (positionSeconds: number) => void;
+    // reportStop (fired from onDestroy during autoplay navigation) is attributed
-    onReportStop?: (positionSeconds: number) => void;
+    // to the episode this player actually played, not the next episode whose URL
+    // is already active on the page.
+    onReportProgress?: (positionSeconds: number, isPaused: boolean, reportId?: string) => void;
+    onReportStart?: (positionSeconds: number, reportId?: string) => void;
+    onReportStop?: (positionSeconds: number, reportId?: string) => void;
     onEnded?: () => void; // Called when video playback ends naturally
     onNext?: () => void; // Called when user clicks next episode button
     hasNext?: boolean; // Whether there is a next episode available
@@ -30,6 +34,12 @@
 
   let { media, streamUrl, mediaSourceId, initialPosition, needsTranscoding = false, onClose, onSeek, onReportProgress, onReportStart, onReportStop, onEnded, onNext, hasNext = false }: Props = $props();
 
+  // The id this player instance reports progress against. Snapshotted from the
+  // media prop so a late reportStop (e.g. from onDestroy during autoplay
+  // navigation) is always attributed to the episode this player played.
+  // untrack() makes the intent explicit: capture the initial value only.
+  const reportMediaId = untrack(() => media?.id);
+
   let videoElement: HTMLVideoElement | null = $state(null);
   let isPlaying = $state(false);
   let currentTime = $state(0);
@@ -140,13 +150,7 @@
       const userId = auth.getUserId();
       if (!userId) return;
 
-      const preference = await invoke<{ seriesId: string, audioTrackDisplayTitle?: string | null, audioTrackLanguage?: string | null, audioTrackIndex?: number | null } | null>(
+      const preference = await commands.storageGetSeriesAudioPreference(userId, media.seriesId);
-        "storage_get_series_audio_preference",
-        {
-          userId,
-          seriesId: media.seriesId
-        }
-      );
 
       if (preference) {
         console.log("[VideoPlayer] Loaded series audio preference:", preference);
@@ -403,14 +407,12 @@
         // Call Rust backend to start playback
         // Rust will choose ExoPlayer (Android), libmpv (Linux), or tell us to use HTML5
         // Send minimal video data - no complex serialization to avoid Tauri Android issues
-        const response: any = await invoke("player_play_item", {
+        const response: any = await commands.playerPlayItem({
-          item: {
+          streamUrl: currentStreamUrl,
-            streamUrl: currentStreamUrl,
+          title: media.name,
-            title: media.name,
+          id: media.id,
-            id: media.id,
+          videoCodec: needsTranscoding ? "hevc" : "h264",
-            videoCodec: needsTranscoding ? "hevc" : "h264",
+          needsTranscoding: needsTranscoding,
-            needsTranscoding: needsTranscoding,
-          },
         });
 
         // Rust tells us which backend it's using
@@ -422,7 +424,7 @@
         if (useHtml5Element && !needsTranscoding) {
           try {
             console.log("[VideoPlayer] Using HTML5 for direct stream - stopping backend player to prevent dual audio");
-            await invoke("player_stop");
+            await commands.playerStop();
             didStopBackendEarly = true; // Track that we stopped the backend
           } catch (err) {
             console.warn("[VideoPlayer] Failed to stop backend player:", err);
@@ -460,7 +462,7 @@
         // For non-transcoded content, try to stop any backend player that might have started
         if (!needsTranscoding) {
           try {
-            await invoke("player_stop");
+            await commands.playerStop();
             didStopBackendEarly = true;
           } catch (stopErr) {
             // Ignore errors when stopping
@@ -478,7 +480,7 @@
     // Report progress every 10 seconds while playing
     progressInterval = setInterval(() => {
       if (isPlaying && !isSeeking && onReportProgress) {
-        onReportProgress(currentTime, false);
+        onReportProgress(currentTime, false, reportMediaId);
       }
     }, 10000);
 
@@ -536,7 +538,7 @@
     if (didStartNativePlayback && !didStopBackendEarly) {
       try {
         console.log("[VideoPlayer] Stopping backend player on component unmount");
-        await invoke("player_stop");
+        await commands.playerStop();
       } catch (err) {
         console.error("[VideoPlayer] Failed to stop backend player:", err);
       }
@@ -544,7 +546,7 @@
 
     // Report stop when component is destroyed
     if (onReportStop && currentTime > 0) {
-      onReportStop(currentTime);
+      onReportStop(currentTime, reportMediaId);
     }
   });
 
@@ -738,7 +740,7 @@
     startTimeUpdates(); // Start RAF loop for smooth time updates
     // Report playback start on first play
     if (!hasReportedStart && onReportStart) {
-      onReportStart(currentTime);
+      onReportStart(currentTime, reportMediaId);
       hasReportedStart = true;
     }
   }
@@ -748,7 +750,7 @@
     stopTimeUpdates(); // Stop RAF loop when paused
     // Report progress when paused
     if (onReportProgress) {
-      onReportProgress(currentTime, true);
+      onReportProgress(currentTime, true, reportMediaId);
     }
   }
 
@@ -757,7 +759,7 @@
     stopTimeUpdates(); // Stop RAF loop when ended
     // Report stop when video ends
     if (onReportStop) {
-      onReportStop(currentTime);
+      onReportStop(currentTime, reportMediaId);
     }
     // Notify parent that video has ended (for next episode popup)
     if (onEnded) {
@@ -768,7 +770,7 @@
   async function togglePlayPause() {
     if (!useHtml5Element) {
       try {
-        const response = await invoke<{ state: string }>("player_toggle");
+        const response = (await commands.playerToggle()) as any;
         isPlaying = response.state === "playing";
       } catch (err) {
         console.error("[VideoPlayer] Failed to toggle native player:", err);
@@ -807,13 +809,13 @@
       }
 
       // Backend smart seeking handles both native and HTML5
-      const response = await invoke<{strategy: string, position?: number, newUrl?: string, seekOffset?: number}>("player_seek_video", {
+      const response = (await commands.playerSeekVideo(
-        repositoryHandle: repo.getHandle(),
+        repo.getHandle(),
-        position: targetTime,
+        targetTime,
-        mediaSourceId: mediaSourceId ?? null,
+        mediaSourceId ?? null,
-        audioStreamIndex: selectedAudioTrackIndex ?? null,
+        selectedAudioTrackIndex ?? null,
-        useHtml5: useHtml5Element,
+        useHtml5Element
-      });
+      )) as any;
 
       console.log("[VideoPlayer] Backend seek response:", response);
 
@@ -1095,14 +1097,14 @@
       if (!repo) throw new Error("Not authenticated");
 
       // Call unified backend command
-      const response = await invoke<{strategy: string, success?: boolean, newUrl?: string, position?: number}>("player_switch_audio_track", {
+      const response = (await commands.playerSwitchAudioTrack(
-        repositoryHandle: repo.getHandle(),
+        repo.getHandle(),
         streamIndex,
         arrayIndex,
-        useHtml5: useHtml5Element,
+        useHtml5Element,
-        currentPosition: useHtml5Element && videoElement ? videoElement.currentTime + seekOffset : null,
+        useHtml5Element && videoElement ? videoElement.currentTime + seekOffset : null,
-        mediaSourceId: mediaSourceId ?? null,
+        mediaSourceId ?? null
-      });
+      )) as any;
 
       // Handle response based on strategy
       if (response.strategy === "reloadStream" && useHtml5Element && videoElement) {
@@ -1171,14 +1173,14 @@
           // Find the selected track info
           const selectedTrack = audioTracks().find(t => t.index === streamIndex);
           if (selectedTrack) {
-            await invoke("storage_save_series_audio_preference", {
+            await commands.storageSaveSeriesAudioPreference(
               userId,
-              seriesId: media.seriesId,
+              media.seriesId,
-              serverId: media.serverId,
+              media.serverId ?? "",
-              audioTrackDisplayTitle: selectedTrack.displayTitle || null,
+              selectedTrack.displayTitle || null,
-              audioTrackLanguage: selectedTrack.language || null,
+              selectedTrack.language || null,
-              audioTrackIndex: streamIndex,
+              streamIndex
-            });
+            );
             console.log("[VideoPlayer] Saved series audio preference:", selectedTrack.displayTitle || selectedTrack.language);
           }
         } catch (err) {
@@ -1229,7 +1231,7 @@
         // Use array index for ExoPlayer (0-based position in subtitle tracks array)
         // If streamIndex is null (disable), pass null; otherwise use arrayIndex
         const indexToUse = streamIndex === null ? null : (arrayIndex !== undefined ? arrayIndex : streamIndex);
-        await invoke("player_set_subtitle_track", { streamIndex: indexToUse });
+        await commands.playerSetSubtitleTrack(indexToUse);
         console.log("[VideoPlayer] Native backend subtitle track changed - arrayIndex:", arrayIndex, "used:", indexToUse);
       } catch (error) {
         console.error("[VideoPlayer] Failed to set subtitle track:", error);

src/lib/components/player/VolumeControl.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { volume, isMuted, mergedVolume } from "$lib/stores/player";
   import { isRemoteMode } from "$lib/stores/playbackMode";
   import { selectedSession, sessions } from "$lib/stores/sessions";
@@ -31,7 +31,7 @@
       // Remote mode: send volume as 0-100 integer to remote session
       await sessions.sendVolume($selectedSession.id, Math.round(newVolume * 100));
     } else {
-      await invoke("player_set_volume", { volume: newVolume });
+      await commands.playerSetVolume(newVolume);
     }
   }
 
@@ -39,7 +39,7 @@
     if ($isRemoteMode && $selectedSession) {
       await sessions.sendToggleMute($selectedSession.id);
     } else {
-      await invoke("player_toggle_mute");
+      await commands.playerToggleMute();
     }
   }
 

src/lib/components/sessions/CastButton.svelte

@@ -1,7 +1,7 @@
 <!-- TRACES: UR-010 | DR-037 -->
 <script lang="ts">
   import { onMount, onDestroy } from "svelte";
-  import { invoke } from "@tauri-apps/api/core";
+  import { commands } from "$lib/api/bindings";
   import { sessions, controllableSessions, selectedSession } from "$lib/stores";
   import SessionPickerModal from "./SessionPickerModal.svelte";
 
@@ -42,18 +42,18 @@
 
     // Set initial hint based on connection state
     const hint = isConnected ? "cast_active" : "cast_discovery";
-    await invoke("sessions_set_polling_hint", { hint });
+    await commands.sessionsSetPollingHint(hint);
   });
 
   onDestroy(async () => {
     // Reset to normal polling when component unmounts
-    await invoke("sessions_set_polling_hint", { hint: "normal" });
+    await commands.sessionsSetPollingHint("normal");
   });
 
   // Update polling hint when connection state changes
   $effect(() => {
     const hint = isConnected ? "cast_active" : "cast_discovery";
-    invoke("sessions_set_polling_hint", { hint });
+    commands.sessionsSetPollingHint(hint);
   });
 
   const isConnected = $derived($selectedSession !== null);

src/lib/components/sessions/RemoteControls.svelte

@@ -15,8 +15,8 @@
   const nowPlaying = $derived(session.nowPlayingItem);
   const supportsSeek = $derived(playState?.canSeek ?? false);
   const supportsNextPrevious = $derived(
-    session.supportedCommands.includes("NextTrack") &&
+    (session.supportedCommands ?? []).includes("NextTrack") &&
-    session.supportedCommands.includes("PreviousTrack")
+    (session.supportedCommands ?? []).includes("PreviousTrack")
   );
 
   async function handlePlayPause() {
@@ -107,8 +107,8 @@
       <h4 class="text-base font-medium text-white truncate">{nowPlaying.name}</h4>
       {#if nowPlaying.artists && nowPlaying.artists.length > 0}
         <p class="text-sm text-gray-400 truncate">{nowPlaying.artists.join(", ")}</p>
-      {:else if nowPlaying.albumName}
+      {:else if nowPlaying?.album}
-        <p class="text-sm text-gray-400 truncate">{nowPlaying.albumName}</p>
+        <p class="text-sm text-gray-400 truncate">{nowPlaying?.album}</p>
       {/if}
     </div>
 
@@ -196,9 +196,9 @@
     {#if playState.volumeLevel !== undefined}
       <div class="flex items-center gap-3">
         <svg class="w-5 h-5 text-gray-400 flex-shrink-0" fill="currentColor" viewBox="0 0 24 24">
-          {#if playState.isMuted || playState.volumeLevel === 0}
+          {#if playState.isMuted || (playState.volumeLevel ?? 0) === 0}
             <path d="M16.5 12c0-1.77-1.02-3.29-2.5-4.03v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51C20.63 14.91 21 13.5 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06c1.38-.31 2.63-.95 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z" />
-          {:else if playState.volumeLevel < 50}
+          {:else if (playState.volumeLevel ?? 0) < 50}
             <path d="M7 9v6h4l5 5V4l-5 5H7z" />
           {:else}
             <path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02z" />

src/lib/components/sessions/SessionCard.svelte

@@ -51,11 +51,11 @@
     <div class="flex items-center gap-3 mt-3 pt-3 border-t border-white/10">
       <div class="w-12 h-12 rounded overflow-hidden flex-shrink-0">
         <CachedImage
-          itemId={nowPlaying.id}
+          itemId={nowPlaying.id ?? ""}
           imageType="Primary"
           tag={nowPlaying.primaryImageTag}
           maxWidth={80}
-          alt={nowPlaying.name}
+          alt={nowPlaying.name ?? undefined}
           class="w-full h-full object-cover"
         />
       </div>
@@ -64,8 +64,8 @@
         <p class="text-sm font-medium text-white truncate">{nowPlaying.name}</p>
         {#if nowPlaying.artists && nowPlaying.artists.length > 0}
           <p class="text-xs text-gray-400 truncate">{nowPlaying.artists.join(", ")}</p>
-        {:else if nowPlaying.albumName}
+        {:else if nowPlaying.album}
-          <p class="text-xs text-gray-400 truncate">{nowPlaying.albumName}</p>
+          <p class="text-xs text-gray-400 truncate">{nowPlaying.album}</p>
         {/if}
 
         <div class="flex items-center gap-2 mt-1">

src/lib/components/sessions/SessionPickerModal.svelte

@@ -63,8 +63,8 @@
     }
   }
 
-  function getSessionIcon(client: string): string {
+  function getSessionIcon(client: string | null | undefined): string {
-    const clientLower = client.toLowerCase();
+    const clientLower = (client ?? "").toLowerCase();
     if (clientLower.includes("tv") || clientLower.includes("roku") || clientLower.includes("android tv")) {
       return "tv";
     } else if (clientLower.includes("web") || clientLower.includes("chrome") || clientLower.includes("firefox")) {

src/lib/components/sessions/SessionsList.svelte

@@ -68,7 +68,7 @@
         <SessionCard
           {session}
           selected={$sessions.selectedSessionId === session.id}
-          onclick={() => handleSessionClick(session.id)}
+          onclick={() => handleSessionClick(session.id ?? "")}
         />
       {/each}
     </div>

src/lib/services/deviceId.ts

@@ -8,7 +8,7 @@
  * TRACES: UR-009 | DR-011
  */
 
-import { invoke } from "@tauri-apps/api/core";
+import { commands } from "$lib/api/bindings";
 
 let cachedDeviceId: string | null = null;
 
@@ -30,7 +30,7 @@ export async function getDeviceId(): Promise<string> {
 
   try {
     // Rust backend handles generation and storage atomically
-    const deviceId = await invoke<string>("device_get_id");
+    const deviceId = await commands.deviceGetId();
     cachedDeviceId = deviceId;
     return deviceId;
   } catch (e) {

src/lib/services/favorites.ts

@@ -1,7 +1,7 @@
 // Favorites service - Handles toggling favorite status with optimistic updates
 // TRACES: UR-017 | DR-021
 
-import { invoke } from "@tauri-apps/api/core";
+import { commands } from "$lib/api/bindings";
 import { auth } from "$lib/stores/auth";
 
 /**
@@ -29,11 +29,7 @@ export async function toggleFavorite(
   const newIsFavorite = !currentIsFavorite;
 
   // 1. Update local database first (optimistic update)
-  await invoke("storage_toggle_favorite", {
+  await commands.storageToggleFavorite(userId, itemId, newIsFavorite);
-    userId,
-    itemId,
-    isFavorite: newIsFavorite,
-  });
 
   // 2. Sync to Jellyfin server
   try {
@@ -45,7 +41,7 @@ export async function toggleFavorite(
     }
 
     // 3. Mark as synced
-    await invoke("storage_mark_synced", { userId, itemId });
+    await commands.storageMarkSynced(userId, itemId);
   } catch (error) {
     console.error("Failed to sync favorite to server:", error);
     // Favorite is stored locally and will be synced later