test(player): answer the commands the tap-surface tests actually render

VideoPlayer.tapSurface.test.ts deliberately does not mock $lib/api/bindings — it
renders the real component against the real bindings, which bottom out in the
globally mocked `invoke`. That mock resolves `undefined` for every command, so
any command whose result is *rendered* blows up: the quality picker assigns the
result straight to state and the template then reads `streamingQualities.length`,
which throws on undefined.

It threw asynchronously, outside any test, so the suite reported 4 unhandled
errors while every test still passed — the state vitest warns "might cause false
positive tests". Answering the two rendered commands removes them.

Authored in the main checkout; brought in here and verified: 83 files, 1009
tests, and the unhandled-error count drops from 4 to 0.

.dockerignore

@@ -0,0 +1,18 @@
+node_modules
+.git
+.gitignore
+.claude
+.svelte-kit
+build
+dist
+.env
+.env.local
+.vscode
+.idea
+target
+*.apk
+*.aab
+*.log
+coverage
+src-tauri/gen
+src-tauri/target

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

@@ -0,0 +1,124 @@
+name: '🏗️ Build and Test JellyTau'
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches:
+      - master
+    paths-ignore:
+      - '**/*.md'
+  workflow_dispatch:
+
+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: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ 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
+
+      # Tripwire for domain-taxonomy leaks into the presentation layer (a
+      # multi-type includeItemTypes query defining a category in the frontend).
+      # See scripts/check-frontend-boundary.sh and
+      # docs/specs/scoped-search-boundary.md.
+      - name: Check frontend/backend boundary
+        run: bash scripts/check-frontend-boundary.sh
+
+      - name: Run frontend tests
+        run: |
+          bunx svelte-kit sync
+          bun run test
+
+      - name: Run Rust tests
+        run: |
+          cd src-tauri
+          cargo test
+          cd ..
+
+  # Fast per-commit Android compile check. This does NOT build a shippable APK:
+  # the full signed release APK is built only on tag pushes by build-release.yml
+  # (which runs sync-android-sources.sh + signing). Running the full bundle here
+  # too would duplicate a ~15min build and, without the sync step, produced an
+  # unsigned APK missing our custom sources/icons/proguard rules anyway.
+  # `cargo check` for the Android target (~1min) catches Android-specific Rust
+  # breakage without linking, bundling, or signing.
+  android-check:
+    name: Android Compile Check
+    runs-on: linux/amd64
+    needs: test
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+    env:
+      ANDROID_HOME: /opt/android-sdk
+      ANDROID_SDK_ROOT: /opt/android-sdk
+      NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
+      ANDROID_NDK_HOME: /opt/android-sdk/ndk/27.0.11902837
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-android-
+
+      - name: Cache Node dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Cargo check (aarch64-linux-android)
+        run: |
+          TC="$NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin"
+          export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$TC/aarch64-linux-android24-clang"
+          export CC_aarch64_linux_android="$TC/aarch64-linux-android24-clang"
+          export AR_aarch64_linux_android="$TC/llvm-ar"
+          cd src-tauri
+          cargo check --target aarch64-linux-android --lib

.gitea/workflows/build-release.yml

@@ -0,0 +1,414 @@
+name: Build & Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to build (e.g., v1.0.0)'
+        required: false
+
+env:
+  RUST_BACKTRACE: 1
+  CARGO_TERM_COLOR: always
+
+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: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ 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: |
+          bunx svelte-kit sync
+          bun run test --run
+        continue-on-error: false
+
+      - name: Run Rust tests
+        run: bun run test:rust
+        continue-on-error: false
+
+      - name: Check TypeScript
+        run: bun run check
+        continue-on-error: false
+
+  build-linux:
+    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: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-host-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ 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
+
+      # The Linux job previously had no version step at all, so a tagged release
+      # built Linux packages from whatever version happened to be committed.
+      - name: Set app version from tag
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
+
+      - name: Build for Linux
+        run: bun run tauri build
+        env:
+          TAURI_SKIP_UPDATER: true
+
+      - name: Prepare Linux artifacts
+        run: |
+          mkdir -p dist/linux
+          # Copy AppImage
+          if [ -f "src-tauri/target/release/bundle/appimage/jellytau_"*.AppImage ]; then
+            cp src-tauri/target/release/bundle/appimage/jellytau_*.AppImage dist/linux/
+          fi
+          # Copy .deb if built
+          if [ -f "src-tauri/target/release/bundle/deb/jellytau_"*.deb ]; then
+            cp src-tauri/target/release/bundle/deb/jellytau_*.deb dist/linux/
+          fi
+          ls -lah dist/linux/
+
+      - name: Upload Linux build artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: jellytau-linux
+          path: dist/linux/
+          retention-days: 30
+
+  build-windows:
+    name: Build Windows
+    runs-on: linux/amd64
+    needs: test
+    # Cross-compiled from Linux via the official Tauri path (MSVC + cargo-xwin),
+    # baked into the builder image. No toolchain installs here — the image has
+    # cargo-xwin, clang/clang-cl, lld, llvm, nsis and the msvc target.
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            ~/.cache/cargo-xwin
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-windows-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-windows-
+
+      - 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-
+
+      # The tag is the single source of truth for a release version; the script
+      # stamps every file that carries it (package.json, tauri.conf.json,
+      # Cargo.toml, Cargo.lock). This step used to sed only tauri.conf.json, so
+      # the other three shipped whatever was committed.
+      - name: Set app version from tag
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
+
+      - name: Build Windows (NSIS installer + exe)
+        run: OUTPUT_DIR="$PWD/dist/windows" WIN_BUNDLES=nsis ./scripts/build-windows-cross.sh
+
+      - name: List Windows artifacts
+        run: ls -lah dist/windows/
+
+      - name: Upload Windows build artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: jellytau-windows
+          path: dist/windows/
+          retention-days: 30
+
+  build-android:
+    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: Cache Rust dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-android-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-android-
+
+      - name: Cache Node dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install
+
+      # Stamp before `android init`: it derives its generated project (including
+      # the initial versionCode) from tauri.conf.json.
+      - name: Set app version from tag
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+        if: startsWith(github.ref, 'refs/tags/v')
+
+      - name: Initialize Android project
+        run: bun run tauri android init
+
+      # Re-run after init: tauri.properties only exists now, and its
+      # autogenerated versionCode (0.0.15 -> 15) is both tiny and NOT monotonic
+      # against the 1000 floor already shipped in the field. The script rewrites
+      # it as 1000 + major*10000 + minor*100 + patch. Runs unconditionally so
+      # untagged builds get a sane code too, derived from git describe.
+      - name: Pin a monotonic Android versionCode
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
+
+      - name: Sync custom Android sources & gradle config
+        run: ./scripts/sync-android-sources.sh
+
+      - name: Write signing keystore
+        run: |
+          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 -d > "$RUNNER_TEMP/jellytau-release.jks"
+          cat > src-tauri/gen/android/keystore.properties <<EOF
+          storeFile=$RUNNER_TEMP/jellytau-release.jks
+          storePassword=${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
+          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
+          EOF
+
+      - name: Build signed Android APK
+        run: bun run tauri android build --apk true --target aarch64
+
+      - name: Collect & verify signed APK
+        run: |
+          mkdir -p dist/android
+          APK=$(find src-tauri/gen/android/app/build/outputs/apk -name '*-release.apk' | head -1)
+          if [ -z "$APK" ]; then echo "❌ No release APK produced"; exit 1; fi
+          cp "$APK" dist/android/jellytau-release.apk
+          APKSIGNER=$(find "$ANDROID_SDK_ROOT/build-tools" -name apksigner | sort -V | tail -1)
+          echo "🔏 Verifying signature with $APKSIGNER"
+          "$APKSIGNER" verify --print-certs dist/android/jellytau-release.apk
+          ls -lah dist/android/
+
+      - name: Upload Android build artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: jellytau-android
+          path: dist/android/
+          retention-days: 30
+
+  create-release:
+    name: Create Release
+    runs-on: linux/amd64
+    needs: [build-linux, build-windows, 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
+
+      - name: Get version from tag
+        id: tag_name
+        run: |
+          echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          echo "RELEASE_NAME=JellyTau ${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Download Linux artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: jellytau-linux
+          path: artifacts/linux/
+
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: jellytau-windows
+          path: artifacts/windows/
+
+      - name: Download Android artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: jellytau-android
+          path: artifacts/android/
+
+      - name: Prepare release notes
+        id: release_notes
+        run: |
+          VERSION="${{ steps.tag_name.outputs.VERSION }}"
+          echo "## JellyTau $VERSION Release" > release_notes.md
+          echo "" >> 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 "" >> release_notes.md
+          echo "#### Windows" >> release_notes.md
+          echo "- **Installer (.exe)** - Run \`jellytau_*-setup.exe\` (NSIS). Unsigned — SmartScreen may warn on first run." >> 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 "- **AAB** - Upload to Google Play Console or testing platforms" >> release_notes.md
+          echo "" >> 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 "" >> release_notes.md
+          echo "#### Linux (AppImage)" >> release_notes.md
+          echo "\`\`\`bash" >> release_notes.md
+          echo "chmod +x jellytau_*.AppImage" >> release_notes.md
+          echo "./jellytau_*.AppImage" >> release_notes.md
+          echo "\`\`\`" >> release_notes.md
+          echo "" >> release_notes.md
+          echo "#### Linux (DEB)" >> release_notes.md
+          echo "\`\`\`bash" >> release_notes.md
+          echo "sudo dpkg -i jellytau_*.deb" >> release_notes.md
+          echo "jellytau" >> release_notes.md
+          echo "\`\`\`" >> release_notes.md
+          echo "" >> release_notes.md
+          echo "#### Android" >> release_notes.md
+          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 "" >> release_notes.md
+          echo "See [GitHub Issues](../../issues) for reported bugs." >> release_notes.md
+          echo "" >> 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
+          echo "- GLIBC 2.29+" >> release_notes.md
+          echo "" >> release_notes.md
+          echo "**Android:**" >> release_notes.md
+          echo "- Android 8.0 or higher" >> release_notes.md
+          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
+
+      - name: Publish Gitea release & upload assets
+        env:
+          # GITEA_TOKEN (a PAT) is preferred; falls back to the auto-provided token.
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          AUTO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          command -v jq >/dev/null || { echo "❌ jq is required on the runner"; exit 1; }
+          VERSION="${{ steps.tag_name.outputs.VERSION }}"
+          API="${GITHUB_SERVER_URL}/api/v1"
+          REPO="${GITHUB_REPOSITORY}"
+          TOKEN="${GITEA_TOKEN:-$AUTO_TOKEN}"
+          case "$VERSION" in *rc*|*beta*|*alpha*) PRE=true;; *) PRE=false;; esac
+
+          PAYLOAD=$(jq -n \
+            --arg tag "$VERSION" \
+            --arg name "JellyTau $VERSION" \
+            --rawfile body release_notes.md \
+            --argjson pre "$PRE" \
+            '{tag_name:$tag, name:$name, body:$body, draft:false, prerelease:$pre}')
+
+          echo "📦 Creating release $VERSION on $REPO"
+          # -f drops on HTTP error; capture status so an existing release (409) is handled gracefully.
+          HTTP=$(curl -sS -o resp.json -w '%{http_code}' -X POST "$API/repos/$REPO/releases" \
+            -H "Authorization: token $TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "$PAYLOAD")
+          if [ "$HTTP" = "201" ]; then
+            RELEASE_ID=$(jq -r '.id' resp.json)
+          elif [ "$HTTP" = "409" ]; then
+            echo "ℹ️  Release $VERSION already exists; fetching its id to upload assets"
+            RELEASE_ID=$(curl -fsS "$API/repos/$REPO/releases/tags/$VERSION" \
+              -H "Authorization: token $TOKEN" | jq -r '.id')
+          else
+            echo "❌ Failed to create release (HTTP $HTTP):"; cat resp.json; exit 1
+          fi
+          echo "Release id=$RELEASE_ID"
+
+          for f in artifacts/android/* artifacts/linux/* artifacts/windows/*; do
+            [ -f "$f" ] || continue
+            echo "⬆️  Uploading $(basename "$f")"
+            curl -fsS -X POST \
+              "$API/repos/$REPO/releases/$RELEASE_ID/assets?name=$(basename "$f")" \
+              -H "Authorization: token $TOKEN" \
+              -F "attachment=@$f" >/dev/null
+          done
+          echo "✅ Release $VERSION published with assets"

.gitea/workflows/publish-docs.yml

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

.gitea/workflows/traceability-check.yml

@@ -0,0 +1,166 @@
+name: Traceability Validation
+
+on:
+  push:
+    branches:
+      - master
+      - main
+      - develop
+  pull_request:
+    branches:
+      - master
+      - main
+      - develop
+
+jobs:
+  validate-traces:
+    runs-on: linux/amd64
+    name: Check Requirement Traces
+    container:
+      image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # bun is baked into jellytau-builder (see Dockerfile.builder); no setup-bun
+      # action needed — fetching it stalls on this Gitea runner.
+      - name: Install dependencies
+        run: bun install
+
+      - name: Extract traces
+        run: |
+          echo "🔍 Extracting requirement traces..."
+          bun run traces:json > traces-report.json
+
+      - name: Validate traces
+        run: |
+          set -e
+
+          echo "📊 Validating requirement traceability..."
+          echo ""
+
+          # Denominators come from docs/requirements.md at run time — NEVER
+          # hardcode them here. This step previously divided by frozen literals
+          # (UR/39, IR/24, DR/48, JA/3, total 114) while the file had grown to
+          # 211 requirements, so it reported 158% coverage and the threshold
+          # below could never trip. See docs/specs/traceability-gate-repair.md.
+          TOTAL_TRACES=$(jq '.totalTraces' traces-report.json)
+          COVERED=$(jq '.coverage.covered' traces-report.json)
+          TOTAL_REQS=$(jq '.coverage.total' traces-report.json)
+          COVERAGE=$(jq '.coverage.percent' traces-report.json)
+
+          echo "✅ TRACES Found: $TOTAL_TRACES"
+          echo ""
+          echo "📋 Coverage Summary (traced / defined):"
+          for T in UR IR DR JA; do
+            TRACED=$(jq --arg t "$T" '[.byType[$t][] | select(. != null)] | length' traces-report.json)
+            DEFINED=$(jq --arg t "$T" '.defined[$t]' traces-report.json)
+            echo "   $T: $TRACED / $DEFINED"
+          done
+          echo ""
+
+          echo "📈 Overall Coverage: $COVERED / $TOTAL_REQS ($COVERAGE%)"
+          echo ""
+
+          # Traced IDs that requirements.md does not define (typo, or a deleted
+          # requirement). These do not count toward coverage.
+          ORPHANED=$(jq -c '.coverage.orphaned' traces-report.json)
+          if [ "$ORPHANED" != "[]" ]; then
+            echo "⚠️  Traced but not defined in requirements.md: $ORPHANED"
+            echo ""
+          fi
+
+          # A ratio above 100% means the computation is broken — the exact
+          # condition that hid the stale-denominator bug. Fail loudly.
+          if [ "$COVERAGE" -gt 100 ]; then
+            echo "❌ ERROR: Coverage ($COVERAGE%) exceeds 100% — the gate is miscomputing."
+            echo "   Orphaned IDs: $ORPHANED"
+            exit 1
+          fi
+
+          # Check minimum threshold
+          MIN_THRESHOLD=50
+          if [ "$COVERAGE" -lt "$MIN_THRESHOLD" ]; then
+            echo "❌ ERROR: Coverage ($COVERAGE%) is below minimum threshold ($MIN_THRESHOLD%)"
+            exit 1
+          fi
+
+          echo "✅ Coverage is acceptable ($COVERAGE% >= $MIN_THRESHOLD%)"
+
+      - name: Check modified files
+        if: github.event_name == 'pull_request'
+        run: |
+          echo "🔍 Checking modified files for traces..."
+          echo ""
+
+          # Get changed files
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(ts|tsx|svelte|rs)$' || echo "")
+
+          if [ -z "$CHANGED" ]; then
+            echo "✅ No TypeScript/Rust files changed"
+            exit 0
+          fi
+
+          echo "📝 Changed files:"
+          echo "$CHANGED" | sed 's/^/   /'
+          echo ""
+
+          # Check each file
+          # Pipe into the loop instead of a here-string (<<<) so this step works
+          # under POSIX sh/dash, not just bash. Use `case` instead of `[[ == ]]`
+          # for the same reason. The loop runs in a subshell (so a counter var
+          # wouldn't survive), so we record warnings in a temp file and count it
+          # afterwards.
+          MISSING_FILE=$(mktemp)
+          echo "$CHANGED" | while IFS= read -r file; do
+            # Skip test files
+            case "$file" in
+              *.test.*) continue ;;
+            esac
+
+            if [ -f "$file" ]; then
+              if ! grep -q "TRACES:" "$file"; then
+                echo "⚠️  Missing TRACES: $file"
+                echo "$file" >> "$MISSING_FILE"
+              fi
+            fi
+          done
+
+          MISSING_TRACES=$(wc -l < "$MISSING_FILE" | tr -d ' ')
+          rm -f "$MISSING_FILE"
+
+          if [ "$MISSING_TRACES" -gt 0 ]; then
+            echo ""
+            echo "📝 Recommendation: Add TRACES comments to new/modified code"
+            echo "   Format: // TRACES: UR-001, UR-002 | DR-003"
+            echo ""
+            echo "💡 For more info, see: scripts/README.md"
+          fi
+
+      - name: Generate full report
+        if: always()
+        run: |
+          echo "📄 Generating full traceability report..."
+          bun run traces:markdown
+
+      - name: Display report summary
+        if: always()
+        run: |
+          echo ""
+          echo "📊 Full Report Generated"
+          echo "📁 Location: docs/traceability.md"
+          echo ""
+          head -50 docs/traceability.md || true
+
+      - name: Save artifacts
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: traceability-reports
+          path: |
+            traces-report.json
+            docs/traceability.md
+          retention-days: 30

.gitignore

@@ -0,0 +1,72 @@
+# OS files
+.DS_Store
+Thumbs.db
+
+# Node.js
+node_modules
+npm-debug.log*
+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
+/.svelte-kit
+/package
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Testing
+coverage
+.nyc_output
+*.lcov
+
+# WebdriverIO E2E tests
+e2e/logs/
+e2e/screenshots/
+wdio-*.log
+
+# Vitest
+.vitest
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+*~
+
+# Logs
+logs
+*.log
+
+# Android signing keystore (NEVER commit)
+android-keystore/
+
+# Local machine-specific Android NDK toolchain paths (do not commit)
+src-tauri/.cargo/config.toml
+
+# Docs site build artifacts (generated by the publish-docs CI job into docs/)
+/docs/SUMMARY.md
+/docs/README.md
+/docs/api-redirect.md
+/docs-site/book/
+
+# Arch packaging build artifacts (vendored cargo cache, makepkg workdir, output package)
+/.cargo-arch/
+/packaging/arch/pkg/
+/packaging/arch/src/
+/packaging/arch/*.pkg.tar.zst

CLAUDE.md

@@ -0,0 +1,313 @@
+# JellyTau
+
+A cross-platform Jellyfin client. Business logic lives in a Rust backend
+(`src-tauri/`); a SvelteKit + TypeScript frontend (`src/`) handles presentation
+and talks to it over Tauri v2 IPC. Targets **Linux** (libmpv, WebKitGTK HTML5
+`<video>` for transcoded playback) and **Android** (ExoPlayer).
+
+Package manager is **bun**.
+
+## Build / Run / Test
+
+All routine tasks go through `package.json` scripts and helper scripts in
+`scripts/`:
+
+```bash
+bun install                  # install deps
+bun run dev                  # vite dev server (frontend)
+bun run tauri dev            # run the desktop app
+
+bun run check                # svelte-check (types)
+bun run test                 # vitest (frontend unit/integration)
+bun run test:rust            # cargo test (scripts/test-rust.sh)
+bun run test:all             # full suite (scripts/test-all.sh)
+bun run test:e2e             # webdriverio e2e
+
+# Android — canonical entry points (see scripts/):
+bun run android:build            # debug APK
+bun run android:build:release    # release APK
+bun run android:deploy           # install to connected device
+bun run android:dev              # build + deploy
+bun run android:logs             # logcat
+```
+
+The **debug** build type carries `applicationIdSuffix ".debug"`, so
+`com.dtourolle.jellytau.debug` ("JellyTau Debug") installs *alongside* a release
+build with its own data dir — never uninstall the release app to test a debug
+one. `./scripts/build-and-deploy.sh release --device --debug` puts an
+R8-minified *release* build in that same slot, signed with the local debug
+keystore, for validating minification without the real key. Only the
+applicationId is suffixed; Kotlin classes stay in the `namespace` package
+`com.dtourolle.jellytau`, so JNI lookups and R8 keep rules are unaffected. See
+[README_ANDROID_BUILD.md](src-tauri/android/README_ANDROID_BUILD.md).
+
+CI runs on **Gitea Actions** (`.gitea/workflows/`), not GitHub. Use the `gh` CLI
+only against the mirror if one exists; the canonical remote is
+`gitea.tourolle.paris`.
+
+> **🔴 CI installs no system tools.** Never add an `apt-get`, `rustup`,
+> `sdkmanager`, mingw/nsis, or any other *toolchain/system-package* install to a
+> CI workflow step. Every build, test, and packaging **tool** must already live
+> in the Docker image the job runs in — the unified builder (`Dockerfile.builder`
+> → `gitea.tourolle.paris/dtourolle/jellytau-builder`) for Android/Linux/Windows,
+> or `Dockerfile.arch` for Arch. If a job needs a tool the image lacks, **add it
+> to the image, rebuild + push it** (`scripts/build-builder-image.sh`), and use
+> it from CI — do not install it at job time. This keeps builds reproducible and
+> fast, and is why the packaging stages are thin `FROM ${BUILDER_IMAGE}` layers.
+>
+> `bun install` (fetching the project's own JS deps per the lockfile) is **not**
+> a violation — that's project dependencies, not a toolchain. The rule is about
+> system tools, not npm/bun/cargo *packages* declared by the project.
+
+## Before Committing
+
+- Frontend: `bun run check` and `bun run test` must pass.
+- Rust: `cd src-tauri && cargo fmt` then `cargo clippy`, plus `bun run test:rust`.
+- **Boundary**: `bun run check:boundary` must pass — no domain taxonomy (Jellyfin
+  item-type category sets) leaked into the frontend. See below.
+- **Traceability**: new requirement-implementing code must carry a `// TRACES:`
+  comment (see below).
+- **Android source edits**: edit `src-tauri/android/src` (the canonical tree),
+  then run `scripts/sync-android-sources.sh` to sync into the `gen/` tree.
+  Never edit the generated `gen/` sources directly.
+
+## Traceability (TRACES)
+
+This project practices requirement-driven development: code that implements a
+requirement is tagged with a `TRACES:` comment linking it to requirement IDs, and
+an extraction tool builds the traceability matrix. **When you add or change code
+that implements a requirement, add/update its TRACES comment.** Internal helpers
+and requirement-less code stay untraced.
+
+Format — `// TRACES: <URs> | <DRs> | <tests>`, e.g.:
+
+```rust
+/// TRACES: UR-005 | DR-001
+pub enum PlayerState { … }
+```
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+export function autoplayNextEpisode() { }
+```
+
+ID types: **UR** user requirement, **IR** integration, **DR** development, **JA**
+Jellyfin API, **UT** unit test, **IT** integration test. Requirements are defined
+in [docs/requirements.md](docs/requirements.md); the generated matrix is
+[docs/traceability.md](docs/traceability.md).
+
+Tooling:
+
+```bash
+bun run traces            # extract traces (default format)
+bun run traces:json       # JSON — e.g. | jq '.byType' or '.requirements."UR-005"'
+bun run traces:markdown   # regenerate docs/traceability.md
+git diff --name-only | xargs grep -L "TRACES:"   # find untraced changed files
+```
+
+**CI is Gitea Actions** (`.gitea/workflows/`, remote `gitea.tourolle.paris`), not
+GitHub. `traceability-check.yml` fails the build if coverage drops below
+**50%** (`MIN_THRESHOLD`); `build-and-test.yml` runs frontend + Rust tests and an
+Android `cargo check`. See [docs/traceability-ci.md](docs/traceability-ci.md) and
+[docs/traces-quick-ref.md](docs/traces-quick-ref.md).
+
+### Traces drive release notes
+
+Prefer traceability over raw commit subjects when writing release notes for
+[docs/release-checklist.md](docs/release-checklist.md). Raw `git log` subjects are
+noisy; the TRACES graph gives a semantic summary of *what capabilities* the
+release touched.
+
+```bash
+bun run release:notes                 # <latest tag>..HEAD
+bun run release:notes v0.0.15..HEAD   # explicit range
+```
+
+[scripts/release-notes.ts](scripts/release-notes.ts) resolves a commit range's
+changed files → their `TRACES:` IDs → descriptions in
+[docs/requirements.md](docs/requirements.md), then groups **UR** into *Features*
+and **DR/IR** into *Improvements* (deduped, so many commits touching one
+requirement collapse to one line). It also lists changed files that carry no
+TRACES so nothing is silently dropped — those still need a manual line. Treat the
+output as a reviewed draft, not a final changelog.
+
+## Architecture
+
+- **Rust backend** (`src-tauri/src/`) — all business logic: auth, catalog,
+  sessions, downloads, offline cache, playback control. Commands grouped by
+  domain in `src-tauri/src/commands/` (`auth.rs`, `catalog.rs`, `player/`,
+  `download/`, `offline.rs`, `sessions.rs`, …).
+- **Svelte frontend** (`src/`) — presentation only. Stores in
+  `src/lib/stores/`, API wrappers in `src/lib/api/`, components in
+  `src/lib/components/`.
+- **Playback layers** — Linux uses libmpv for direct playback and a WebKitGTK
+  HTML5 `<video>` element for HLS-transcoded (h264) streams; Android uses
+  ExoPlayer with a foreground media service + `MediaSessionCompat`.
+- **tauri-specta** generates TypeScript bindings and typed events from the Rust
+  command/event definitions (registered via the Builder in `src-tauri/src/lib.rs`).
+
+**Read the architecture docs before making structural changes** — they are the
+canonical, maintained source; this file only summarizes. See
+[docs/architecture/README.md](docs/architecture/README.md) and:
+
+| Doc | Contents |
+|-----|----------|
+| [01-rust-backend.md](docs/architecture/01-rust-backend.md) | Player/session state machines, playback mode, queue, commands |
+| [02-svelte-frontend.md](docs/architecture/02-svelte-frontend.md) | Stores, repository architecture, MiniPlayer, autoplay, nav guard |
+| [03-data-flow.md](docs/architecture/03-data-flow.md) | Cache-first query flow, playback initiation, mode transfer |
+| [04-type-sync-and-threading.md](docs/architecture/04-type-sync-and-threading.md) | **Rust↔TS type sync, the IPC camelCase convention + param table, locking** |
+| [05-platform-backends.md](docs/architecture/05-platform-backends.md) | MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession, HTML5 adapter |
+| [06-downloads-and-offline.md](docs/architecture/06-downloads-and-offline.md) | Download manager/worker, smart cache, offline commands |
+| [07-connectivity.md](docs/architecture/07-connectivity.md) | HTTP retry, ConnectivityMonitor, reachability model |
+| [08-database-design.md](docs/architecture/08-database-design.md) | Tables, relationships, key queries |
+| [09-security.md](docs/architecture/09-security.md) | Token storage, secure storage, network security |
+
+Release process lives in [docs/release-checklist.md](docs/release-checklist.md)
+and [docs/build-release.md](docs/build-release.md).
+
+### Core principles (from the architecture docs)
+
+- **Playback state is one-directional.** The player (ExoPlayer on Android, MPV on
+  Linux, session poller in remote mode) is the **authoritative source** of state
+  — position, pause, seeking, rate, track changes. The Svelte UI, OS
+  `MediaSession`/lockscreen, and MPRIS are **consumers**; they reflect what the
+  player reports and never determine it.
+- **Unified player boundary.** UI controls playback *only* through the frontend
+  facade `src/lib/player/index.ts` (`playerController`) — never by calling
+  `commands.player*` directly. Webview HTML5 `<video>` reports its state back
+  into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*`
+  commands, so the controller stays the single source of truth in both native
+  and HTML5 modes.
+- **Reachability from real traffic.** Server online/offline is derived from the
+  outcome of actual repository requests (reported to `ConnectivityMonitor`), not
+  a side-channel poller. The `/System/Info/Public` probe runs *only while
+  offline*, as a recovery detector.
+- **Poison-tolerant locking.** Access shared `std::sync` state via the
+  `MutexSafe`/`RwLockSafe` helpers in `utils/lock.rs`, which recover a poisoned
+  lock instead of cascading a panic across the player.
+- **Graceful backend init.** If a native player backend fails to initialize, the
+  app falls back to a no-op backend and emits `backend-init-failed` rather than
+  crashing.
+- **Domain vocabulary lives in Rust.** The frontend is presentation-only and must
+  not encode Jellyfin's *taxonomy* — e.g. the set of item types that defines a
+  category like "Music". Send an opaque scope/enum across the boundary and let the
+  backend expand it. Single-type presentation (`itemType: "Movie"`, "this page
+  shows albums") is fine; a *category → set of types* mapping in `src/` is a leak.
+  `bun run check:boundary` is the tripwire; the real gate is the spec's layer
+  assignment. The canonical example lives in Rust:
+  `SearchScope::item_types()` in `repository/types.rs` expands an opaque scope the
+  frontend sends. See [scoped-search-boundary.md](docs/specs/scoped-search-boundary.md)
+  for the incident this rule came from — note the tripwire missed that leak for
+  months because the mapping was assigned to a named const rather than written
+  inline at the query, so **a green `check:boundary` is not proof**; it flags
+  item-type array literals only, not run-time-built sets or `switch`/`||`
+  taxonomy.
+
+## Writing specs
+
+New feature specs go in [docs/specs/](docs/specs/). **Start from
+[SPEC-TEMPLATE.md](docs/specs/SPEC-TEMPLATE.md)** — its "Layer assignment" section
+forces each piece of *logic* to be placed in the correct layer (Rust = domain,
+frontend = presentation) *with a reason*, which is what prevents boundary leaks.
+Before accepting a spec, run it past
+[SPEC-REVIEW-CHECKLIST.md](docs/specs/SPEC-REVIEW-CHECKLIST.md). Do **not** frame
+a spec around "no Rust changes required" — correct layer placement is the goal,
+not minimal backend churn.
+
+## Conventions
+
+### Rust Backend
+
+- Use `#[tauri::command]` for all IPC handlers.
+- Prefer `async` commands for I/O-bound work.
+- Return `Result<T, String>` from commands (the established convention here).
+- Use `tauri::State<>` for shared state.
+- Group related commands in domain modules under `commands/`.
+- Use official Tauri plugins before writing custom native code.
+
+### Frontend
+
+- Use `invoke<T>()` from `@tauri-apps/api/core`, or the tauri-specta bindings.
+- Define TS types matching the Rust structs; prefer the generated bindings.
+- Handle IPC errors with try/catch.
+- Use `@tauri-apps/api/path` for paths (never hardcode).
+- Use `@tauri-apps/api/event` for backend→frontend events.
+
+### 🔴 IPC parameter naming (Tauri v2)
+
+The command **name** must match the Rust function name exactly
+(`invoke("player_play_queue", …)`). But **parameter names do NOT** — Tauri v2's
+`#[tauri::command]` macro auto-converts snake_case Rust params to **camelCase**
+on the frontend:
+
+```rust
+#[tauri::command]
+pub async fn cmd(repository_handle: String) { … }
+```
+```typescript
+await invoke("cmd", { repositoryHandle: "…" }); // camelCase, auto-converted
+```
+
+Nested struct fields need `#[serde(rename_all = "camelCase")]`; tagged unions use
+`#[serde(tag = "type")]` and both sides must match the tag. Note: tauri-specta
+tagged responses keep the Rust field names as-is (e.g. `new_url`, not `newUrl`).
+
+### Events
+
+- Backend events use **kebab-case** names (`download-event`, `search-event`).
+- Emit from Rust via `emit(...)`; consume on the frontend via
+  `@tauri-apps/api/event` or the tauri-specta typed event bindings.
+
+### Security
+
+- Declare minimum permissions in `src-tauri/capabilities/`.
+- Keep the CSP restrictive in `tauri.conf.json`.
+- Validate all inputs in Rust command handlers.
+- **Never read credentials** (tokens/keys from keyring, env, or stores) without
+  asking the user first.
+
+## Gotchas (hard-won)
+
+- **Never call sync/blocking APIs from event callbacks** that can re-enter the
+  player or hold a lock — it deadlocks. On Android, bind a locked
+  `AutoplayDecision` to a `let` *before* matching; a tokio `MutexGuard` held in
+  the `match` scrutinee deadlocks the `AdvanceToNext` arm.
+- **VideoPlayer native mode**: no lifecycle calls after an `await` in `onMount`
+  (it flips to HTML5 mode and breaks Android seek).
+- **Transcoded resume/seek**: `get_video_stream_url` must return the HLS
+  `master.m3u8`, not `stream.mp4`, or transcoded playback never starts.
+- **Downloads** cap at 3 concurrent; the backend pump auto-starts pending rows.
+  Don't loop `startDownload` from the frontend.
+- **Parallel Claude sessions**: the user may run concurrent sessions. Unexpected
+  file changes may be another session — check `git diff` before "repairing".
+
+## Testing
+
+### 🔴 Bug fixes: failing test FIRST, then the fix
+
+When fixing a bug, **write a test that reproduces it and watch it fail before
+touching the fix.** Red → green, in that order:
+
+1. Write a test that exercises the broken behavior and **run it — it must fail**,
+   proving the test actually catches the bug (a test that passes before the fix
+   proves nothing).
+2. Apply the fix.
+3. Re-run — the test now passes, and so does the rest of the suite.
+
+Never fix first and backfill the test afterward: a test written against
+already-fixed code can pass for the wrong reason and silently fails to guard the
+regression. If the logic is buried in a component, extract the pure part into a
+plain `.ts` module (e.g. `episodeStrip.ts`) so it can be unit-tested — the same
+pattern as `TrackList.logic.test.ts`.
+
+```bash
+# Rust
+cd src-tauri && cargo test
+cd src-tauri && cargo test test_name        # single test
+
+# Frontend
+bun run test
+bun run test:coverage
+
+# Tauri IPC param-naming integration tests (guard the camelCase rule):
+bun run test -- tauriIntegration.test.ts
+```

Dockerfile

@@ -0,0 +1,156 @@
+# Multi-stage build for JellyTau - Tauri Jellyfin client
+#
+# The desktop packaging stages (desktop-linux-build, windows-cross) build FROM
+# the unified registry builder image, which carries every packaging tool. Declared
+# here (before the first FROM) so it's in scope for those stages' FROM lines.
+# Override for local iteration: --build-arg BUILDER_IMAGE=jellytau-builder:latest
+ARG BUILDER_IMAGE=gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+
+FROM ubuntu:24.04 AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    ANDROID_HOME=/opt/android-sdk \
+    NDK_VERSION=27.0.11902837 \
+    SDK_VERSION=34 \
+    RUST_BACKTRACE=1 \
+    PATH="/root/.bun/bin:/root/.cargo/bin:$PATH" \
+    CARGO_HOME=/root/.cargo
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Build essentials
+    build-essential \
+    curl \
+    wget \
+    git \
+    ca-certificates \
+    unzip \
+    # JDK for Android
+    openjdk-17-jdk-headless \
+    # Android build tools
+    android-sdk-platform-tools \
+    # Additional development tools
+    pkg-config \
+    libssl-dev \
+    libclang-dev \
+    llvm-dev \
+    # Tauri Linux desktop dependencies (needed for `cargo test` on the host target)
+    libglib2.0-dev \
+    libgtk-3-dev \
+    libwebkit2gtk-4.1-dev \
+    libjavascriptcoregtk-4.1-dev \
+    libsoup-3.0-dev \
+    librsvg2-dev \
+    libayatana-appindicator3-dev \
+    # mpv player library (linked via libmpv-sys)
+    libmpv-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20.x from NodeSource
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Bun
+RUN curl -fsSL https://bun.sh/install | bash && \
+    ln -s /root/.bun/bin/bun /usr/local/bin/bun
+
+# Install Rust using rustup
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && \
+    . $HOME/.cargo/env && \
+    rustup target add aarch64-linux-android && \
+    rustup target add armv7-linux-androideabi && \
+    rustup target add x86_64-linux-android
+
+# Setup Android SDK
+RUN mkdir -p $ANDROID_HOME && \
+    mkdir -p /root/.android && \
+    echo '### User Sources for `android` cmd line tool ###' > /root/.android/repositories.cfg && \
+    echo 'count=0' >> /root/.android/repositories.cfg
+
+# Download and setup Android Command Line Tools
+RUN wget -q https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O /tmp/cmdline-tools.zip && \
+    unzip -q /tmp/cmdline-tools.zip -d $ANDROID_HOME && \
+    rm /tmp/cmdline-tools.zip && \
+    mkdir -p $ANDROID_HOME/cmdline-tools/latest && \
+    mv $ANDROID_HOME/cmdline-tools/* $ANDROID_HOME/cmdline-tools/latest/ 2>/dev/null || true
+
+# Setup Android SDK components
+RUN $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --sdk_root=$ANDROID_HOME \
+    "platforms;android-$SDK_VERSION" \
+    "build-tools;34.0.0" \
+    "ndk;$NDK_VERSION" \
+    --channel=0 2>&1 | grep -v "Warning" || true
+
+# Set NDK environment variable
+ENV NDK_HOME=$ANDROID_HOME/ndk/$NDK_VERSION
+
+# Create working directory
+WORKDIR /app
+
+# Copy project files
+COPY . .
+
+# Install Node.js dependencies
+RUN bun install
+
+# Install Rust dependencies
+RUN cd src-tauri && cargo fetch && cd ..
+
+# Build stage - Tests
+FROM builder AS test
+WORKDIR /app
+RUN echo "Running tests..." && \
+    bunx svelte-kit sync && \
+    bun run test && \
+    cd src-tauri && cargo test && cd .. && \
+    echo "All tests passed!"
+
+# Build stage - APK
+FROM builder AS android-build
+WORKDIR /app
+RUN cd src-tauri && cargo fetch && cd .. && \
+    echo "Building Android APK..." && \
+    bun run build && \
+    bun run tauri android build --apk true && \
+    echo "APK build complete!"
+
+# Desktop packaging stages build FROM the unified registry builder image (see the
+# BUILDER_IMAGE ARG at the top), which already carries every packaging tool
+# (rpm/file for Linux, cargo-xwin + nsis + the x86_64-pc-windows-msvc rust
+# target for Windows). ONE source of dependency truth, shared with CI — no
+# per-stage apt/rustup here.
+#
+# NOTE: Windows uses the MSVC target via cargo-xwin, NOT mingw/GNU — the GNU
+# toolchain cannot bundle an NSIS installer from Linux. See
+# scripts/build-windows-cross.sh.
+
+# Linux desktop packaging environment (deb + rpm; Arch is Dockerfile.arch).
+# Thin layer over the builder — the actual build runs at container-run time on
+# the bind-mounted source (see docker-compose.yml / scripts/build-desktop-linux.sh),
+# matching the `dev` service model. Run standalone with:
+#   docker run --rm -v "$PWD:/app" -v "$PWD/dist:/app/dist" <img> \
+#     bash -c "OUTPUT_DIR=/app/dist scripts/build-desktop-linux.sh"
+FROM ${BUILDER_IMAGE} AS desktop-linux-build
+WORKDIR /app
+CMD ["bash", "-c", "OUTPUT_DIR=/app/dist scripts/build-desktop-linux.sh"]
+
+# Windows cross-compile environment (MSVC target via cargo-xwin). Video works via
+# WebView2 and audio via the webview <audio> backend; NSIS installer is produced
+# from Linux by cargo-xwin. Default bundles NSIS; override WIN_BUNDLES=none for
+# exe-only. Build runs at container-run time like above.
+FROM ${BUILDER_IMAGE} AS windows-cross
+WORKDIR /app
+CMD ["bash", "-c", "OUTPUT_DIR=/app/dist WIN_BUNDLES=${WIN_BUNDLES:-nsis} scripts/build-windows-cross.sh"]
+
+# Final output stage
+FROM ubuntu:24.04 AS final
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    android-sdk-platform-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY --from=android-build /app/src-tauri/gen/android/app/build/outputs/apk /app/apk
+
+VOLUME ["/app/apk"]
+CMD ["/bin/bash", "-c", "echo 'APK files are available in /app/apk' && ls -lh /app/apk/"]

Dockerfile.arch

@@ -0,0 +1,37 @@
+# JellyTau Arch Linux package builder.
+#
+# Tauri has no pacman bundle target, so we build a real .pkg.tar.zst with makepkg
+# from packaging/arch/PKGBUILD. makepkg refuses to run as root, so we create a
+# non-root `builder` user with passwordless sudo (for `makepkg -s` pacman calls).
+#
+#   docker build -f Dockerfile.arch -t jellytau-arch .
+#   docker run --rm -v "$PWD/dist:/out" jellytau-arch
+FROM archlinux:latest
+
+RUN pacman -Syu --noconfirm \
+    base-devel git sudo \
+    rust cargo nodejs \
+    webkit2gtk-4.1 mpv gtk3 libayatana-appindicator \
+    libsoup3 pkgconf openssl \
+    && pacman -Scc --noconfirm
+
+# Bun is not in the official repos; install the upstream binary.
+RUN curl -fsSL https://bun.sh/install | bash && \
+    ln -s /root/.bun/bin/bun /usr/local/bin/bun
+
+# Non-root build user with passwordless sudo for makepkg's dependency step.
+RUN useradd -m builder && \
+    echo 'builder ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/builder && \
+    ln -sf /root/.bun/bin/bun /usr/local/bin/bun
+
+WORKDIR /app
+COPY . .
+RUN chown -R builder:builder /app
+
+USER builder
+ENV OUTPUT_DIR=/out
+RUN mkdir -p /out
+VOLUME ["/out"]
+
+# Default: build the package. Output lands in /out (mount it to collect the pkg).
+CMD ["bash", "-c", "OUTPUT_DIR=/out scripts/build-arch.sh"]

Dockerfile.builder

@@ -0,0 +1,136 @@
+# JellyTau Builder Image
+# Pre-built image with all dependencies for building, testing, and packaging:
+#   - Android APK (SDK/NDK), Linux desktop (deb/rpm),
+#   - Windows cross via the official Tauri path: MSVC target + cargo-xwin + NSIS
+# Arch packages build in a separate archlinux image (Dockerfile.arch) since
+# makepkg is Arch-specific.
+# Push to your registry: docker build -f Dockerfile.builder -t gitea.tourolle.paris/dtourolle/jellytau-builder:latest .
+
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    ANDROID_HOME=/opt/android-sdk \
+    NDK_VERSION=27.0.11902837 \
+    SDK_VERSION=36 \
+    BUILD_TOOLS_VERSION=35.0.0 \
+    RUST_BACKTRACE=1 \
+    PATH="/root/.bun/bin:/root/.cargo/bin:$PATH" \
+    CARGO_HOME=/root/.cargo
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    wget \
+    git \
+    ca-certificates \
+    unzip \
+    jq \
+    openjdk-17-jdk-headless \
+    pkg-config \
+    libssl-dev \
+    libclang-dev \
+    llvm-dev \
+    # Tauri Linux desktop dependencies (needed for `cargo test` on the host target)
+    libglib2.0-dev \
+    libgtk-3-dev \
+    libwebkit2gtk-4.1-dev \
+    libjavascriptcoregtk-4.1-dev \
+    libsoup-3.0-dev \
+    librsvg2-dev \
+    libayatana-appindicator3-dev \
+    # mpv player library (linked via libmpv-sys)
+    libmpv-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20.x from NodeSource
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Bun
+RUN curl -fsSL https://bun.sh/install | bash && \
+    ln -s /root/.bun/bin/bun /usr/local/bin/bun
+
+# Install Rust using rustup
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && \
+    . $HOME/.cargo/env && \
+    rustup target add aarch64-linux-android && \
+    rustup target add armv7-linux-androideabi && \
+    rustup target add x86_64-linux-android && \
+    rustup component add rustfmt clippy
+
+# Setup Android SDK
+RUN mkdir -p $ANDROID_HOME && \
+    mkdir -p /root/.android && \
+    echo '### User Sources for `android` cmd line tool ###' > /root/.android/repositories.cfg && \
+    echo 'count=0' >> /root/.android/repositories.cfg
+
+# Download and setup Android Command Line Tools
+RUN wget -q https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O /tmp/cmdline-tools.zip && \
+    unzip -q /tmp/cmdline-tools.zip -d $ANDROID_HOME && \
+    rm /tmp/cmdline-tools.zip && \
+    mkdir -p $ANDROID_HOME/cmdline-tools/latest && \
+    mv $ANDROID_HOME/cmdline-tools/* $ANDROID_HOME/cmdline-tools/latest/ 2>/dev/null || true
+
+# 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;$BUILD_TOOLS_VERSION" \
+    "ndk;$NDK_VERSION" \
+    --channel=0 2>&1 | grep -v "Warning" || true
+
+# Set NDK environment variable
+ENV NDK_HOME=$ANDROID_HOME/ndk/$NDK_VERSION
+
+# Gradle distribution. `tauri android init` regenerates gen/android with a
+# wrapper pointing at services.gradle.org, so every Android job would otherwise
+# download ~130MB of Gradle at build time — slow, and a hard failure when the
+# CDN hiccups ("Unexpected end of file from server"). Ship the distribution in
+# the image instead; scripts/sync-android-sources.sh repoints the regenerated
+# wrapper at this local copy. Keep GRADLE_VERSION in sync with the version
+# Tauri's generated wrapper requests.
+ENV GRADLE_VERSION=8.14.3 \
+    GRADLE_HOME=/opt/gradle/gradle-8.14.3
+RUN mkdir -p /opt/gradle/dist && \
+    wget -q "https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip" \
+        -O "/opt/gradle/dist/gradle-${GRADLE_VERSION}-bin.zip" && \
+    unzip -q "/opt/gradle/dist/gradle-${GRADLE_VERSION}-bin.zip" -d /opt/gradle && \
+    "$GRADLE_HOME/bin/gradle" --version
+ENV PATH="$GRADLE_HOME/bin:$PATH"
+
+# ---------------------------------------------------------------------------
+# Desktop packaging tools — kept in a trailing layer ON PURPOSE so that adding
+# or changing a packaging tool doesn't invalidate the expensive apt/rust/Android
+# layers above (a tool tweak becomes a ~1-2 min rebuild, not ~15). Covers Linux
+# (deb/rpm) and Windows cross (MSVC via cargo-xwin + NSIS).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Linux desktop packaging: rpmbuild for the .rpm bundle (deb needs nothing extra)
+    rpm \
+    file \
+    # Windows cross-compile (official Tauri path: MSVC target via cargo-xwin).
+    # clang provides clang-cl, the MSVC-compatible C compiler cc-rs uses to build
+    # C deps (bundled sqlite, ring, ...); lld = linker; llvm = llvm-lib/ar etc;
+    # nsis = installer generator.
+    clang \
+    lld \
+    llvm \
+    nsis \
+    && rm -rf /var/lib/apt/lists/* \
+    # Ubuntu's clang package ships clang but NOT the clang-cl alias that cc-rs
+    # invokes for MSVC targets. clang-cl is the same binary in MSVC-compat mode,
+    # so provide it as a symlink.
+    && ln -sf /usr/bin/clang /usr/local/bin/clang-cl
+
+# Windows rust target + cargo-xwin (downloads the MSVC CRT/SDK at build time).
+RUN . $HOME/.cargo/env && \
+    rustup target add x86_64-pc-windows-msvc && \
+    cargo install --locked cargo-xwin
+
+WORKDIR /app
+
+ENTRYPOINT ["/bin/bash"]

README.md

@@ -0,0 +1,60 @@
+<h1 align="center">
+  <img src="docs/assets/logo.png" alt="JellyTau logo" width="120" /><br />
+  JellyTau
+</h1>
+
+A cross-platform Jellyfin client built with Tauri, SvelteKit, and TypeScript.
+
+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).
+
+## Getting Started
+
+This project uses [bun](https://bun.sh) as its package manager.
+
+```bash
+# Activate the Rust environment (fish shell)
+source "$HOME/.cargo/env.fish"
+
+# Install dependencies
+bun install
+
+# Run in development
+bun run tauri dev
+
+# Type-check the frontend
+bun run check
+
+# Build for Linux
+bun run tauri build
+
+# Build for Android
+bun run tauri android build
+```
+
+For the full set of build, test, and Android helper scripts, see
+[scripts/README.md](scripts/README.md).
+
+## Documentation
+
+| Topic | Location |
+|-------|----------|
+| Architecture overview & subsystem docs | [docs/architecture/](docs/architecture/) |
+| Requirements, traceability & technical debt | [docs/requirements.md](docs/requirements.md) |
+| Build & release process | [docs/build-release.md](docs/build-release.md) |
+| Docker builds | [docs/build/docker.md](docs/build/docker.md) |
+| Traceability tooling & CI | [docs/traceability.md](docs/traceability.md), [docs/traceability-ci.md](docs/traceability-ci.md) |
+| Release checklist | [docs/release-checklist.md](docs/release-checklist.md) |
+| UX flows | [docs/ux-flows.md](docs/ux-flows.md) |
+
+## Recommended IDE Setup
+
+[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).
+
+## License
+
+MIT

docker-compose.yml

@@ -0,0 +1,114 @@
+version: '3.8'
+
+services:
+  # Test service - runs tests only
+  test:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: test
+    container_name: jellytau-test
+    volumes:
+      - .:/app
+    environment:
+      - RUST_BACKTRACE=1
+    command: bash -c "bun run test && cd src-tauri && cargo test && cd .. && echo 'All tests passed!'"
+
+  # Android build service - builds APK after tests pass
+  android-build:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: android-build
+    container_name: jellytau-android-build
+    volumes:
+      - .:/app
+      - android-cache:/root/.cargo
+      - android-bun-cache:/root/.bun
+    environment:
+      - RUST_BACKTRACE=1
+      - ANDROID_HOME=/opt/android-sdk
+    depends_on:
+      - test
+    ports:
+      - "5172:5172"  # In case you want to run dev server
+
+  # Linux desktop packages - deb + rpm + pacman into ./dist
+  desktop-linux-build:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: desktop-linux-build
+      args:
+        # Defaults to the registry builder (Dockerfile's ARG). Point at a locally
+        # built builder with: BUILDER_IMAGE=jellytau-builder:latest docker compose ...
+        BUILDER_IMAGE: ${BUILDER_IMAGE:-gitea.tourolle.paris/dtourolle/jellytau-builder:latest}
+    container_name: jellytau-desktop-linux-build
+    volumes:
+      - .:/app
+      - cargo-cache:/root/.cargo
+      - bun-cache:/root/.bun
+    environment:
+      - RUST_BACKTRACE=1
+      - OUTPUT_DIR=/app/dist
+    command: bash -c "OUTPUT_DIR=/app/dist scripts/build-desktop-linux.sh"
+
+  # Arch Linux package (.pkg.tar.zst via makepkg) into ./dist
+  arch-build:
+    build:
+      context: .
+      dockerfile: Dockerfile.arch
+    container_name: jellytau-arch-build
+    volumes:
+      - ./dist:/out
+    environment:
+      - RUST_BACKTRACE=1
+      - OUTPUT_DIR=/out
+
+  # Windows cross-compile (MSVC via cargo-xwin). Emits NSIS installer + .exe to
+  # ./dist. Override WIN_BUNDLES=none for exe-only.
+  windows-cross:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: windows-cross
+      args:
+        BUILDER_IMAGE: ${BUILDER_IMAGE:-gitea.tourolle.paris/dtourolle/jellytau-builder:latest}
+    container_name: jellytau-windows-cross
+    volumes:
+      - .:/app
+      - cargo-cache:/root/.cargo
+      - bun-cache:/root/.bun
+    environment:
+      - RUST_BACKTRACE=1
+      - OUTPUT_DIR=/app/dist
+      - WIN_BUNDLES=${WIN_BUNDLES:-nsis}
+    command: bash -c "OUTPUT_DIR=/app/dist WIN_BUNDLES=${WIN_BUNDLES:-nsis} scripts/build-windows-cross.sh"
+
+  # Development container - for interactive development
+  dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: builder
+    container_name: jellytau-dev
+    volumes:
+      - .:/app
+      - cargo-cache:/root/.cargo
+      - bun-cache:/root/.bun
+      - node-modules:/app/node_modules
+    environment:
+      - RUST_BACKTRACE=1
+      - ANDROID_HOME=/opt/android-sdk
+      - NDK_HOME=/opt/android-sdk/ndk/27.0.11902837
+    working_dir: /app
+    stdin_open: true
+    tty: true
+    command: /bin/bash
+
+volumes:
+  cargo-cache:
+  bun-cache:
+  android-cache:
+  android-bun-cache:
+  node-modules:

docs-site/SUMMARY.md

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

docs-site/book.toml

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

docs/architecture/01-rust-backend.md

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

docs/architecture/02-svelte-frontend.md

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

docs/architecture/03-data-flow.md

@@ -0,0 +1,163 @@
+# Data Flow
+
+## Repository Query Flow (Cache-First)
+
+```mermaid
+sequenceDiagram
+    participant UI as Svelte Component
+    participant Client as RepositoryClient (TS)
+    participant Rust as Tauri Command
+    participant Hybrid as HybridRepository
+    participant Cache as OfflineRepository (SQLite)
+    participant Server as OnlineRepository (HTTP)
+    participant Conn as ConnectivityMonitor
+
+    UI->>Client: getItems(parentId)
+    Client->>Rust: invoke("repository_get_items", {handle, parentId})
+    Rust->>Hybrid: get_items()
+
+    par Parallel Racing
+        Hybrid->>Cache: get_items() with 100ms timeout
+        Hybrid->>Server: get_items() (no timeout)
+    end
+
+    Note over Server,Conn: Every server request reports its outcome
+    alt Server succeeds (or answers with 4xx/5xx)
+        Server->>Conn: mark_reachable() (server is up)
+    else Network failure / timeout
+        Server->>Conn: mark_unreachable() (debounced)
+    end
+
+    alt Cache returns with content
+        Cache-->>Hybrid: Result with items
+        Hybrid-->>Rust: Return cache result
+    else Cache timeout or empty
+        Server-->>Hybrid: Fresh result
+        Hybrid-->>Rust: Return server result
+    end
+
+    Rust-->>Client: SearchResult
+    Client-->>UI: items[]
+    Note over UI: Reactive update
+```
+
+**Key Points:**
+- Cache queries have 100ms timeout for responsiveness
+- Server queries always run for fresh data
+- Cache wins if it has meaningful content
+- Automatic fallback to server if cache is empty/stale
+- Background cache updates (planned)
+- **Connectivity side-effect**: each server request feeds the `ConnectivityMonitor`, which is the source of truth for the offline/online banner (see [07-connectivity.md](07-connectivity.md)). A server-answered error (401/404/5xx) still counts as *reachable* — only network failures, sustained past a debounce window, flip the app to offline.
+
+## Playback Initiation Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AudioPlayer
+    participant Tauri as Tauri IPC
+    participant Command as player_play_item()
+    participant Controller as PlayerController
+    participant Backend as PlayerBackend
+    participant Store as Frontend Store
+
+    User->>AudioPlayer: clicks play
+    AudioPlayer->>Tauri: invoke("player_play_item", {item})
+    Tauri->>Command: player_play_item()
+    Command->>Command: Convert PlayItemRequest -> MediaItem
+    Command->>Controller: play_item(item)
+    Controller->>Backend: load(item)
+    Note over Backend: State -> Loading
+    Controller->>Backend: play()
+    Note over Backend: State -> Playing
+    Controller-->>Command: Ok(())
+    Command-->>Tauri: PlayerStatus {state, position, duration, volume}
+    Tauri-->>AudioPlayer: status
+    AudioPlayer->>Store: player.setPlaying(media, position, duration)
+    Note over Store: UI updates reactively
+```
+
+## Playback Mode Transfer Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Cast Button
+    participant Store as playbackMode store
+    participant Rust as Tauri Command
+    participant Manager as PlaybackModeManager
+    participant Player as PlayerController
+    participant Jellyfin as Jellyfin API
+
+    UI->>Store: transferToRemote(sessionId)
+    Store->>Rust: invoke("playback_mode_transfer_to_remote", {sessionId})
+    Rust->>Manager: transfer_to_remote()
+
+    Manager->>Player: Get current queue
+    Player-->>Manager: Vec<MediaItem>
+    Manager->>Manager: Extract Jellyfin IDs
+
+    Manager->>Jellyfin: POST /Sessions/{id}/Playing<br/>{itemIds, startIndex}
+    Jellyfin-->>Manager: 200 OK
+
+    Manager->>Jellyfin: POST /Sessions/{id}/Playing/Seek<br/>{positionTicks}
+    Jellyfin-->>Manager: 200 OK
+
+    Manager->>Player: stop()
+    Manager->>Manager: mode = Remote {sessionId}
+
+    Manager-->>Rust: Ok(())
+    Rust-->>Store: PlaybackMode
+    Store->>UI: Update cast icon
+```
+
+## Queue Navigation Flow
+
+```mermaid
+flowchart TB
+    User["User clicks Next"] --> Invoke["invoke('player_next')"]
+    Invoke --> ControllerNext["controller.next()"]
+    ControllerNext --> QueueNext["queue.next()<br/>- Check repeat mode<br/>- Check shuffle<br/>- Update history"]
+
+    QueueNext --> None["None<br/>(at end)"]
+    QueueNext --> Some["Some(next)"]
+    QueueNext --> Same["Same<br/>(repeat one)"]
+
+    Some --> PlayItem["play_item(next)<br/>Returns new status"]
+```
+
+## Volume Control Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Slider as Volume Slider
+    participant Handler as handleVolumeChange()
+    participant Tauri as Tauri IPC
+    participant Command as player_set_volume
+    participant Controller as PlayerController
+    participant Backend as MpvBackend/NullBackend
+    participant Events as playerEvents.ts
+    participant Store as Player Store
+    participant UI
+
+    User->>Slider: adjusts (0-100)
+    Slider->>Handler: oninput event
+    Handler->>Handler: Convert 0-100 -> 0.0-1.0
+    Handler->>Tauri: invoke("player_set_volume", {volume})
+    Tauri->>Command: player_set_volume
+    Command->>Controller: set_volume(volume)
+    Controller->>Backend: set_volume(volume)
+    Backend->>Backend: Clamp to 0.0-1.0
+    Note over Backend: MpvBackend: Send to MPV loop
+    Backend-->>Tauri: emit "player-event"
+    Tauri-->>Events: VolumeChanged event
+    Events->>Store: player.setVolume(volume)
+    Store-->>UI: Reactive update
+    Note over UI: Both AudioPlayer and<br/>MiniPlayer stay in sync
+```
+
+**Key Implementation Details:**
+- Volume is stored in the backend (NullBackend/MpvBackend)
+- `PlayerController.volume()` delegates to backend
+- `get_player_status()` returns `controller.volume()` (not hardcoded)
+- Frontend uses normalized 0.0-1.0 scale, UI shows 0-100

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

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

docs/architecture/05-platform-backends.md

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

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

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

docs/architecture/07-connectivity.md

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

docs/architecture/08-database-design.md

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

docs/architecture/09-security.md

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

docs/architecture/README.md

@@ -0,0 +1,210 @@
+# JellyTau Software Architecture
+
+This document describes the current architecture of JellyTau, a cross-platform Jellyfin client built with Tauri, SvelteKit, and Rust.
+
+**Last Updated:** 2026-06-20
+
+## Architecture Overview
+
+JellyTau uses a client-server architecture: business logic lives in a comprehensive Rust backend, while a UI-rich Svelte frontend handles presentation and interaction.
+
+### Architecture Principles
+
+- **Business Logic in Rust**: Core logic — playback, repository, sync, downloads, connectivity — lives in Rust for performance, reliability, and type safety.
+- **Presentation in Svelte**: The frontend (~20.5k non-test lines) owns UI, layout, navigation, and interaction state and invokes Rust commands. It is intentionally UI-heavy, **not** a thin wrapper. Largest pieces: components + routes (~14.6k lines), stores (~3.4k), api/services/utils (~2.4k); `VideoPlayer.svelte` alone is ~1.6k lines.
+- **Events + Polling hybrid**: Rust emits events the frontend listens to, and the UI also polls status on short intervals in a few hot spots (e.g. queue status in `library/+layout.svelte`, playback progress in `VideoPlayer.svelte`).
+- **Unified player boundary**: UI components control playback only through the frontend facade `src/lib/player/index.ts` (`playerController`), never by calling `commands.player*` directly. Webview-rendered HTML5 video reports its state back into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*` commands, so the `PlayerController` stays the single source of truth in both native (MPV/ExoPlayer) and HTML5 modes (see [05-platform-backends.md](05-platform-backends.md)).
+- **Handle-Based Resources**: UUID handles for stateful Rust objects.
+- **Cache-First**: Parallel queries with intelligent fallback.
+- **Single source of truth for reachability**: Server reachability is derived from the outcome of *real repository traffic*, not a side-channel poller. The `OnlineRepository` reports each server result to the `ConnectivityMonitor` (classified via `RepoError`), which applies a time-window debounce before declaring the server offline and recovers instantly on the first success. The standalone `/System/Info/Public` probe runs *only while offline*, as a recovery detector for idle sessions.
+- **Poison-tolerant locking**: Shared `std::sync` state is accessed via the `MutexSafe`/`RwLockSafe` helpers in `utils/lock.rs`, which recover a poisoned lock instead of cascading a panic across the player.
+- **Graceful backend init**: If a native player backend (MPV/ExoPlayer) fails to initialize, the app falls back to a no-op backend and emits a `backend-init-failed` event rather than crashing.
+
+```mermaid
+flowchart TB
+    subgraph Frontend["Svelte Frontend"]
+        subgraph Stores["Stores (Thin Wrappers)"]
+            auth["auth"]
+            player["player"]
+            queue["queue"]
+            library["library"]
+            connectivity["connectivity"]
+            playbackMode["playbackMode"]
+        end
+        subgraph Components
+            playerComp["player/"]
+            libraryComp["library/"]
+            Search["Search"]
+        end
+        subgraph Routes
+            routeLibrary["/library"]
+            routePlayer["/player"]
+            routeRoot["/"]
+        end
+        subgraph API["API Layer (Thin Client)"]
+            RepositoryClient["RepositoryClient<br/>(Handle-based)"]
+            JellyfinClient["JellyfinClient<br/>(Helper)"]
+        end
+    end
+
+    Frontend -->|"Tauri IPC (invoke)"| Backend
+
+    subgraph Backend["Rust Backend (Business Logic)"]
+        subgraph Commands["Tauri Commands (90+)"]
+            PlayerCmds["player.rs"]
+            RepoCmds["repository.rs (27)"]
+            PlaybackModeCmds["playback_mode.rs (5)"]
+            StorageCmds["storage.rs"]
+            ConnectivityCmds["connectivity.rs (7)"]
+        end
+
+        subgraph Core["Core Modules"]
+            MediaSessionManager["MediaSessionManager<br/>(Audio/Movie/TvShow/Idle)"]
+
+            PlayerController["PlayerController<br/>+ PlayerBackend<br/>+ QueueManager"]
+
+            Repository["Repository Layer<br/>HybridRepository (cache-first)<br/>OnlineRepository (HTTP)<br/>OfflineRepository (SQLite)"]
+
+            PlaybackModeManager["PlaybackModeManager<br/>(Local/Remote/Idle)"]
+
+            ConnectivityMonitor["ConnectivityMonitor<br/>(Adaptive polling)"]
+
+            HttpClient["HttpClient<br/>(Exponential backoff retry)"]
+        end
+
+        subgraph Storage["Storage Layer"]
+            DatabaseService["DatabaseService<br/>(Async trait)"]
+            SQLite["SQLite Database<br/>(13 tables)"]
+        end
+
+        Commands --> Core
+        Core --> Storage
+        Repository --> HttpClient
+        Repository --> DatabaseService
+        Repository -->|"reports server outcome<br/>(success / RepoError)"| ConnectivityMonitor
+    end
+```
+
+> The `Repository --> ConnectivityMonitor` edge is the source of truth for the offline/online banner: every server request the user actually makes updates reachability. The monitor's own polling is now an offline-only recovery probe (see [07-connectivity.md](07-connectivity.md)).
+
+---
+
+## Detailed Documentation
+
+Each major subsystem is documented in its own file in this directory:
+
+| Document | Contents |
+|----------|----------|
+| [01 - Rust Backend](01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
+| [02 - Svelte Frontend](02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
+| [03 - Data Flow](03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
+| [04 - Type Sync & Threading](04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
+| [05 - Platform Backends](05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
+| [06 - Downloads & Offline](06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
+| [07 - Connectivity](07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
+| [08 - Database Design](08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
+| [09 - Security](09-security.md) | Authentication token storage, secure storage module, network security, local data protection |
+
+---
+
+## File Structure Summary
+
+```
+src-tauri/src/
+├── lib.rs                    # Tauri app setup, state initialization
+├── commands/                 # Tauri command handlers (90+ commands)
+│   ├── mod.rs               # Command exports
+│   ├── player.rs            # 16 player commands
+│   ├── repository.rs        # 27 repository commands
+│   ├── playlist.rs          # 7 playlist commands
+│   ├── playback_mode.rs     # 5 playback mode commands
+│   ├── connectivity.rs      # 7 connectivity commands
+│   ├── storage.rs           # Storage & database commands
+│   ├── download.rs          # 7 download commands
+│   ├── offline.rs           # 3 offline commands
+│   └── sync.rs              # Sync queue commands
+├── repository/              # Repository pattern implementation
+│   ├── mod.rs               # MediaRepository trait, handle management
+│   ├── types.rs             # RepoError, Library, MediaItem, etc.
+│   ├── hybrid.rs            # HybridRepository with cache-first racing
+│   ├── online.rs            # OnlineRepository (HTTP API)
+│   └── offline.rs           # OfflineRepository (SQLite queries)
+├── playback_mode/           # Playback mode manager
+│   └── mod.rs               # PlaybackMode enum, transfer logic
+├── connectivity/            # Connectivity monitoring
+│   └── mod.rs               # ConnectivityMonitor, adaptive polling
+├── jellyfin/                # Jellyfin API client
+│   ├── mod.rs               # Module exports
+│   ├── http_client.rs       # HTTP client with retry logic
+│   └── client.rs            # JellyfinClient for API calls
+├── storage/                 # Database layer
+│   ├── mod.rs               # Database struct, migrations
+│   ├── db_service.rs        # DatabaseService trait (async wrapper)
+│   ├── schema.rs            # Table definitions
+│   └── queries/             # Query modules
+├── download/                # Download manager module
+│   ├── mod.rs               # DownloadManager, DownloadInfo, DownloadTask
+│   ├── worker.rs            # DownloadWorker, HTTP streaming, retry logic
+│   ├── events.rs            # DownloadEvent enum
+│   └── cache.rs             # SmartCache, CacheConfig, LRU eviction
+└── player/                  # Player subsystem
+    ├── mod.rs               # PlayerController
+    ├── session.rs           # MediaSessionManager, MediaSessionType
+    ├── state.rs             # PlayerState, PlayerEvent
+    ├── media.rs             # MediaItem, MediaSource, MediaType
+    ├── queue.rs             # QueueManager, RepeatMode
+    ├── backend.rs           # PlayerBackend trait, NullBackend
+    ├── events.rs            # PlayerStatusEvent, TauriEventEmitter
+    ├── mpv/                 # Linux MPV backend
+    │   ├── mod.rs           # MpvBackend implementation
+    │   └── event_loop.rs    # Dedicated thread for MPV operations
+    └── android/             # Android ExoPlayer backend
+        └── mod.rs           # ExoPlayerBackend + JNI bindings
+
+src/lib/
+├── api/                     # Thin API layer (~200 lines total)
+│   ├── types.ts             # TypeScript type definitions
+│   ├── repository-client.ts # RepositoryClient wrapper (~100 lines)
+│   ├── client.ts            # JellyfinClient (helper for streaming)
+│   └── sessions.ts          # SessionsApi (remote session control)
+├── player/                  # Unified player boundary (frontend)
+│   ├── index.ts             # playerController facade — the only write-side entry point for playback
+│   └── html5Adapter.ts      # Reports webview <video> DOM events back into Rust (player_report_*)
+├── services/
+│   ├── playerEvents.ts      # Tauri event listener for player events
+│   └── playbackReporting.ts # Thin wrapper (~50 lines)
+├── stores/                  # Thin reactive wrappers over Rust commands
+│   ├── index.ts             # Re-exports
+│   ├── auth.ts              # Auth store (calls Rust commands)
+│   ├── player.ts            # Player store
+│   ├── queue.ts             # Queue store
+│   ├── library.ts           # Library store
+│   ├── playbackMode.ts      # Playback mode store (~150 lines)
+│   ├── connectivity.ts      # Connectivity store (~250 lines)
+│   └── downloads.ts         # Downloads store with event listeners
+└── components/
+    ├── Search.svelte
+    ├── player/              # Player UI components
+    ├── playlist/            # Playlist modals (Create, AddTo)
+    ├── sessions/            # Remote session control UI
+    ├── downloads/           # Download UI components
+    └── library/             # Library UI components + PlaylistDetailView
+```
+
+## Key Architecture Changes
+
+**What moved to Rust (~3,500 lines of business logic):**
+1. **HTTP Client** (338 lines) - Retry logic with exponential backoff
+2. **Connectivity Monitor** (301 lines) - Reachability derived from real repository traffic, time-window debounce, offline-only recovery probe, event emission
+3. **Repository Pattern** (1061 lines) - Cache-first hybrid with parallel racing
+4. **Database Service** - Async wrapper preventing UI freezing
+5. **Playback Mode** (303 lines) - Local/remote transfer coordination
+
+**Svelte/TypeScript frontend (~20.5k non-test lines, plus ~9.6k test lines):**
+- Components + routes (~14.6k lines) — UI and presentation
+- Stores (~3.4k lines) — reactive state that invokes Rust commands and listens for events
+- api / services / utils (~2.4k lines) — typed clients, event listeners, conversion helpers
+
+The frontend is genuinely UI-heavy; business decisions live in Rust, but the UI owns layout, navigation, and interaction state.
+
+**Total Commands:** 90+ Tauri commands across 14 command modules

docs/build-desktop-packages.md

@@ -0,0 +1,91 @@
+# Desktop packaging (Linux, Arch, Windows)
+
+How to produce distributable desktop packages for JellyTau. All three flows can
+run in Docker so no host toolchain setup is required. Outputs land in `./dist`.
+
+## One builder image (shared with CI)
+
+The deb/rpm and Windows-cross flows build on the **unified registry builder**
+([../Dockerfile.builder](../Dockerfile.builder) →
+`gitea.tourolle.paris/dtourolle/jellytau-builder`), the same image CI uses. It
+carries every packaging tool: Android SDK/NDK, `rpm`/`file` (Linux bundler),
+`cargo-xwin` + `lld` + `llvm` + `nsis` + the `x86_64-pc-windows-msvc` rust target
+(Windows). There is **one** dependency source of truth — no per-stage tool
+installs.
+
+The desktop stages in [../Dockerfile](../Dockerfile) are thin `FROM
+${BUILDER_IMAGE}` environments; the actual build runs at container-run time on
+your bind-mounted source (like the `dev` service), so source edits need no image
+rebuild.
+
+**If you changed `Dockerfile.builder`** (e.g. added a tool), rebuild and push it
+first, or the packaging flows use the stale registry image:
+
+```bash
+scripts/build-builder-image.sh           # build + push :latest to the registry
+# ...or iterate locally without pushing:
+docker build -f Dockerfile.builder -t jellytau-builder:latest .
+BUILDER_IMAGE=jellytau-builder:latest bun run docker:build:windows
+```
+
+Arch uses a separate `archlinux` image ([../Dockerfile.arch](../Dockerfile.arch))
+because `makepkg` is Arch-specific — it is not part of the unified builder.
+
+| Target | Format | Docker command | Functional? |
+|--------|--------|----------------|-------------|
+| Debian/Ubuntu, Fedora | `.deb`, `.rpm` | `bun run docker:build:linux` | ✅ yes |
+| Arch Linux | `.pkg.tar.zst` | `bun run docker:build:arch` | ✅ yes |
+| Windows | NSIS installer + `.exe` | `bun run docker:build:windows` | ✅ yes (unsigned) |
+
+## Linux: deb + rpm
+
+Tauri's bundler produces these natively. The build runs on the existing Ubuntu
+builder image ([../Dockerfile](../Dockerfile), `desktop-linux-build` stage):
+
+```bash
+bun run docker:build:linux            # deb + rpm -> ./dist
+# or, on a host with the Tauri Linux deps installed:
+BUNDLES="deb,rpm" scripts/build-desktop-linux.sh
+```
+
+Runtime dependency: the app links libmpv (audio) and WebKitGTK (webview + HTML5
+transcoded video). The deb/rpm declare these.
+
+> Note: `appimage` is also a valid Tauri target if you want a portable bundle —
+> add it to `BUNDLES`.
+
+## Arch Linux: pacman package
+
+**Tauri has no `pacman` bundle target** (as of tauri-cli 2.9.x — valid targets
+are deb/rpm/appimage/msi/nsis/app/dmg). So we ship a hand-written PKGBUILD in
+[../packaging/arch/PKGBUILD](../packaging/arch/PKGBUILD) and build it with
+`makepkg` on an Arch base image ([../Dockerfile.arch](../Dockerfile.arch)):
+
+```bash
+bun run docker:build:arch             # .pkg.tar.zst -> ./dist
+```
+
+The PKGBUILD is AUR-ready: swap its `source=()` for a release tarball/VCS URL to
+publish. Runtime deps: `webkit2gtk-4.1`, `mpv`, `gtk3`, `libayatana-appindicator`.
+
+`makepkg` refuses to run as root, so the Docker stage builds as a non-root
+`builder` user. Because the image `COPY`s the source at build time, the
+`arch-build` compose service does **not** bind-mount the repo — rebuild the image
+to pick up source changes.
+
+## Windows: NSIS installer cross-compiled from Linux
+
+Produces a working (unsigned) NSIS installer + `.exe` via the official Tauri
+cross-compile path — the `x86_64-pc-windows-msvc` target driven by `cargo-xwin`.
+Video plays via WebView2 and audio via the webview `<audio>` backend. See
+[build-windows.md](build-windows.md) for the full explanation.
+
+```bash
+bun run docker:build:windows                     # NSIS installer + .exe -> ./dist
+WIN_BUNDLES=none bun run docker:build:windows     # exe only, skip bundling
+```
+
+The Docker `windows-cross` stage is a thin layer over the builder, which carries
+`cargo-xwin` + `lld` + `llvm` + `nsis` + the `x86_64-pc-windows-msvc` target.
+Cross-compilation is Tauri's "last resort" path (less tested than building on
+Windows); a `windows-latest` CI job is the fallback if it misbehaves.

docs/build-release.md

@@ -0,0 +1,347 @@
+# Build & Release Workflow
+
+This document explains the automated build and release process for JellyTau.
+
+## Overview
+
+The CI/CD pipeline automatically:
+1. ✅ Runs all tests (frontend + Rust)
+2. ✅ Builds Linux binaries (AppImage + DEB)
+3. ✅ Builds Android APK and AAB
+4. ✅ Creates releases with artifacts
+5. ✅ Tags releases with version numbers
+
+## Workflow Triggers
+
+### Automatic Trigger
+When you push a version tag:
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The workflow automatically:
+1. Runs tests
+2. Builds both platforms
+3. Creates a GitHub release with artifacts
+4. Tags it as release/prerelease based on version
+
+### Manual Trigger
+In Gitea Actions UI:
+1. Go to **Actions** tab
+2. Click **Build & Release** workflow
+3. Click **Run workflow**
+4. Optionally specify a version
+5. Workflow runs without creating a release
+
+## Version Tagging
+
+### Format
+Version tags follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`
+
+Examples:
+- `v1.0.0` - Release version
+- `v1.0.0-rc1` - Release candidate (marked as prerelease)
+- `v1.0.0-beta` - Beta version (marked as prerelease)
+- `v0.1.0-alpha` - Alpha version (marked as prerelease)
+
+### Creating a Release
+
+```bash
+# Create and push a version tag
+git tag v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+
+# Or create from main branch
+git tag -a v1.0.0 -m "Release version 1.0.0" main
+git push origin v1.0.0
+```
+
+### Release Status
+
+Versions containing `rc`, `beta`, or `alpha` are marked as **prerelease**:
+```bash
+git tag v1.0.0-rc1      # ⚠️ Prerelease
+git tag v1.0.0-beta     # ⚠️ Prerelease
+git tag v1.0.0-alpha    # ⚠️ Prerelease
+git tag v1.0.0          # ✅ Full release
+```
+
+## Workflow Steps
+
+### 1. Test Phase
+Runs on all tags and manual triggers:
+- Frontend tests (`vitest`)
+- Rust tests (`cargo test`)
+- TypeScript type checking
+
+**Failure:** Stops workflow, no build/release
+
+### 2. Build Linux Phase
+Runs after tests pass:
+- Installs system dependencies
+- Builds with Tauri
+- Generates:
+  - **AppImage** - Universal Linux binary
+  - **DEB** - Debian/Ubuntu package
+
+**Output:** `artifacts/linux/`
+
+### 3. Build Android Phase
+Runs in parallel with Linux build:
+- Installs Android SDK/NDK
+- Configures Rust for Android targets
+- Builds with Tauri
+- Generates:
+  - **APK** - Android app package (installable)
+  - **AAB** - Android App Bundle (for Play Store)
+
+**Output:** `artifacts/android/`
+
+### 4. Create Release Phase
+Runs after both builds succeed (only on version tags):
+- Prepares release notes
+- Downloads build artifacts
+- Creates GitHub/Gitea release
+- Uploads all artifacts
+- Tags as prerelease if applicable
+
+## Artifacts
+
+### Linux Artifacts
+
+#### AppImage
+- **File:** `jellytau_*.AppImage`
+- **Size:** ~100-150 MB
+- **Use:** Run directly on any Linux distro
+- **Installation:**
+  ```bash
+  chmod +x jellytau_*.AppImage
+  ./jellytau_*.AppImage
+  ```
+
+#### DEB Package
+- **File:** `jellytau_*.deb`
+- **Size:** ~80-120 MB
+- **Use:** Install on Debian/Ubuntu/similar
+- **Installation:**
+  ```bash
+  sudo dpkg -i jellytau_*.deb
+  jellytau
+  ```
+
+### Android Artifacts
+
+#### APK
+- **File:** `jellytau-release.apk`
+- **Size:** ~60-100 MB
+- **Use:** Direct installation on Android devices
+- **Installation:**
+  ```bash
+  adb install jellytau-release.apk
+  # Or sideload via file manager
+  ```
+
+#### AAB (Android App Bundle)
+- **File:** `jellytau-release.aab`
+- **Size:** ~50-90 MB
+- **Use:** Upload to Google Play Console
+- **Note:** Cannot be installed directly; for Play Store distribution
+
+## Release Notes
+
+Release notes are automatically generated with:
+- Version number
+- Download links
+- Installation instructions
+- System requirements
+- Known issues link
+- Changelog reference
+
+## Build Matrix
+
+| Platform | OS | Architecture | Format |
+|----------|----|----|--------|
+| **Linux** | Any | x86_64 | AppImage, DEB |
+| **Android** | 8.0+ | arm64, armv7, x86_64 | APK, AAB |
+
+## Troubleshooting
+
+### Build Fails During Test Phase
+1. Check test output in Gitea Actions
+2. Run tests locally: `bun run test` and `bun run test:rust`
+3. Fix failing tests
+4. Create new tag with fixed code
+
+### Linux Build Fails
+1. Check system dependencies installed
+2. Verify Tauri configuration
+3. Check cargo dependencies
+4. Clear cache: Delete `.cargo` and `target/` directories
+
+### Android Build Fails
+1. Check Android SDK/NDK setup
+2. Verify Java 17 is installed
+3. Check Rust Android targets: `rustup target list`
+4. Clear cache and rebuild
+
+### Release Not Created
+1. Tag must start with `v` (e.g., `v1.0.0`)
+2. Tests must pass
+3. Both builds must succeed
+4. Check workflow logs for errors
+
+## GitHub Release vs Gitea
+
+The workflow uses GitHub Actions SDK but is designed for Gitea. For Gitea-native releases:
+
+1. Workflow creates artifacts
+2. Artifacts are available in Actions artifacts
+3. Download and manually create Gitea release, or
+4. Set up Gitea API integration to auto-publish
+
+## Customization
+
+### Change Release Notes Template
+
+Edit `.gitea/workflows/build-release.yml`, section `Prepare release notes`:
+
+```yaml
+- name: Prepare release notes
+  id: release_notes
+  run: |
+    # Add your custom release notes format here
+    echo "Custom notes" > release_notes.md
+```
+
+### Add New Platforms
+
+To add macOS or Windows builds:
+
+1. Add new `build-{platform}` job
+2. Set appropriate `runs-on` runner
+3. Add platform-specific dependencies
+4. Update artifact upload
+5. Include in `needs: [build-linux, build-android, build-{platform}]`
+
+### Change Build Targets
+
+Modify Tauri configuration or add targets:
+
+```yaml
+- name: Build for Linux
+  run: |
+    # Add target specification
+    bun run tauri build -- --target x86_64-unknown-linux-gnu
+```
+
+## Monitoring
+
+### Check Status
+1. Go to **Actions** tab in Gitea
+2. View **Build & Release** workflow runs
+3. Click specific run to see logs
+
+### Notifications
+Set up notifications for:
+- Build failures
+- Release creation
+- Tag pushes
+
+## Performance
+
+### Build Times (Approximate)
+- Test phase: 5-10 minutes
+- Linux build: 10-15 minutes
+- Android build: 15-20 minutes
+- Total: 30-45 minutes
+
+### Caching
+Workflow caches:
+- Rust dependencies (cargo)
+- Bun node_modules
+- Android SDK components
+
+## Security
+
+### Secrets
+The workflow uses:
+- `GITHUB_TOKEN` - Built-in, no setup needed
+- No credentials needed for Gitea
+
+### Verification
+To verify build integrity:
+1. Download artifacts
+2. Verify signatures (if implemented)
+3. Check file hashes
+4. Test on target platform
+
+## Best Practices
+
+### Versioning
+1. Follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`
+2. Tag releases in git
+3. Update CHANGELOG.md before tagging
+4. Include release notes in tag message
+
+### Testing Before Release
+```bash
+# Local testing before release
+bun run test          # Frontend tests
+bun run test:rust     # Rust tests
+bun run check         # Type checking
+bun run tauri build   # Local build test
+```
+
+### Documentation
+1. Update [CHANGELOG.md](../CHANGELOG.md) with changes
+2. Update [README.md](../README.md) with new features
+3. Document breaking changes
+4. Add migration guide if needed
+
+## Example Release Workflow
+
+```bash
+# 1. Update version in relevant files (package.json, Cargo.toml, etc.)
+vim package.json
+vim src-tauri/tauri.conf.json
+
+# 2. Update CHANGELOG
+vim CHANGELOG.md
+
+# 3. Commit changes
+git add .
+git commit -m "Bump version to v1.0.0"
+
+# 4. Create annotated tag
+git tag -a v1.0.0 -m "Release version 1.0.0
+
+Features:
+- Feature 1
+- Feature 2
+
+Fixes:
+- Fix 1
+- Fix 2"
+
+# 5. Push tag to trigger workflow
+git push origin v1.0.0
+
+# 6. Monitor workflow in Gitea Actions
+# Wait for tests → Linux build → Android build → Release
+
+# 7. Download artifacts and test
+# Visit release page and verify downloads
+```
+
+## References
+
+- [Tauri Documentation](https://tauri.app/)
+- [Semantic Versioning](https://semver.org/)
+- [GitHub Release Best Practices](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
+- [Android App Bundle](https://developer.android.com/guide/app-bundle)
+- [AppImage Documentation](https://docs.appimage.org/)
+
+---
+
+**Last Updated:** 2026-02-13

docs/build-windows.md

@@ -0,0 +1,78 @@
+# Windows build
+
+JellyTau targets Linux and Android primarily, but a working Windows build —
+including an **NSIS installer cross-compiled from Linux** — is produced by the
+Docker tooling. It is not yet a first-class release target (no code signing / CI
+job / SMTC lockscreen), but it runs and plays media.
+
+## How playback works on Windows
+
+- **Video** — renders through the webview HTML5 `<video>` element (hls.js) on
+  *every* platform; on Windows that is WebView2 (Chromium/Edge), which plays HLS +
+  h264 fine. No Windows-specific code.
+- **Audio-only (music)** — the native audio backends are libmpv (Linux) and
+  ExoPlayer (Android); neither exists on Windows. Instead
+  `create_player_backend()` in [../src-tauri/src/lib.rs](../src-tauri/src/lib.rs)
+  uses `WebviewAudioBackend` on non-Linux/non-Android targets: it hands the stream
+  URL to a webview `<audio>` element (see
+  [../src/lib/services/webviewAudio.ts](../src/lib/services/webviewAudio.ts)),
+  which reports state back through the same `player_report_*` round-trip the video
+  path uses. Pure Rust + Tauri events.
+
+## Cross-compiling from Linux (MSVC + cargo-xwin)
+
+We use the [official Tauri cross-compile path](https://v2.tauri.app/distribute/windows-installer/):
+the **MSVC** target (`x86_64-pc-windows-msvc`) driven by
+[`cargo-xwin`](https://github.com/rust-cross/cargo-xwin), which downloads the MSVC
+CRT / Windows SDK headers and links with `lld`. MSVC is the target Tauri
+officially supports for Windows (mingw/GNU is not), and — unlike GNU — it lets the
+Tauri CLI bundle the **NSIS installer from a Linux host**.
+
+> Why not mingw/GNU? The GNU target *does* link a valid `.exe`, but the Tauri CLI
+> gates `--bundles` by the host OS unless it recognizes a real Windows build.
+> `--runner cargo-xwin --target x86_64-pc-windows-msvc` is what flips it into
+> Windows mode and enables the `nsis`/`msi` bundlers on Linux.
+
+The builder image ([../Dockerfile.builder](../Dockerfile.builder)) bakes in the
+whole toolchain: the `x86_64-pc-windows-msvc` rust target, `cargo-xwin`, `lld`,
+`llvm`, and `nsis`.
+
+```bash
+bun run docker:build:windows            # NSIS installer + .exe -> ./dist
+WIN_BUNDLES=none bun run docker:build:windows   # exe only, skip bundling
+```
+
+Or directly on a host that has the toolchain:
+
+```bash
+scripts/build-windows-cross.sh                    # nsis installer + exe
+WIN_BUNDLES=none scripts/build-windows-cross.sh   # exe only
+```
+
+Under the hood the build runs:
+
+```bash
+tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc --bundles nsis
+```
+
+Outputs:
+- `.exe` — `src-tauri/target/x86_64-pc-windows-msvc/release/jellytau.exe`
+- NSIS installer — `.../release/bundle/nsis/*-setup.exe`
+
+(both copied to `./dist` when `OUTPUT_DIR` is set).
+
+## Caveats
+
+- **Cross-compilation is a last resort** per Tauri's own docs — it's less tested
+  than building on Windows. If it misbehaves, a `windows-latest` CI job or a
+  Windows VM building natively (`tauri build --bundles nsis`) is the fallback.
+- **Code signing is not wired up** — the installer is unsigned, so Windows
+  SmartScreen will warn on first run.
+
+## Outstanding for a first-class Windows release
+
+1. Gapless/crossfade + SMTC (lockscreen) — currently no-ops in the webview audio
+   path.
+2. Downloaded (`Local` source) file playback needs `convertFileSrc` on the
+   frontend; streaming works today.
+3. Code signing + a Windows packaging CI job.

docs/build/build-builder-image.md

@@ -0,0 +1,156 @@
+# Building and Pushing the JellyTau Builder Image
+
+This document explains how to create and push the pre-built builder Docker image to your registry for use in Gitea Act CI/CD.
+
+## Prerequisites
+
+- Docker installed and running
+- Access to your Docker registry (e.g., `gitea.tourolle.paris`)
+- Docker registry credentials configured (`docker login`)
+
+## Building the Builder Image
+
+### Step 1: Build the Image Locally
+
+```bash
+# From the project root
+docker build -f Dockerfile.builder -t jellytau-builder:latest .
+```
+
+This creates a local image with:
+- All system dependencies
+- Rust with Android targets
+- Android SDK and NDK
+- Node.js and Bun
+- All build tools pre-installed
+
+### Step 2: Tag for Your Registry
+
+Replace `gitea.tourolle.paris/dtourolle` with your actual registry path:
+
+```bash
+docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+```
+
+### Step 3: Login to Your Registry
+
+If not already logged in:
+
+```bash
+docker login gitea.tourolle.paris
+```
+
+### Step 4: Push to Registry
+
+```bash
+docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+```
+
+## Complete One-Liner
+
+```bash
+docker build -f Dockerfile.builder -t jellytau-builder:latest . && \
+docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest && \
+docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+```
+
+## Verifying the Build
+
+Check that the image was pushed successfully:
+
+```bash
+# List images in your registry (depends on registry API support)
+docker search gitea.tourolle.paris/dtourolle/jellytau-builder
+
+# Or pull and test locally
+docker pull gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+docker run -it gitea.tourolle.paris/dtourolle/jellytau-builder:latest bun --version
+```
+
+## Using in CI/CD
+
+The workflow at `.gitea/workflows/build-and-test.yml` automatically uses:
+```yaml
+container:
+  image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+```
+
+Once pushed, your CI/CD pipeline will use this pre-built image instead of installing everything during the build, saving significant time.
+
+## Updating the Builder Image
+
+When dependencies change (new Rust version, Android SDK update, etc.):
+
+1. Update `Dockerfile.builder` with the new configuration
+2. Rebuild and push with a new tag:
+
+```bash
+docker build -f Dockerfile.builder -t jellytau-builder:v1.2.0 .
+docker tag jellytau-builder:v1.2.0 gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
+docker push gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
+```
+
+3. Update the workflow to use the new tag:
+
+```yaml
+container:
+  image: gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
+```
+
+## Image Contents
+
+The builder image includes:
+
+- **Base OS**: Ubuntu 24.04
+- **Languages**:
+  - Rust (stable) with targets: aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android
+  - Node.js 20.x
+  - OpenJDK 17 (for Android)
+- **Tools**:
+  - Bun package manager
+  - Android SDK 34
+  - Android NDK 27.0.11902837
+  - Build essentials (gcc, make, etc.)
+  - Git, curl, wget
+  - libssl, libclang development libraries
+- **Pre-configured**:
+  - Rust toolchain components (rustfmt, clippy)
+  - Android SDK/NDK environment variables
+  - All paths optimized for building
+
+## Build Time
+
+First build takes ~15-20 minutes depending on internet speed (downloads Android SDK/NDK).
+Subsequent builds are cached and take seconds.
+
+## Storage
+
+The built image is approximately **4-5 GB**. Ensure your registry has sufficient storage.
+
+## Troubleshooting
+
+### "Image not found" in CI
+- Verify the image name matches exactly in the workflow
+- Check that the image was successfully pushed: `docker push` output should show successful layers
+- Ensure Gitea has access to your registry (check network/firewall)
+
+### Build fails with "command not found"
+- The image may not have finished pushing. Wait a few moments and retry the CI job.
+- Check that all layers were pushed successfully in the push output.
+
+### Registry authentication in CI
+If your registry requires credentials in CI:
+1. Create a deploy token in your registry
+2. Add to Gitea secrets as `REGISTRY_USERNAME` and `REGISTRY_TOKEN`
+3. Use in workflow:
+```yaml
+- name: Login to Registry
+  run: |
+    docker login gitea.tourolle.paris -u ${{ secrets.REGISTRY_USERNAME }} -p ${{ secrets.REGISTRY_TOKEN }}
+```
+
+## References
+
+- [Docker Build Documentation](https://docs.docker.com/build/)
+- [Docker Push Documentation](https://docs.docker.com/engine/reference/commandline/push/)
+- [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/)

docs/build/docker.md

@@ -0,0 +1,282 @@
+# Docker & CI/CD Setup for JellyTau
+
+This document explains how to use the Docker configuration and Gitea Act CI/CD pipeline for building and testing JellyTau.
+
+## Overview
+
+The setup includes:
+- **Dockerfile.builder**: Pre-built image with all dependencies (push to your registry)
+- **Dockerfile**: Multi-stage build for local testing and building
+- **docker-compose.yml**: Orchestration for local development and testing
+- **.gitea/workflows/build-and-test.yml**: Automated CI/CD pipeline using pre-built builder image
+
+### Quick Start
+
+**For CI/CD (Gitea Actions)**:
+1. Build and push builder image (see [build-builder-image.md](build-builder-image.md))
+2. Push to master branch - workflow runs automatically
+3. Check Actions tab for results and APK artifacts
+
+**For Local Testing**:
+```bash
+docker-compose run test       # Run tests
+docker-compose run android-build  # Build APK
+docker-compose run dev        # Interactive shell
+```
+
+## Docker Usage
+
+### Prerequisites
+
+- Docker Engine 20.10+
+- Docker Compose 2.0+ (if using docker-compose)
+- At least 10GB free disk space (for Android SDK and build artifacts)
+
+### Building the Docker Image
+
+```bash
+# Build the complete image
+docker build -t jellytau:latest .
+
+# Build specific target
+docker build -t jellytau:test --target test .
+docker build -t jellytau:android --target android-build .
+```
+
+### Using Docker Compose
+
+#### Run Tests Only
+```bash
+docker-compose run test
+```
+
+This will:
+1. Install all dependencies
+2. Run frontend tests (Vitest)
+3. Run Rust backend tests
+4. Report results
+
+#### Build Android APK
+```bash
+docker-compose run android-build
+```
+
+This will:
+1. Run tests first (depends on test service)
+2. If tests pass, build the Android APK
+3. Output APK files to `src-tauri/gen/android/app/build/outputs/apk/`
+
+#### Interactive Development
+```bash
+docker-compose run dev
+```
+
+This starts an interactive shell with all development tools available. From here you can:
+```bash
+bun install
+bun run build
+bun test
+bun run tauri android build --apk true
+```
+
+#### Run All Services in Sequence
+```bash
+docker-compose up --abort-on-container-exit
+```
+
+### Extracting Build Artifacts
+
+After a successful build, APK files are located in:
+```
+src-tauri/gen/android/app/build/outputs/apk/
+```
+
+Copy to your host machine:
+```bash
+docker cp jellytau-android-build:/app/src-tauri/gen/android/app/build/outputs/apk ./apk-output
+```
+
+## Gitea Act CI/CD Pipeline
+
+The `.gitea/workflows/build-and-test.yml` workflow automates:
+
+**Single Job**: Runs on every push to `master` and PRs
+- Uses pre-built builder image (no setup time)
+- Installs project dependencies
+- Runs frontend tests (Vitest)
+- Runs Rust backend tests
+- Builds the frontend
+- Builds the Android APK
+- Uploads APK as artifact (30-day retention)
+
+The workflow skips markdown files to avoid unnecessary builds.
+
+### Workflow Triggers
+
+The workflow runs on:
+- Push to `master` or `main` branches
+- Pull requests to `master` or `main` branches
+- Can be extended with: `workflow_dispatch` for manual triggers
+
+### Setting Up the Builder Image
+
+Before using the CI/CD pipeline, you must build and push the builder image:
+
+```bash
+# Build the image
+docker build -f Dockerfile.builder -t jellytau-builder:latest .
+
+# Tag for your registry
+docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+
+# Push to registry
+docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
+```
+
+See [build-builder-image.md](build-builder-image.md) for detailed instructions.
+
+### Setting Up Gitea Act
+
+1. **Ensure builder image is pushed** (see above)
+
+2. **Push to Gitea repository**:
+   The workflow will automatically trigger on push to `master` or pull requests
+
+3. **View workflow runs in Gitea UI**:
+   - Navigate to your repository
+   - Go to Actions tab
+   - Click on workflow runs to see logs
+
+4. **Test locally** (optional):
+   ```bash
+   # Install act if needed
+   curl https://gitea.com/actions/setup-act/releases/download/v0.25.0/act-0.25.0-linux-x86_64.tar.gz | tar xz
+
+   # Run locally (requires builder image to be available)
+   ./act push --file .gitea/workflows/build-and-test.yml
+   ```
+
+### Customizing the Workflow
+
+#### Modify Build Triggers
+Edit `.gitea/workflows/build-and-test.yml` to change when builds run:
+
+```yaml
+on:
+  push:
+    branches:
+      - master
+      - develop  # Add more branches
+    paths:
+      - 'src/**'  # Only run if src/ changes
+      - 'src-tauri/**'  # Only run if Rust code changes
+```
+
+#### Add Notifications
+Add Slack, Discord, or email notifications on build completion:
+
+```yaml
+- name: Notify on success
+  if: success()
+  run: |
+    curl -X POST https://slack-webhook-url...
+```
+
+#### Customize APK Upload
+Modify artifact retention or add to cloud storage:
+
+```yaml
+- name: Upload APK to S3
+  uses: actions/s3-sync@v1
+  with:
+    aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY }}
+    aws_secret_access_key: ${{ secrets.AWS_SECRET_KEY }}
+    aws_bucket: my-apk-bucket
+    source_dir: src-tauri/gen/android/app/build/outputs/apk/
+```
+
+## Environment Setup in CI
+
+### Secret Variables
+To use secrets in the workflow, set them in Gitea:
+
+1. Go to Repository Settings → Secrets
+2. Add secrets like:
+   - `AWS_ACCESS_KEY` for S3 uploads
+   - `SLACK_WEBHOOK_URL` for notifications
+   - `GITHUB_TOKEN` for releases (pre-configured)
+
+## Troubleshooting
+
+### Out of Memory During Build
+Android builds are memory-intensive. If you get OOM errors:
+
+```bash
+# Limit memory in docker-compose
+services:
+  android-build:
+    deploy:
+      resources:
+        limits:
+          memory: 6G
+```
+
+Or increase Docker's memory allocation in Docker Desktop settings.
+
+### Android SDK Download Timeout
+If downloads timeout, increase timeout or download manually:
+
+```bash
+# In container, with longer timeout
+timeout 600 sdkmanager --sdk_root=$ANDROID_HOME ...
+```
+
+### Rust Compilation Errors
+Make sure Rust is updated:
+
+```bash
+rustup update
+rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
+```
+
+### Cache Issues
+Clear Docker cache and rebuild:
+
+```bash
+docker-compose down -v  # Remove volumes
+docker system prune      # Clean up dangling images
+docker-compose up --build
+```
+
+## Performance Tips
+
+1. **Cache Reuse**: Both Docker and Gitea Act cache dependencies across runs
+2. **Parallel Steps**: The workflow runs frontend and Rust tests in series; consider parallelizing for faster CI
+3. **Incremental Builds**: Rust and Node caches persist between runs
+4. **Docker Buildkit**: Enable for faster builds:
+   ```bash
+   DOCKER_BUILDKIT=1 docker build .
+   ```
+
+## Security Considerations
+
+- Dockerfile uses `ubuntu:24.04` base image from official Docker Hub
+- NDK is downloaded from official Google servers (verified via HTTPS)
+- No credentials are stored in the Dockerfile
+- Use Gitea Secrets for sensitive values (API keys, tokens, etc.)
+- Lock dependency versions in `Cargo.toml` and `package.json`
+
+## Next Steps
+
+1. Test locally with `docker-compose up`
+2. Push to your Gitea repository
+3. Monitor workflow runs in the Actions tab
+4. Configure secrets in repository settings for production builds
+5. Set up artifact retention policies (currently 30 days)
+
+## References
+
+- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
+- [Docker Multi-stage Builds](https://docs.docker.com/build/building/multi-stage/)
+- [Android Build Tools](https://developer.android.com/studio/command-line)
+- [Tauri Android Guide](https://tauri.app/v1/guides/building/android)

docs/defect-windows.md

@@ -0,0 +1,150 @@
+# Defect windows — which bugs were present when
+
+For each fixed defect, the releases it was actually present in. Companion to
+[CHANGELOG.md](../CHANGELOG.md), which says what changed; this says how long each
+fault had been shipping before it did.
+
+**"Present since"** is the first *release* containing the defective code, not the
+first release where a user could hit it — those differ, sometimes by months, and
+the gap is called out where it matters. **"How dated"** records the evidence, so a
+row can be re-checked or disputed:
+
+| Method | Meaning |
+|--------|---------|
+| `pickaxe` | `git log -S<token>` on the defective token — the commit that introduced the exact string, then the earliest tag containing it. Strongest evidence. |
+| `feature` | The defect is inseparable from a feature that landed whole (bad rung in a new algorithm, missing caller in new plumbing), dated to that feature's release. |
+| `absence` | The fix *adds* something that was never there. Dated to when the surrounding code was built, since there is no introducing commit to find. Weakest — treat as "no later than". |
+
+## Present since the first release
+
+Nine defects date to the initial proof of concept (v0.0.1, 2026-06-23) and shipped
+for between two weeks and seven weeks short of two months before anyone hit them.
+That is the dominant pattern here: not regressions, but original assumptions that
+went unexercised until a later feature leaned on them.
+
+| Defect | Present since | Fixed in | Shipped broken for | How dated |
+|---|---|---|---|---|
+| `AudioStreamIndex=0` pinned the video stream as the audio track (DR-140) | v0.0.1 | **v0.4.6** | ~7 weeks | pickaxe |
+| Download URL spelled `videoBitrate`, which Jellyfin does not bind (DR-123) | v0.0.1 | **v0.5.1** | ~7 weeks | pickaxe |
+| `pause_download` / `resume_download` were no-ops (DR-168) | v0.0.1 | **v0.5.3** | ~7.5 weeks | pickaxe |
+| `.part` sidecar named by `with_extension`, so no cleanup path matched it (DR-169) | v0.0.1 | **v0.5.3** | ~7.5 weeks | pickaxe |
+| `Range` sent on every retry regardless of the response (DR-170) | v0.0.1 | **v0.5.3** | ~7.5 weeks | pickaxe |
+| `/Items/Latest` requested with the default `GroupItems=false` | v0.0.1 | **v0.5.1** | ~7 weeks | pickaxe |
+| `SubtitleStreamIndex` omitted from PlaybackInfo, letting the server burn in (DR-176) | v0.0.1 | **v0.5.5** | ~8 weeks | pickaxe |
+| No `PlaySessionId`, and one hardcoded `DeviceId`, on every stream URL (DR-177) | v0.0.1 | **v0.5.5** | ~8 weeks | pickaxe |
+| `download_item` never recorded `media_type`; NULL read as `'audio'` (DR-135) | v0.0.1 | **v0.4.6** | ~7 weeks | pickaxe |
+| `download_album` read its track list from the local cache (DR-173) | v0.0.1 | **v0.5.5** | ~8 weeks | pickaxe |
+| Device profile carried no `MaxAudioChannels` (DR-141) | v0.0.1 | **v0.4.6** | ~7 weeks | absence |
+| Streaming ceiling fixed at 20 Mbps with no way to lower it (UR-074) | v0.0.1 | **v0.5.3** (as a feature) | ~7.5 weeks | pickaxe |
+
+### Why they took so long to surface
+
+Four of these were **latent until a later feature exercised them**, which is why
+the fix lands so far from the cause:
+
+- The `videoBitrate` casing was harmless while every download was `original`. It
+  became visible only once a quality picker existed to select against — and then
+  produced no error, just a full-size file, because Jellyfin discards an unbound
+  query key silently.
+- The unconditional `Range` header was inert for the same reason: `original` is
+  the one rung served with a `Content-Length` and real byte-range support. It
+  started corrupting files in **v0.5.1**, the moment the casing fix made
+  transcoded downloads actually transcode. So the *code* dates to v0.0.1 and the
+  *corruption* to v0.5.1 — a one-release window for the visible symptom.
+- The missing `PlaySessionId` only bites when a stream is re-opened for the same
+  item. Nothing re-opened one until quality switching, transcoded seek and
+  audio-track switching existed.
+- The omitted `SubtitleStreamIndex` only bites on sources whose own default
+  subtitle track is image-based, since that is what forces the server from
+  sidecar to burn-in.
+
+Two were **masked by soft failure**: the asset protocol being disabled (DR-134)
+was hidden by the thumbnail cache falling back to the server copy whenever the
+server was reachable, and `AudioStreamIndex=0` was hidden by servers that
+silently correct an out-of-range index — which is exactly why it was reported as
+"*some* videos have no audio" rather than as a bug in the client.
+
+## Introduced by a feature, fixed later
+
+| Defect | Present since | Fixed in | How dated |
+|---|---|---|---|
+| Native-path resume position never applied (both layers assumed the other seeked) | v0.0.9/v0.0.10 | **v0.5.1** | feature (`PlayerAdapter` contract) |
+| `get_downloaded_items` matched "this library exists" rather than constraining the item to it (DR-167) | v0.0.17 | **v0.5.3** | feature (browsable downloaded library) |
+| `SCOPE_ITEM_TYPES` — the frontend/backend boundary leak (DR-063) | v0.0.17 | **v0.2.1** | pickaxe |
+| `check:boundary` anchored to the query site, blind to a named const (DR-094) | v0.0.17 | **v0.2.1** | feature (tripwire landed with the leak it missed) |
+| Coverage gate divided by hardcoded denominators, reporting 158% (DR-093) | v0.0.1 | **v0.2.1** | pickaxe |
+| Tap deferral raced the WebView's synthesized click (DR-092 → DR-098) | v0.1.5 | **v0.2.7** | feature (the deferral itself) |
+| Transport for webview media decided from `el.paused` in the DOM (DR-097) | v0.0.9/v0.0.10 | **v0.2.7** | feature (`Html5PlayerAdapter`) |
+| `pick_current_episode` rung 3 returned the first *gap*, not the furthest watched | v0.3.0 | **v0.5.1** | feature |
+| `mirror_user_data` mirrored `is_favorite` alone and returned early (DR-155) | v0.4.0 | **v0.5.1** | pickaxe |
+| Stop-report path never fed the sync queue that existed for it (DR-154) | v0.4.6 | **v0.5.1** | feature (queue + drain landed with no producer) |
+| Background-audio base applied in two display-only places (DR-159) | v0.2.9 | **v0.5.3** | pickaxe |
+| Positions reported as 0 before the first tick, and always 0 for webview media (DR-178/179/180) | v0.5.3 | **v0.5.5** | feature (DR-159's tick boundary) |
+
+Three of these are worth separating out, because the defect is not a mistake in
+the code so much as **plumbing that was built and never connected**:
+
+- `repository_get_next_up_episodes` accepted a `series_id` from the day it was
+  written, and no caller passed one until v0.3.0.
+- The sync queue and its drain were built, tested and running in v0.4.6 with
+  neither of its two would-be producers ever called.
+- Both halves of the watched-state backend existed with no caller before v0.5.3.
+
+An automated check cannot see any of these — the code is present, tested and
+reachable in principle. Only tracing a requirement to a *call site* catches it.
+
+## Short windows (one release or less)
+
+| Defect | Present since | Fixed in | Note |
+|---|---|---|---|
+| `experimentalNativeVideo` defaulted on, shipping audio with a blank screen (DR-161 → DR-172) | v0.5.3 | **v0.5.4** | One release. The decode path was fine; the compositing step never ran. |
+| Webview-shaped audio profile insufficient — server ignores a profile's audio codec (DR-149) | v0.4.7 | **v0.4.8** | The v0.4.7 fix for DR-148 was necessary and not sufficient. |
+| Android `versionCode` floor went stale (`minor*100` yielding less than the 5002 already in the field) | v0.5.0 | **v0.5.3** | Caught before a broken APK shipped; no released build was un-installable. |
+| Subtitle sidecar work reverted by a commit assembled from a stale tree | v0.5.5 | **v0.5.5** | Never released broken — both commits are in v0.5.5. |
+
+## Fixed twice / never actually broken
+
+- **Autoplay time reset (v0.0.2).** Two commit objects carry this identical
+  change: `dcf08f30` (merged via Gitea PR #3, tagged v0.0.2) and `fa7cb6e9` (the
+  local original). Both have the same parent `674c8e5c` and the same diff. A merge
+  chain pulled `fa7cb6e9` and its follow-up `1e599627` into master's history
+  during v0.5.5, so `git log v0.5.4..v0.5.5` lists an autoplay fix that changed no
+  file in that release — `nextEpisodeService.ts` is byte-identical across the tag
+  boundary. The fix shipped in **v0.0.2** and has not regressed.
+
+  This is the one case where reading the changelog off `git log` subjects would
+  have produced a false entry, and it is a good argument for the project's
+  practice of deriving release notes from TRACES rather than commit subjects.
+
+## Recurring shapes
+
+Four causes account for most of the table:
+
+1. **An omitted parameter is not a neutral default.** `SubtitleStreamIndex`,
+   `AudioStreamIndex`, `GroupItems` and `MaxAudioChannels` all had a server-side
+   default that was actively wrong, and in three of the four the server's choice
+   was more expensive than the one intended — burn-in forcing a full re-encode
+   being the extreme case.
+2. **Silent binding failures.** `videoBitRate` produced no error, no warning and a
+   plausible-looking file. So did an unbound `Range`, and so did the coverage gate
+   dividing by a stale denominator.
+3. **Two layers each assuming the other acts.** Native resume (adapter recorded
+   the position, backend never seeked), end-of-playback dispatch (two paths, one
+   unreachable), and the surface/attach split in v0.5.0's native video.
+4. **A guard keyed on state that moves.** The tap deferral keyed suppression on a
+   timer handle the callback had already cleared; the HTML5 toggle keyed
+   play-vs-pause on `el.paused`, which flips while buffering.
+
+## Reproducing this
+
+The pickaxe rows can be re-derived directly:
+
+```bash
+git log --oneline --reverse -S'<defective token>' -- src-tauri/src   # introducing commit
+git tag --contains <sha> | sort -V | head -1                          # first release with it
+```
+
+Blaming the lines a fix removed (`git blame` at the fix's parent) is faster to run
+across many commits but was **not** used for the rows above: it reliably lands on
+whichever commit last touched the adjacent lines, which is usually not the commit
+that introduced the defect. It was used only to shortlist candidates.

docs/release-checklist.md

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

docs/requirements.md

@@ -0,0 +1,813 @@
+# 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 | Done (Linux only) |
+| 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 | Not implemented (blocked — see DR-034) |
+| UR-032 | Gapless playback for seamless album listening | Medium | Done (Linux only) |
+| UR-033 | Volume normalization to prevent volume jumps between tracks | Low | Done (Linux only) |
+| UR-034 | Rich home screen with hero banners, carousels, and personalized sections | High | Done |
+| UR-035 | View cast/crew (actors, directors) on movie/show detail pages | High | Done |
+| UR-036 | Navigate to actor/person page showing their filmography | Medium | Done |
+| UR-037 | Visually appealing video library with poster grids and metadata | High | Done |
+| UR-038 | Movie/show detail page with backdrop, ratings, and rich metadata | High | Done |
+| UR-039 | Navigate between main sections via bottom navigation bar | High | Done |
+| UR-040 | Keep a video's audio playing when the app is backgrounded or the screen is locked, stopping video decode until the app returns to the foreground (per-player toggle; Android) | Medium | Done (pending device verification) |
+| UR-041 | Continue watching *locally-playing video* in a floating picture-in-picture window when leaving the app (Android) — PiP applies to video only, never to audio playback, library/menu browsing, or remote/cast sessions | Medium | Done |
+| UR-042 | Authenticate to a server and manage the session lifecycle (connect, log in, Quick Connect, background session verification, re-authenticate, log out) | High | Done |
+| UR-043 | Automatically detect server reachability and switch between online and offline operation without user intervention | High | Done |
+| UR-044 | Pin downloaded media so it is protected from automatic cache eviction | Low | Done |
+| UR-045 | Predictively pre-cache likely-next media (queue lookahead and album affinity) within a storage budget | Low | Done |
+| UR-046 | Group multiple remote players into a synchronized playback group (LMS SyncGroups) | Low | Done |
+| UR-047 | Manage multiple Jellyfin servers (add, list, remove) and switch the active server/account | Medium | Planned (backend store done; switcher UI pending) |
+| UR-048 | See the next episodes of a series directly below the episode/series being viewed, above cast and similar-shows content, so continuing a show is the shortest path (see [ux-flows.md §5B](ux-flows.md)) | High | Done |
+| UR-049 | Search is scoped by where it was started — inside a library it searches that library, from Home/library-root/search-tab it searches everything — with the scope shown as filter chips under the search bar that preselect from context and can be changed without retyping (see [ux-flows.md §6.1](ux-flows.md)) | High | Implemented |
+| UR-050 | Reorder search result groups (Songs, Albums, Artists, Movies, TV Shows) by drag and drop in settings, so the media a user cares about most appears first (see [ux-flows.md §6.3](ux-flows.md)) | Medium | Implemented |
+| UR-051 | Browse library pages in a consistent layout where card shape signals media type (square music, poster video, thumbnail episode), ordinal content stays listed, and the grid/list preference persists across pages (see [ux-flows.md §5A](ux-flows.md)) | Medium | Partial (implemented; toggle not reachable from settings) |
+| UR-052 | While offline, library pages show only media available on the device by default, with an opt-in toggle that additionally reveals the cached server catalog as greyed-out entries which can be queued for download on the next reconnect | High | Done |
+| UR-053 | Restrict media downloads to unmetered networks via a "WiFi Only" setting: when enabled, queued downloads are held while the device is on cellular or a metered connection (including metered WiFi hotspots) and resume automatically once an unmetered network is available | Medium | Done (pending device verification) |
+| UR-054 | Reach account actions (Settings, Downloads, Display preferences, Sign out) from every authenticated screen via a single account menu anchored to the user's name, identical on desktop and mobile (see [ux-flows.md §1.2](ux-flows.md)) | High | Done |
+| UR-055 | Browse downloaded media as an offline-scoped library — reusing the same library grids, cards, and detail pages as online browsing, showing only libraries/containers with downloaded content — with the transfer-progress list demoted to a secondary "Transfers" view (see [ux-flows.md §7.2](ux-flows.md)) | High | Done |
+| UR-056 | See how much disk each downloaded item/album/series consumes, in familiar rounded units shown on the card and detail page, with a device total on the Downloaded surface and a reclaim amount stated at the point of removal (see [ux-flows.md §7.3.1](ux-flows.md)) | Medium | Done |
+| UR-057 | Settings apply the instant a control is changed — no "Save" button and no save/dirty state — so leaving the page never loses a change; sliders show a live readout while dragging but persist on release (see [ux-flows.md §8.1](ux-flows.md)) | Medium | Done |
+| UR-058 | On the home screen, a tap on a media card opens the item (movie/episode detail page, or the series Episode Focus View for episodes) rather than starting playback; a long-press starts "play now" after a confirm; an episode detail/focus page links back to its parent series and season (see [ux-flows.md §5B.5](ux-flows.md) and [§5B.1](ux-flows.md)) | Medium | Done |
+| UR-059 | Skipping to the next episode records the episode left behind as **fully watched** rather than saving a mid-episode resume point — skipping means "done with this one", not "stopped here" — and Continue Watching hides episodes the viewer has already moved past (a partial position behind that series' next-up episode), so the row only ever offers genuinely unfinished media | Medium | Done |
+| UR-060 | Search results are ordered by how well they match: a name that *starts* with the query outranks one matching mid-word (typing "parks" finds "Parks and Recreation" before "Sparks of Love"), and at equal match quality a container outranks its contents (a series before its episodes). Results are grouped into distinct categories — TV Shows, Episodes, Movies, Songs, Albums, Artists and People — so a show never competes with its own episodes for the same slot, and searching an actor's name reaches their bio | High | Done |
+| UR-061 | Double tapping the video skips within it — right half jumps **forward 30 seconds**, left half jumps **back 10 seconds** — with an on-screen indicator naming the amount. A double tap leaves the play state unchanged — playing jumps and keeps playing, paused jumps and stays paused — because the second tap re-toggles what the first tap toggled (see DR-098); the skip lands relative to the position the player actually reports, and repeated double taps accumulate rather than all skipping from the same spot | Medium | Done |
+| UR-062 | Opening a TV series lands the viewer **where they are in it**, not at season 1: the series page scrolls the current season into view and highlights the current episode, and the hero button opens that episode (labelled `Resume S2E4` / `Play S1E1`). "Current" means the episode in progress, else the server's Next Up for that series, else the first unwatched episode, else the first — resolved by the backend so it also works offline. A season is **never a page of its own**: every route that names a season lands on the series with that season in view, so the episodes of all seasons are always one continuous scrollable list | High | Done |
+| UR-063 | Each video library is **one page**, not three. Browsing (hero, Continue Watching, Next Up, Recently Added, genre rows), the full title grid, and the genre browser are tabs of `/library/tv` and `/library/movies` rather than separate routes with inconsistent names (`/library/tv/shows` vs `/library/movies/all`, `/library/shows/genres` vs `/library/movies/genres`). The old routes redirect so existing links keep working | Medium | Done |
+| UR-064 | Watch history can be **erased**, per series and per season, from the series page. Clearing marks every episode inside unwatched and clears resume positions, so the show returns to "never watched" and reopens on its premiere. It asks for confirmation first (it cannot be undone) and requires a connection to the server, since history cleared only locally would be undone by the next sync | Medium | Done |
+| UR-065 | Search answers from a **locally indexed copy of the library**, so results appear as fast as the device can query rather than at the speed of a round trip to the server, and the same results are found with the server unreachable. A background job keeps the index current — refreshing on a schedule rather than only at app start, dropping media removed from the server, and covering everything the result groups can show (including artists and people). The server is still queried in the background so media added since the last index still turns up, merged in without reordering what is already on screen | High | Implemented |
+| UR-066 | The app's own chrome stays clear of the device's system chrome. On Android the bottom navigation sits above the navigation/gesture bar instead of underneath it, the header clears the status bar, and full-screen video and audio playback keep their controls inside the usable screen — clear of the gesture bar and, in landscape, of the display notch. This must hold across navigation modes (gesture and 3-button) and rotation, not only on the handsets it happened to be tested on | High | Done |
+| UR-067 | Favourited media can be **found again**. A Favourites page lists everything favourited across all libraries, scoped by tabs (All / Movies / Shows / Music); the home screen carries favourite rows for movies, shows and music, hidden when a category is empty; and each library page can be filtered to favourites in place. Without this the like button writes to a store nothing reads | Medium | Done |
+| UR-068 | Anything the app shows can be favourited where it is shown — from a movie, series, episode, album, artist or playlist page, and from any card in a grid or carousel — not only from the player while the item happens to be playing | Medium | Done |
+| UR-069 | Favourite state agrees with the server in both directions. An item favourited in another Jellyfin client shows as favourited here without being touched, and an item favourited here while the server is unreachable reaches the server once it returns — without the user going back to the screen where they marked it | Medium | Done |
+| UR-070 | Playback quality is the viewer's choice: the player offers the bitrates the server can produce for what is playing, and changing one resumes at the same point with the same audio and subtitle tracks. Because the chosen rendition can change at any moment, nothing that streams for playback is treated as a stored copy unless it happens to be byte-identical to the real file | Medium | Proposed |
+| UR-071 | Media the viewer is watching can be **kept**, by a whole-file download that runs in the background independently of playback and at its own quality, so it is unaffected by bitrate changes. Where the streamed bytes already are that file (direct play), they are kept rather than fetched twice. A completed download is then played from disk rather than streamed again | Medium | Proposed |
+| UR-073 | Watched state is something the viewer can **set**, not only something playback records. Any episode, season, series or movie can be marked watched — or unwatched again — from where it is shown, without sitting through it or erasing its history wholesale. Marking a season or series covers the episodes inside it, and works with the server unreachable | Medium | Done |
+| UR-072 | Each page opens where a page should open. Moving to a new screen starts at the top of it, and going Back returns the viewer to the place they left — their position in a long library grid or home screen, not the top of it. A page never inherits the scroll position of the page before it | Medium | Done |
+| UR-075 | Artwork is shown at the shape it was made in. Where a screen presents a set of things side by side — the libraries on the library page and on home — they are laid out as a mosaic: rows of a common height in which each tile is as wide as its own picture, rather than a grid that crops every cover to one box. Favourites are reachable per category from that same mosaic, beside the library they belong to, not only as one undifferentiated list | Medium | Done |
+| UR-074 | Video streaming can be held to a **bandwidth budget the viewer sets**, rather than spent at whatever rate the server would otherwise send. A ceiling chosen once — from the source's own bitrate down to a rung that still plays on a poor connection — governs every video the app opens, live TV included, and survives a restart, so a metered connection is not quietly drained by the next thing played. A single video can be moved to a different ceiling from the player, resuming where it was, without disturbing that default | Medium | 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 | Done (Linux/MPV; Android parity pending) |
+| IR-022 | Jellyfin API client for person/cast data | API | UR-035, UR-036 | Done |
+| IR-023 | Database schema for person/cast caching | Storage | UR-035, UR-036 | Done |
+| IR-024 | Jellyfin API client for home screen data (featured, continue watching) | API | UR-034 | Done |
+| IR-025 | Android background-audio handoff: WebView `<video>` → native ExoPlayer foreground service on background/lock, and back on foreground (audio continues, video decode stops) | Platform | UR-040 | Done (pending device verification) |
+| IR-026 | Android picture-in-picture: auto-enter on user-leave-hint via `enterPictureInPictureMode`, **only while a local video surface is actively rendering** (never for audio-only playback, menu/library browsing, or remote/cast sessions — enforced by the native `canEnterPip` guard, re-checked at leave time); aspect-ratio sizing; a play/pause RemoteAction that **reflects live player play/pause state** (updated whenever playback state changes, not only on button press); WebView hide/restore on mode change | Platform | UR-041 | Done |
+| IR-027 | Jellyfin `/System/Info/Public` reachability probe used as an offline→online recovery detector | API | UR-043 | Done |
+| IR-028 | Jellyfin/LMS SyncGroups API client (list, create, join, unsync, dissolve sync groups) | API | UR-046 | Done |
+| IR-029 | Android `ConnectivityManager`/`NetworkCapabilities` transport probe with a `NetworkCallback` change subscription, surfaced to the frontend via the `AndroidNetworkType` JS bridge and the `jellytau-network-changed` WebView event (requires `ACCESS_NETWORK_STATE`) | Platform | UR-053 | Done (pending device verification) |
+| IR-030 | Scheduled full-catalog crawl of every library (`Recursive=true`, paged) feeding the local index, driven by a Rust background task and the `ConnectivityMonitor` reconnect signal rather than by the frontend | Storage | UR-065 | Implemented |
+| IR-031 | Android `WindowInsets` bridge: an `OnApplyWindowInsetsListener` on the decor view reports `systemBars() | displayCutout()` in CSS pixels, pushed into the WebView as `jt-inset` CSS custom properties plus a `jellytau-insets-changed` event, and pullable via the `AndroidInsets` JS bridge | Platform | UR-066 | Done (pending device verification) |
+| IR-032 | Whole-file background download of the item being played, reusing the existing resumable download worker and the Range-capable `/Videos/{id}/stream.mp4` endpoint; plus per-platform read-through caching hooks (ExoPlayer `CacheDataSource`, mpv `stream-record`) for direct-play sessions only | Storage | UR-071 | Proposed |
+
+### 2.2 Jellyfin API Requirements
+
+API endpoints and data contracts required for Jellyfin integration.
+
+| ID | Requirement | Endpoint Category | Traces To | Status |
+|----|-------------|-------------------|-----------|--------|
+| JA-001 | Server connection and discovery | System | UR-009 | Done |
+| JA-002 | User authentication (username/password) | Users | UR-009, UR-012 | Done |
+| JA-003 | Get user library views | UserViews | UR-007 | Done |
+| JA-004 | Get library items (paginated) | Items | UR-007 | Done |
+| JA-005 | Get item details and metadata | Items | UR-007 | Done |
+| JA-006 | Search across libraries | Items | UR-008 | Done |
+| JA-007 | Get playback info and stream URL | MediaInfo | UR-003, UR-004 | Done |
+| JA-008 | Get available subtitles for item | MediaInfo | UR-020 | Done |
+| JA-009 | Get available audio tracks for item | MediaInfo | UR-021 | Done |
+| JA-010 | Report playback start | Sessions | UR-025 | Done |
+| JA-011 | Report playback progress (periodic) | Sessions | UR-025 | Done |
+| JA-012 | Report playback stopped | Sessions | UR-025 | Done |
+| JA-013 | Get resume position for item | UserData | UR-019 | Done |
+| JA-014 | Get "Next Up" items | Shows | UR-023 | Done |
+| JA-015 | Get "Continue Watching" items | Items | UR-023 | Done |
+| JA-016 | Get recently added items | Items | UR-024 | Done |
+| JA-017 | Mark item as favorite | UserData | UR-017 | Done |
+| JA-018 | Remove item from favorites | UserData | UR-017 | Done |
+| JA-019 | Get/create/update playlists | Playlists | UR-014 | Done |
+| JA-020 | Add/remove items from playlist | Playlists | UR-014 | Done |
+| JA-021 | Get active sessions list | Sessions | UR-010 | Done |
+| JA-022 | Send playback commands to remote session (play/pause/stop) | Sessions | UR-010 | Done |
+| JA-023 | Send seek command to remote session | Sessions | UR-010 | Done |
+| JA-024 | Send next/previous track commands to remote session | Sessions | UR-010 | Done |
+| JA-025 | Play specific item on remote session | Sessions | UR-010 | Done |
+| JA-026 | Send volume/mute commands to remote session | Sessions | UR-010 | Done |
+| JA-027 | Get transcoding options | MediaInfo | UR-022 | Planned |
+| JA-028 | Get image/artwork URLs | Images | UR-007 | Done |
+| JA-029 | Get cast/crew for item (actors, directors) | Items | UR-035 | Done |
+| JA-030 | Get person details and filmography | Persons | UR-036 | Done |
+| JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
+| JA-032 | Get audio-only stream URL for a video item (selected audio-stream index) | MediaInfo | UR-040 | Done |
+| JA-033 | Query favourite items (`Filters=IsFavorite`, recursive, scoped by item type) | Items | UR-067 | Done |
+| JA-034 | Read `UserData` (favourite, played, resume position) from item responses | UserData | UR-069 | Done |
+| JA-035 | Mark item played (`POST /Users/{userId}/PlayedItems/{itemId}`) | UserData | UR-025 | Done |
+
+### 2.3 Development Requirements
+
+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 | Done |
+| 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 | Not implemented (blocked on MPV: single-stream audio chain; `acrossfade` needs 2 inputs — see docs/specs/playback-backend-unification.md) |
+| DR-035 | Gapless playback between sequential tracks | Player | UR-032 | Done (Linux only) |
+| DR-036 | Volume normalization with preset levels (Loud/Normal/Quiet) | Player | UR-033 | Done (Linux only) |
+| DR-037 | Remote session browser and control UI | UI | UR-010 | Done |
+| DR-038 | Home screen with hero banner carousel (featured/continue watching) | UI | UR-034 | Done |
+| DR-039 | Home screen horizontal carousels (recently added, recommendations) | UI | UR-034, UR-024 | Done |
+| DR-040 | Cast/crew section on movie/show detail pages | UI | UR-035 | Done |
+| DR-041 | Person/actor detail page with filmography grid | UI | UR-036 | Done |
+| DR-042 | Video library grid with poster cards, year, and rating badges | UI | UR-037 | Done |
+| DR-043 | Movie/show detail page with backdrop hero, synopsis, and metadata | UI | UR-038 | Done |
+| DR-044 | Horizontal scrolling actor/cast row with profile images | UI | UR-035 | Done |
+| DR-045 | Bottom navigation bar with Home, Library, Search buttons | UI | UR-039 | Done |
+| DR-046 | Dedicated search page with input and results | UI | UR-039 | Done |
+| DR-047 | Next episode auto-play popup with configurable countdown and episode limit | Player | UR-023 | Done |
+| DR-048 | Video settings (auto-play toggle, countdown duration, episode limit) | Settings | UR-023, UR-026 | Done |
+| DR-051 | Background-audio toggle button in the video player controls (suppresses auto-PiP while enabled) | UI | UR-040 | Done (pending device verification) |
+| DR-052 | Background-audio handoff state machine: on background/lock tear down the WebView `<video>`/HLS decode and start native audio-only playback at the current position; on foreground return position and resume `<video>`; exactly one audio source active at every transition (no dual audio) | Player | UR-040 | Done (pending device verification) |
+| DR-053 | PictureInPictureManager: `canEnterPip` gate (local video surface actively rendering — false for audio, browsing, and remote/cast), aspect-ratio clamp, a RemoteAction play/pause receiver whose icon reflects live player state (refreshed on every playback-state change while in PiP, not only on button press), WebView hide/restore, surface re-fit on exit; plus the `AndroidPictureInPicture` JS bridge and the PiP button (shown only when PiP is supported) in the video player | UI | UR-041 | Done |
+| DR-054 | Auth manager and session lifecycle: connect-to-server, login, Quick Connect verification poll (start/stop), session get/set, background session verifier, re-authenticate, logout | Auth | UR-042 | Done |
+| DR-055 | ConnectivityMonitor deriving reachability from real repository traffic, with online/offline state, mark-reachable/unreachable reporting, and a probe-based recovery poller active only while offline | Connectivity | UR-043 | Done |
+| DR-056 | Download pinning (pin/unpin/is-pinned) that excludes an item from smart-cache eviction | Storage | UR-044 | Done |
+| DR-057 | Smart cache manager: album-affinity tracking, queue-lookahead pre-cache, storage-limit enforcement, config, stats, and recommendations | Storage | UR-045 | Done |
+| DR-058 | Remote sync-group control (LMS SyncGroups): list, create, unsync a player, dissolve a group | Player | UR-046 | Done |
+| DR-059 | Playback-mode transfer state machine: get/set current mode, transferring guard, transfer-to-remote / transfer-to-local, remote session status | Player | UR-010 | Done |
+| DR-060 | Multi-server store and active-account selection: save/get/delete server, save/get user, set/get active user (per-server), active-session resolution | Storage | UR-047 | Partial (store done; server-switcher UI pending) |
+| DR-061 | Episode Focus View: episode hero followed *immediately* by the "More Episodes" strip — a forward-biased window (~3 before / ~6 after) around the current episode, spanning season boundaries in series order, with the current episode present and badged, per-card resume progress and watched state, and click-to-swap focus (no playback) | UI | UR-048 | Done |
+| DR-062 | Detail-page section ordering: continuation content precedes discovery content — Episode Focus View renders hero → episode strip → cast → similar; Series renders hero → seasons/episodes → cast → similar | UI | UR-048 | Done |
+| DR-063 | Search scope taxonomy owned by Rust: `SearchScope` (All / Music / Movies / TV) crosses IPC as an opaque enum and `SearchScope::item_types()` expands it to Jellyfin item types, resolved once in `repository_search` before the cache and server paths diverge so online and offline filter identically; `All` expands to *no* filter rather than the union of the other scopes (which would drop People and folders). The frontend maps the originating route to a scope (`resolveSearchScope`, presentation) and never names an item type for search | Backend | UR-049 | Implemented |
+| DR-064 | Scope chip row rendered under the search bar on both the search page and the in-library header search: preselected from context, horizontally scrollable, re-runs the search preserving the query on change | UI | UR-049 | Implemented |
+| DR-065 | Thread `SearchOptions.includeItemTypes` through `library.search()` so the global/header search honours scope (backend online + offline paths already support it) | UI | UR-049 | Implemented |
+| DR-066 | Persisted search result group order with a drag-and-drop settings list, keyboard-accessible reordering, a shipped default (see DR-091 for the current group set and order), and empty-group omission | Settings | UR-050 | Implemented |
+| DR-067 | `SearchResults` renders groups in the user-configured order rather than hardcoded markup order, without altering intra-group ranking | UI | UR-050 | Implemented |
+| DR-068 | Library card shape by media type: 1:1 square for music (circular mask for artists), 2:3 poster for movies/series/seasons, 16:9 for episodes and collection folders | UI | UR-051 | Done |
+| DR-069 | Responsive library grid (2/3/4/5/6 columns across base→xl) with two-line truncated card text and artwork-overlay progress/watched state | UI | UR-051 | Done |
+| DR-070 | Global persisted grid/list view preference honoured by browse pages, suppressed for ordinal content (album tracks, season episodes) | UI | UR-051, UR-029 | Partial (persisted store + page-header toggle; no settings entry) |
+| DR-075 | Shared `AccountMenu` component: identity header (user + server), Downloads / Settings / Display entries, divider, Sign out last; anchored to the username/avatar trigger and identical on desktop and mobile | UI | UR-054 | Done |
+| DR-076 | App shell exposes the header (and therefore the account menu) on every authenticated non-immersive route, including `/`, `/search`, and `/downloads`; only `/player/*` and `/login` remain chrome-free | UI | UR-054 | Done |
+| DR-077 | Display section in Settings binding the existing persisted grid/list `viewMode` store, giving the preference a discoverable home | Settings | UR-054, UR-029 | Done |
+| DR-078 | Catalog-visibility gate spanning the "Show all server media" toggle → `set_show_server_catalog` → `INCLUDE_CATALOG_BROWSE` → the synced-catalog UNION branch of offline `get_items`. Visibility resolves to `serverReachable \|\| showServerCatalog`, so offline with the toggle off lists downloaded/local media only | Storage | UR-052, UR-002 | Done |
+| DR-079 | `isConnected` derives from backend-reported server reachability alone; `navigator.onLine` is advisory and may only trigger a recheck, never force or clear the offline state (a reachable LAN server while the browser reports offline, and an unreachable server on a live link, must both resolve correctly) | Connectivity | UR-052, UR-043 | Done |
+| DR-080 | With the catalog-browse gate off, an empty offline `get_items` result is authoritative "no downloads here" and must be returned as-is; the hybrid repository must not treat it as a cache miss and fall through to the server | Storage | UR-052, UR-013 | Done |
+| DR-074 | WiFi-only download gate: `NetworkState`/`NetworkType` transport model reported from the platform via `set_network_state`, checked in `pump_download_queue` before starting any pending row (cellular/metered/unknown fail closed, WiFi and Ethernet require `NOT_METERED`); blocked rows stay `pending` and re-pump on network change, with a `waitingForNetwork` event driving the "Waiting for WiFi" notice. Also wires the previously inert Smart Caching / Queue Pre-caching / WiFi Only settings toggles to `CacheConfig` | Downloads | UR-053 | Done (pending device verification) |
+| DR-081 | `/downloads` split into a default **Downloaded** browse view and a secondary **Transfers** activity view, with a view switch and a Transfers badge shown only while transfers are active | UI | UR-055 | Done |
+| DR-082 | Offline-scoped browse entry point in the repository client: browse downloaded content only (offline repository `get_items`/`get_libraries` — downloaded items plus their containers) independent of server reachability, without merging server catalog | Storage | UR-055 | Done |
+| DR-083 | Downloaded browse reuses library grids, cards, and detail pages via the offline-scoped source; omits libraries/containers with no downloaded content; badges partially- vs fully-downloaded containers; play uses the local file; remove available at item/album/season/series level | UI | UR-055 | Done |
+| DR-084 | Transfers view renders only in-flight rows (downloading/queued/paused/failed/waiting-for-WiFi) with Pause/Resume/Cancel/Retry; completed transfers leave the view and appear in Downloaded | UI | UR-055 | Done |
+| DR-085 | Per-item on-disk size: stat downloaded files, aggregate to album/season/series subtotals and a device total, format in consistent rounded human units; surface size on cards and detail pages, the device total on the Downloaded surface, and a reclaim figure in the remove confirmation | Downloads | UR-056 | Done |
+| DR-086 | Settings page persists each control on change via per-group writers (`playerSetAudioSettings` / `playerSetVideoSettings` / `updateCacheConfig`) rather than a batch Save action; slider controls persist on `change` (pointer release) not each `input` tick; no Save button, `saving`, or `saveMessage` state | Settings | UR-057 | Done |
+| DR-087 | `MediaCard` gains an `onLongPress` prop with pointer-based long-press detection (~500 ms hold, cancelled on >10 px move so carousel scroll is unaffected, trailing click suppressed); home carousels wire tap→detail/focus routing and long-press→confirm→player; episode taps route to `/library/<seriesId>?episode=<id>`; the bare-episode detail page links to its parent series/season | UI | UR-058 | Done |
+| DR-088 | Skip-to-next-episode marks the outgoing episode played (`markAsPlayed`) instead of reporting a stop position, and arms a one-shot suppression consumed by the player's stop handler so `VideoPlayer`'s post-navigation unmount stop report cannot overwrite the 100% progress with the partial position | UI | UR-059 | Done |
+| DR-089 | Continue Watching suppresses resume entries superseded by Next Up: an in-progress episode whose series has a next-up entry strictly later in series order (season, then episode) is dropped from the Home and TV rows; movies, series without a next-up entry, and items with unknown/mixed episode ordering are always kept | UI | UR-059 | Done |
+| DR-090 | Relevance ranking in Rust (`domain/search_rank.rs`): results sort by match position (prefix → word-start → mid-word substring → no name match) then by media kind (containers before their contents), stably so the backend's own relevance breaks ties. Applied in `repository_search` to both the instant cache result and the merged cache+server union, so the list does not reshuffle when server results land | Backend | UR-060 | Done |
+| DR-091 | Search result groups split TV into separate Shows and Episodes groups and add a People group (default order: Shows → Episodes → Movies → Songs → Albums → Artists → People); a stored `tvShows` order from before the split expands in place to shows+episodes so an upgrading user keeps their arrangement | UI | UR-060 | Done |
+| DR-092 | Video tap gestures resolve in `tapGestures.ts` (pure, unit-tested) rather than inline in `VideoPlayer.svelte`: `registerTap` classifies each tap and the component acts on it immediately — `togglePlayPause` for a first tap, or `seek` (+30 s right / −10 s left) plus a re-toggle for a second tap inside `DOUBLE_TAP_WINDOW_MS` (300 ms). A consumed pair resets the state, and a swipe forgets the tap. The deferral this originally used was removed in DR-098, which also covers suppressing the compatibility `click` the browser synthesizes after a touch tap. `resolveSeekTarget` converts the delta to the absolute position the facade requires, clamped per DR-095 and chained off a still-in-flight `pendingSeekTarget` so back-to-back skips accumulate instead of all resolving against a not-yet-updated position | UI | UR-061 | Done |
+| DR-094 | Frontend boundary tripwire (`scripts/check-frontend-boundary.sh`) detects Jellyfin item-type array literals **anywhere** in `src/` rather than only inline at an `includeItemTypes:` query site, so a category→type mapping cannot evade the check by being assigned to a named const (the evasion that let the `scoped-search` leak pass CI); requires two adjacent type literals so single-type presentation and `item.type ===` inspection stay legal, and caps the allowlist to force taxonomy into Rust instead of accumulating exceptions | Tooling | - | Done |
+| DR-098 | Video tap gestures act **immediately** — no deferral, no timer, and only first/second taps exist. A first tap toggles play/pause; a second tap inside `DOUBLE_TAP_WINDOW_MS` seeks *and* toggles again, so the two toggles cancel and a double tap preserves the play state (playing → jump and keep playing; paused → jump and stay paused). This replaces a design that deferred the first tap behind a 300 ms timer so a second tap could cancel it: the timer cleared its own handle *before* invoking the toggle, which reopened the `tapTimeout !== null` guard in `handleVideoClick` meant to suppress the compatibility `click` Android's WebView synthesizes after a touch — the late click then toggled a second time, producing a pause/unpause loop (long-press was unaffected, which is what identified the tap path). Click suppression no longer depends on the timer: `handleVideoClick` ignores `detail === 0` *and* any click within `TOUCH_CLICK_SUPPRESS_MS` of a touch tap. A swipe undoes the touchstart toggle exactly once (latched on `swipeGestureActive`) so brightness swipes never change play state. Click suppression is shared by **every** click target layered over the video via `isSynthesizedTouchClick`, not just the `<video>`: pausing renders a full-screen play-overlay button, so the synthesized click lands on *that* and an unguarded handler there resumed immediately — pausing appeared impossible while unpausing worked, because unpausing removes the overlay | UI | UR-061 | Done |
+| DR-099 | The video seek bar is usable by touch. Two Android-only defects made dragging or tapping it move the thumb without moving playback. (a) *Gesture hijack*: the container-level gesture layer skips `touchstart` on a control (DR-098) but kept handling `touchmove`, so a seek-bar drag was measured against the **previous** gesture's start point — a huge bogus vertical delta that read as a brightness swipe, dimmed the screen to the 0.3 floor, and fired a spurious play/pause "correction" mid-drag. A gesture is now latched at `touchstart` (`playerGestureActive`) and `touchmove` ignores anything not latched, since re-checking the move target cannot recover a start point that was never recorded. (b) *Commit signal*: the seek was committed **only** from `change`, which Android's WebView does not reliably fire for a touch interaction on a range input — the thumb moved to the tapped position and no seek ever ran. `touchend`/`mouseup` now commit as well; `input` arms a one-shot latch so whichever release signal arrives first commits and the other is a no-op. `seekRelative` shares the same `commitSeek` entry point instead of fabricating a synthetic `change` event | UI | UR-005, UR-061 | Done |
+| DR-097 | Transport authority (play/pause/toggle) lives in Rust for **webview-rendered** media, not just native. The controller tracks the state the HTML5 element reports (`html5_playing`, fed by `report_html5_state`, which now *stores* rather than only re-emitting); `play`/`pause`/`toggle_playback` consult it and drive the element by emitting a `ControlCommand` that `playerEvents.handleControlCommand` executes against the active adapter. A `stopped`/`idle` report clears it so the native backend (MPV/ExoPlayer) regains authority for music. The frontend facade no longer short-circuits transport into the adapter: `adapter.toggle()` previously decided play-vs-pause by reading `el.paused` off the DOM, a value that flips transiently while an element buffers or settles a seek — so two intents ~150 ms apart read *different* values, performed *opposing* actions, and self-sustained a play/pause loop needing no further input (observed on Android with a fully-buffered `readyState=4 networkState=1` element). Same "backend decides, adapter executes the primitive" split as `player_seek_video` | Player | UR-005 | Done |
+| DR-096 | `Html5PlayerAdapter.play()` is resilient to stall recovery: an in-flight attempt is memoised so concurrent callers (UI plus hls.js gap-controller recovery) share one `element.play()` instead of stacking calls, and an `AbortError` ("play() request was interrupted by a call to pause()") is logged at debug rather than pushed to `host.onError`. The browser raises it whenever a pending play promise is superseded by a pause/seek/source change, which hls.js does routinely while nudging past a stall — reporting it surfaced a player error roughly once per second for the whole stall and left the UI stuck showing paused | Player | UR-005 | Done |
+| DR-095 | Seek targets clamp strictly *inside* the media (`clampSeekTarget`, `END_SEEK_MARGIN_SECONDS` = 6 s ≈ one HLS segment) instead of to the exact `duration`. Landing on the duration makes hls.js request the segment whose start time lies past the end of the media (e.g. a 6330.324 s item → segment 1055 starting at 6336.33 s), which Jellyfin never produces; the fetch times out and hls.js' gap-controller stalls at the last buffered position, presenting as "unpausing or skipping bounces straight back to paused". Applied on both seek paths — the relative-skip `resolveSeekTarget` and the seek-bar drag, whose range input `max` is the duration itself — and floored at 0 so media shorter than the margin still seeks to the start | UI | UR-061 | Done |
+| DR-100 | Leaving a video and re-entering it renders the **video** player, never the audio one. Both halves of the `/player/[id]` decision are pure and unit-tested in `playerSurface.ts`. (a) `shouldReuseActivePlayback` excludes video: the "already playing, just show the UI" shortcut (added for expanding the audio mini player) returns *before* a stream URL is fetched, which is fine for audio — the backend owns the stream and the route only mirrors it — but leaves `<VideoPlayer>` with nothing to render. Closing a webview-rendered video deliberately emits no `stopped` state (that would break the autoplay handoff, see DR-047), so the Rust controller still reports that movie/episode as its loaded media and re-entering the same item hit the shortcut. (b) `resolvePlayerSurface` maps video-without-a-stream-URL to `pending` (spinner) instead of falling through to `<AudioPlayer>`, so no future path can put video content in the audio surface. Video now always takes the full load path, which fetches the stream URL and applies the stored resume position | UI | UR-005 | Done |
+| DR-101 | "Where is this viewer in this series" is resolved in **Rust**, not the frontend. `repository_get_series_episodes` performs the season fan-out (`get_items(series_id)` → seasons → `get_items(season_id)`, plus the flat-series fallback for shows whose children are episodes rather than season folders) and returns them in series order — season index ascending, episode index ascending, specials (season 0) after every numbered season. `repository_get_series_current_episode` layers the pure policy `pick_current_episode` over that list: an **in-progress** episode wins (earliest in series order on a tie — it is literally where playback stopped, and Next Up would skip past it), then the server's **Next Up** for that series, then the **first unwatched** episode, then the first. The third rung is the offline path, not dead code: `OfflineRepository::get_next_up_episodes` returns an empty vec, so without it the feature would be online-only. A failing Next Up or resume lookup degrades to empty rather than failing the call. `repository_get_next_up_episodes` had accepted a `series_id` since it was written and **no caller had ever passed one** | Repository | UR-062 | Done |
+| DR-102 | The series detail page anchors on that answer. It calls `repositoryGetSeriesEpisodes` once instead of fanning out over seasons in TypeScript (the fan-out *and* its flat-series fallback were domain knowledge in the presentation layer), groups the returned episodes under season headers by `parentIndexNumber`, and passes the resolved current episode to `SeasonSection` → `EpisodeRow`, which renders a highlight ring and scrolls itself into view. The hero button navigates to `/library/<seriesId>?episode=<currentId>` — the Episode Focus View, where an explicit Play/Resume commits — per ux-flows §5B.5: Play on a *container* is navigation, Play on a *leaf* commits. It previously resolved `$libraryItems[0]`, the first **season** by `SortName`, and navigated to `/player/<seasonId>`, which the player route bounced back to `/library/<seasonId>` — so Play on a series played nothing and landed on the season-1 page | UI | UR-062 | Done |
+| DR-103 | A season is not a destination. `/library/<seasonId>` redirects to `/library/<seriesId>#season-<indexNumber>`, the anchor `SeasonSection` renders, so a season link scrolls the series' continuous episode list rather than opening a page. Every inbound link follows: the episode breadcrumb, `handleItemClick case "season"`, the TV landing page's `case "Season"`, and `DownloadedBrowse`. A season carrying no `seriesId` (deep link into a stale cache) still renders the generic view so the user is never stranded. This removes a surface that had no route of its own — it fell through the detail page's `kind` chain to the generic "Contents" poster grid, contradicting ux-flows §5A.2 (episodes must be a row list), and clicking an episode there opened a bare Episode page, which §5B.1 forbids | UI | UR-062 | Done |
+| DR-104 | The "More Episodes" strip spans the **whole series** in series order, per ux-flows §5B.2's cross-season continuity rule: at the end of a season the window runs on into the next season's first episodes instead of dead-ending. `adjacentEpisodes` previously filtered the pool to `parentIndexNumber === current.parentIndexNumber` and sorted by `indexNumber` alone, so the window could never leave the current season — and, when episodes of several seasons did reach it, sorting by episode number alone interleaved them. Cards crossing a season boundary are labelled `SxEy` rather than a bare episode number so the jump is legible | UI | UR-062 | Done |
+| DR-105 | Video library routes collapse to one per library. `/library/tv` and `/library/movies` render browse / all-titles / genres as in-page tabs driven by `?view=`, omitted for the default `browse` (the convention `searchRouteUrl` already uses for the `all` scope); `resolveLibraryView` is pure and unit-tested. The four legacy routes become redirect-only `+page.ts` loads rather than deletions, because `GenreTags` links to them and users have them in history; `resolveSearchScope` keeps its `/library/shows` branch for the same reason. The "Browse" tile grid at the bottom of both landing pages is removed — it was a second navigation affordance to the same destinations the carousels' "Show all" links already reach | UI | UR-063 | Done |
+| DR-106 | Erasing watch history goes through the repository, not the local cache: `clear_watch_history(item_id)` maps to Jellyfin's `DELETE /Users/{userId}/PlayedItems/{itemId}`, which clears the played flag *and* zeroes the resume position, and which the server applies recursively to a folder — so one call handles a whole series or season. `OfflineRepository` returns `RepoError::Offline` rather than clearing locally, because history diverged only on the device would be silently undone by the next sync; the button disables itself while the server is unreachable. `ClearHistoryButton` is shared by the series hero and each `SeasonSection` header, confirms before acting (there is no undo), and reloads the page on success so the recomputed current episode — the premiere, for a fully cleared series — is what the viewer sees | Repository | UR-064 | Done |
+| DR-107 | Seasons on the series page are collapsible, and **only the current season is expanded** on load — the one holding the episode DR-101 resolved. A show with ten seasons otherwise renders every episode of every season at once, burying the one episode the viewer came for under hundreds of rows. Expansion state is per season and pure (`initialExpandedSeasons` in `seriesNavigation.ts`): the current season, or the first season when there is no current episode, so a never-watched show still opens on season 1 rather than fully collapsed. A `?episode=` deep link expands that episode's season too. Toggling is local and not persisted — it is a reading position, not a preference | UI | UR-062 | Done |
+| DR-108 | The instant (cache) leg of `repository_search` searches the **synced catalog**, not just downloads. `OfflineRepository::search` replaces its `downloaded_items` CTE with the `available_items` CTE `get_items` already uses — the same downloads branches plus a `synced_at IS NOT NULL` branch gated on the same `include_catalog_browse()` flag — so search and browse cannot diverge on what is visible. Online (flag true) search reads the whole index and answers before any HTTP request completes; offline with "Show all server media" off (flag false) it stays downloads-only, unchanged. Requires no frontend change, since the flag is already set correctly for all three states. The `include_item_types` filter is switched from string interpolation to bound parameters, as `SearchOptions` is settable from the frontend and not only from `SearchScope` | Backend | UR-065 | Implemented |
+| DR-109 | Index freshness is a Rust-owned policy, not a frontend startup call. A tokio task ticks every 30 min and runs a full pass when a repository is active, the server is reachable, and `last_catalog_sync` (already persisted to `app_settings`, previously read only for a UI hint) is older than `CATALOG_INDEX_TTL` (6 h); the `ConnectivityMonitor` reconnect signal re-evaluates the same condition immediately. An `AtomicBool` prevents concurrent passes, replacing `offlineCatalog.ts`'s `syncInProgress` — the frontend trigger is removed rather than left alongside, since two triggers with one guard each is how double-crawls happen. `RepositoryManager` gains an active-handle slot so the task has something to run against. Progress is emitted as the kebab-case `catalog-index-event` | Backend | UR-065 | Implemented |
+| DR-110 | Index hygiene. `save_to_cache` switches from `INSERT OR REPLACE INTO items` to `ON CONFLICT(id) DO UPDATE`: REPLACE fires no `AFTER DELETE` trigger unless `recursive_triggers` is on (it is not — only `foreign_keys` and `journal_mode` are set), so `items_ad` never ran, and because `items.id` is a `TEXT PRIMARY KEY` each replacement also took a fresh rowid and appended a second `items_fts` entry — a duplicate index per sync, invisible in results but permanently degrading `MATCH`. The upsert preserves the rowid `items_fts` keys on and fires `items_au`; migration `021_rebuild_items_fts` clears orphans on existing installs. Separately, a post-crawl sweep deletes synced-but-not-downloaded rows a successful library crawl did not return, so media removed from the server stops being searchable; it skips items with completed downloads and skips any library whose crawl errored, because `items.parent_id` is `ON DELETE CASCADE` and a partial crawl would cascade away a whole series | Storage | UR-065 | Implemented |
+| DR-111 | The index covers what the result groups render: `CATALOG_ITEM_TYPES` gains `MusicArtist` and `Playlist`, and migration `022_people_fts` adds a `people_fts` virtual table over the existing `people` table (which had no FTS, and is populated incidentally by item-detail fetches) with the same trigger pattern as `items_fts`. `OfflineRepository::search` UNIONs `people_fts` matches in as `Person` items when the resolved scope admits them — i.e. `SearchScope::All`, which expands to no filter (DR-063). Without this, the Artists and People groups UR-060 mandates can only ever be filled by the server leg | Storage | UR-065, UR-060 | Implemented |
+| DR-112 | Safe-area insets come from **native**, not from `env()` alone. `env(safe-area-inset-*)` is 0px without `viewport-fit=cover` (missing from `app.html`, so every safe-area rule in the app was already a no-op), and even with it Android WebView maps only the *display cutout* — never the status bar or navigation bar. Since `enableEdgeToEdge()` plus `targetSdk 36` make edge-to-edge unconditional, the WebView always spans the system bars, so CSS could not learn about them by any route. `WindowInsetsBridge` reads the real insets and publishes `jt-inset` custom properties; `app.css` folds them with `env()` via `max()` into `--safe-*`, which is the only thing components may pad from. Ownership is exactly one element per edge: the app shell takes top/left/right, and BottomUi takes bottom wherever it renders (`shellReservesBottomInset` hands it back to the shell on routes with no bottom UI) so the padding sits inside BottomUi's surface box and the colour extends behind the gesture bar. The full-screen players inset their control layers only, leaving video and artwork edge-to-edge. The theme's `fitsSystemWindows=true` — which claimed the opposite and was overridden at runtime and ignored at this target SDK — is removed | UI | UR-066 | Done |
+| DR-113 | `MediaItem.user_data` is populated from the server instead of being hardcoded `None`. `JellyfinItem` gains a `UserData` field (`#[serde(alias = "UserData")]` → the existing `UserData` type) and `to_media_item` maps it, so every list and detail response carries favourite/played/resume state. `UserData` is named explicitly in the `Fields=` list rather than relying on Jellyfin's default. Without this no card or detail page can render a favourite it did not itself set, and the mini player's per-track `storageGetPlaybackProgress` fetch is the only way to colour one heart | Repository | UR-069 | Done |
+| DR-114 | Server favourite state is mirrored into the local `user_data` table by `OfflineRepository::save_to_cache` — the single choke point every cached server result passes through — so offline browsing and the offline Favourites page see the same favourites as the server. The upsert carries `pending_sync = 0` and is guarded by `WHERE user_data.pending_sync = 0`, which is the conflict rule: a toggle made offline is never overwritten by a stale server value before it has been pushed | Storage | UR-069 | Done |
+| DR-115 | Cross-library favourites query: a `get_favorites(scope, options)` repository method plus the `repository_get_favorites` command. Online issues `Filters=IsFavorite&Recursive=true` with `IncludeItemTypes` expanded from `SearchScope::item_types()` in Rust (the frontend sends the opaque scope, never a type list — DR-063); offline reads `items ⨝ user_data (is_favorite = 1)` under the same `include_catalog_browse()` gate as browsing; hybrid races cache against server like `get_items` — saving server results through to the cache on a miss, so the favourites page does not re-query the server every visit and the DR-114 mirror is filled on a fresh install — and applies the DR-080 rule that an empty offline result is authoritative when the gate is off. The command falls back to this read when nothing is cached, rather than painting an empty state it will correct a round trip later. A separate method rather than `get_items` because favourites span libraries and `get_items` is `ParentId`-shaped | Repository | UR-067 | Done |
+| DR-116 | `GetItemsOptions.favorites_only` filters an existing library listing in place — online by appending `Filters=IsFavorite`, offline by joining `user_data` into the existing `available_items` CTE so the downloads-only gate still applies. This is what backs the per-library favourites toggle, and composes with the genre and item-type filters already there | Repository | UR-067 | Done |
+| DR-117 | The Favourites page (`/library/favorites`) renders favourites across libraries with All / Movies / Shows / Music scope tabs, reusing `LibraryViewTabs` + `LibraryGrid` + `MediaCard` so card shape still follows the media (§5A.1) and a mixed All tab reads as posters, squares and thumbnails side by side. Each tab sends a `SearchScope` value and nothing else. Reached from the library overview and from "See all" on the home rows | UI | UR-067 | Done |
+| DR-118 | Home carries favourite rows for movies, shows and music, loaded via `repository_get_favorites` per scope and rendered below Recently Added. A row with no items does not render at all, so a fresh install shows no empty favourite rows | UI | UR-067 | Done |
+| DR-119 | `FavoriteButton` is mounted wherever a whole item is shown — movie/series/episode detail heroes, album/artist/playlist headers, and as a `MediaCard` artwork overlay — and a `favorites` store holds in-session optimistic state so un-hearting on one surface updates every other without a refetch. Resolution order is `store override ?? item.userData?.isFavorite ?? false`. On a card the heart is its own button and stops propagation, so hearting never also opens, plays, or triggers the §5B.5 long-press; it is suppressed on server-only (greyed) cards | UI | UR-068 | Done |
+| DR-120 | Favourite toggles made while offline reach the server. A Rust drain, triggered by the `ConnectivityMonitor` offline→online transition, pushes every `user_data` row with `pending_sync = 1` and clears the flag on success, leaving failures pending for the next transition. It lives in Rust rather than the frontend because a frontend drain dies with the component that started it. Both the drain and the hybrid background refresh emit the kebab-case `favorites-changed` event (`{ itemIds }`) so open views update — without it a favourite marked on another client appears only on the *second* visit to a page, since the cache-first read returns local rows and the server refresh is invisible to the frontend. Supersedes the unused `syncService.queueFavorite`, which is deleted rather than left as a second queue | Backend | UR-069 | Done |
+| DR-121 | Player quality selector: Rust reports the bitrates available for the current media source and owns the quality→transcode-parameter mapping (the one `get_video_download_url` already holds — playback calls into it rather than restating it, or the two tables drift). Changing quality re-negotiates the stream URL and resumes at the current position with audio/subtitle selection preserved. On Linux, video re-negotiates *within* HLS: returning `stream.mp4` is the documented cause of transcoded playback never starting. The frontend renders the list and remembers the choice; it does not decide what the choice resolves to | UI | UR-070 | Proposed |
+| DR-122 | The playback path is ephemeral. Streamed bytes are never persisted unless DR-124 rules them keepable, and any in-flight capture is abandoned — partial file deleted, never promoted — the moment the viewer changes quality, because a capture spanning a rendition change is a splice of two encodings rather than a playable file | Playback | UR-070 | Proposed |
+| DR-123 | The download path is independent of playback: a whole-file fetch through the existing download manager at one canonical quality (default `original`, the direct static copy) over the Range-capable `/Videos/{id}/stream.mp4`, unaffected by bitrate changes and completing into an ordinary `downloads` row so offline browsing and `refresh_queue_local_sources` pick it up unchanged. Prerequisite: downloaded video is currently never played locally — `repository_get_video_stream_url` goes straight to the online repo and the player route calls it with no local check, so a completed video download is still streamed. Without that fix nothing in this spec is observable for video | Repository | UR-071 | In Progress |
+| DR-124 | Streamed bytes are kept only where they *are* the download artifact — a direct-play session. Android uses ExoPlayer `SimpleCache`/`CacheDataSource` keyed by item **and** media-source id so renditions cannot collide, sharing the existing smart-cache storage budget rather than opening a second one over the same disk; Linux audio uses mpv `stream-record`, abandoned on seek because it is documented as intended for linear streams and seeking breaks the recording. Transcoded Linux video is **not** captured: HLS segments are not a file, and assembling one needs ffmpeg, which is not a dependency and which CI may not install at job time — DR-123 covers that case instead | Playback | UR-071 | Proposed |
+| DR-125 | A capture is promoted to a completed `downloads` row only when it covers the whole resource; partials stay evictable cache. A new `downloads.source_rendition` column records the negotiated quality/container/codec (`NULL` for the existing paths, which are always `original`) so a captured transcode and a real download are distinguishable rows and an "upgrade to original" remains possible. A quality change never touches a file that already exists — not a permanent download, and not a completed temporary one, both of which stay valid copies of the rendition they hold. It invalidates only an **in-flight** capture or background download of cached media, which is abandoned and restarted at the newly chosen quality, because a capture spanning a rendition change is a splice of two encodings rather than a playable file | Storage | UR-071 | Proposed |
+| DR-126 | Cache eviction only reclaims the *temporary* tier. `evict_lru_async` selected every completed download ordered by `completed_at ASC` with no `download_source` filter, so hitting the 10 GB storage limit deleted the **oldest** download — typically a film saved deliberately for offline — to make room for a newly precached track. It now evicts only `COALESCE(download_source, 'user') = 'auto'` rows; `COALESCE` rather than a bare equality because rows predating migration 012 can be NULL and unknown provenance must be treated as the user's, never as disposable. Freeing less than requested is the correct outcome when only user downloads remain — the caller reports "unable to free enough space" instead of silently deleting them | Storage | UR-071 | Done |
+| DR-127 | A cache entry *is* a download with a shorter life: same `downloads` row and same file handling, distinguished by `download_source = 'auto'` plus an expiry, so there is one storage model rather than a cache and a download library that can disagree. Temporary rows are reclaimed on whichever comes first — the life limit elapsing, or eviction under space pressure (DR-126). Permanent (`'user'`) rows have no expiry. A temporary row can be promoted to permanent by the user choosing to keep it, which only clears the expiry and flips the source; the bytes never move | Storage | UR-071 | Done |
+| DR-128 | Audio-only playback of *downloaded* media reads the local file rather than fetching an audio-only stream. No transcode is involved or wanted: the Linux backend already runs MPV with `video: no`, so handing it the downloaded video file decodes the audio track and ignores the video, and ExoPlayer disables its video renderer equivalently. Transcoding to a separate audio artifact would cost CPU and battery, need an encoder the project does not ship, and produce a second file to keep in step — for no gain over simply not decoding the video | Playback | UR-071 | Done |
+| DR-129 | A stream that stops delivering is recovered, not treated as terminal. Two failure shapes, because the streams differ. (a) *Phantom end* — the background audio-only handoff uses a progressive mp3 transcode over plain HTTP, chunked and therefore length-less, so a dropped connection reaches the player as end-of-input and ExoPlayer reports `STATE_ENDED` indistinguishably from the real end. The item's runtime is the only thing that can tell them apart: an end reported more than a tolerance short of it (comparing the *absolute* position — handoff base plus the player's relative position) is a truncation. Left unhandled, playback parked in `STATE_ENDED` and the next play intent from the lockscreen, notification or a Bluetooth reconnect seeks an ended player to position 0 — the user-visible "the episode randomly restarted". (b) *Recoverable error* — music (`/Audio/{id}/stream?Static=true`) and video (`/Videos/{id}/master.m3u8`) declare their length, so the player detects the truncation itself and raises an error; the frontend's handler stopped playback outright, turning a hiccup into silence. Both resume the current item **in place** (never via `play_item`, which would replace the queue with a single item and lose the album), the error path after a per-attempt backoff. Seekable streams are re-prepared at the URL they already have and seeked; the length-less transcode, which cannot be seeked, has `StartTimeTicks` rewritten into its existing URL so the user's audio-track selection survives and recovery needs no network round-trip. Only `Remote` sources qualify — a local file cannot fail from the network. A shared budget of consecutive attempts at the same position, refilled whenever playback progresses, stops an unreachable server from looping | Playback | UR-040, UR-004 | Done |
+| DR-130 | A backend's position and duration must survive the end of the file they describe. MPV exposes `time-pos`/`duration` as properties of the *loaded* file, so at EOF it unloads and both stop resolving — the accessors reported `0.0`/unknown at exactly the moment end-of-file handling asks where playback reached, and any position-versus-runtime check would have read every natural end as a truncation. The poll thread records the last reading and the accessors fall back to it. Linux resilience is layered on the same principle that the stream, not the player, is what failed: MPV is configured with ffmpeg reconnection (`stream-lavf-o`, `network-timeout`) so ordinary blips never surface, and `EndFile(ERROR)` — previously a bare log, which left playback halted while the UI still showed "playing" — is emitted as a *recoverable* error. Because MpvBackend is constructed before `PlayerController` exists, it cannot decide in-process like the Android JNI callback: the frontend echoes the error into `player_recover_stream`, which keeps the decision in Rust (the same shape as `PlaybackEnded` → `player_on_playback_ended`). Android reports errors it has already declined as *unrecoverable*, so the echo never asks twice | Playback | UR-004, UR-040 | Done |
+| DR-131 | The offline mutation queue is drained. `sync_queue` had producers and no consumer: `PlaybackReporter::queue_for_sync` writes a row for every start/stop/mark-played that cannot reach the server, `sync_mark_processing`/`_completed`/`_failed` were registered commands with no callers, and no Rust task processed the table — so queued watch positions never reached Jellyfin and the offline banner's count only ever grew. A drain hangs off the same `connectivity:reconnected` transition as DR-120 (in Rust, because a drain started by a component dies with it) and replays rows oldest-first, so a stale start cannot move the server's resume position backwards after a later stop. `update_progress` replays as *stopped at N* rather than as progress — replaying a mid-playback report hours later would claim the item is still playing — and payloads are read in both dialects that exist in users' databases (`position_ticks` from Rust, camelCase `positionMs` from the frontend helper). A failed row stays queued for the next reconnect; after `MAX_SYNC_ATTEMPTS` it is `abandoned` and stops counting, because a row nothing can ever push is what turns the queue into a counter that only grows. An *unreachable* server is not counted as an attempt at all — the row goes back to `pending` untouched — so opening the app offline a few times cannot abandon good rows; only a server that answers and refuses spends the budget. The drain also runs once at startup, because a queue built in a previous session would otherwise sit untouched for a whole run whenever the server was reachable the entire time and no offline→online transition ever fired. Requires `MediaRepository::mark_played` (JA-035) — the previous stand-in reported a stop at `i64::MAX` | Backend | UR-025, UR-002 | Done |
+| DR-132 | The pending-sync count is answerable. The offline banner's badge read "N pending sync(s)" and led nowhere, so it was taken for pending *transfers* and looked for on the Downloads page — which lists the `downloads` table and structurally cannot show `sync_queue` rows. The badge becomes a button opening the queue it counts: each row's operation, the item's title (resolved by a `LEFT JOIN items` in `sync_get_pending`, not a per-row frontend fetch), when it was queued, and the error of anything failing, plus a "Sync now" that runs the DR-131 drain on demand. The same list is a Settings section, because a row that keeps failing is still queued when the server is reachable and no banner is on screen. The drain emits `sync-queue-changed` so the badge updates on reconnect instead of lagging by up to one 10s poll | UI | UR-025 | Done |
+| DR-133 | A downloaded file has exactly one on-disk path, and the row that names it is authoritative. `downloads.file_path` starts relative to the storage root, but the worker rewrites it to the absolute path it actually wrote when the transfer completes — so a *completed* row is already rooted. The video player's offline branch rooted it a second time, handing the asset protocol `/data/user/0/app//data/user/0/app/videos/x.mp4`; the webview reported `MEDIA_ERR_SRC_NOT_SUPPORTED` with `NETWORK_NO_SOURCE`, so every downloaded video failed to play while audio — which resolves the same column through Rust's `resolve_local_media_path`, without re-rooting — played fine. The join is absolute-aware (POSIX, Windows drive letters and UNC) so rows written before completion still resolve | Playback | UR-071 | Done |
+| DR-134 | The webview can actually fetch the local files it is handed. `convertFileSrc` rewrites a path to `http://asset.localhost/…` unconditionally, but Tauri only answers that origin when the `protocol-asset` cargo feature is compiled in *and* `app.security.assetProtocol.enable` is set — neither was, so every such URL reached a protocol with no handler and the webview reported `NETWORK_NO_SOURCE`. This silently defeated both offline video (`<video src>`) and the cached-thumbnail path in `imageCache`, which fails soft to the server copy and so hid the breakage whenever the server was reachable. The scope is `$APPDATA/**` — the storage root under which the database, `downloads/` and the thumbnail cache all live — rather than an unrestricted grant, so the webview can read the app's own media and nothing else | Security | UR-071 | Done |
+| DR-140 | An audio track is pinned only when the user picked one. Jellyfin's `MediaStream.Index` is global across every stream in a media source, so index 0 is the *video* stream on virtually all files — yet `AudioStreamIndex=0` was sent as "the first audio track" on the HLS transcode URL, the background audio-only handoff URL, the direct-play fallback URL, and the `PlaybackInfo` negotiation body. A server that honours the request literally then transcodes the video stream into the audio slot and the result plays as a picture with no sound; only servers that silently correct the index hid the bug, which is why it presented as "some videos have no audio". The parameter is now omitted whenever no track has been chosen, so the server resolves the source's `DefaultAudioStreamIndex`; an explicit selection from `player_switch_audio_track` is still carried through unchanged. On the `static=true` direct-play URL it is dropped outright — the original file is served untouched, so the parameter could only mislead | Playback | UR-004, UR-040 | Done |
+| DR-147 | One search input per screen, and the URL is the search's single source of truth. The header bar rendered only under `/library/**` and merely *navigated* to `/search` (DR-063), so a desktop search handed the user to a screen whose input was a different element — the header box cleared itself and vanished, and the page's own box took over mid-word. That page then re-derived its input from `?q=` against `library.searchQuery` on every store write, so the next keystroke re-ran the effect and snapped the text back to the query the header had sent (and a scope chip back to the URL's scope); entering from the bottom-nav Search tab skipped it only because the effect early-returned on an empty query. The bar now renders on `/search` too (`showHeaderSearch`) and is the sole md+ input — the page's own input is `md:hidden` — and on that route it republishes the query into the URL with `replaceState`, so a whole session of typing costs one history entry. The page *consumes* that URL once per distinct value (`seedFromSearchUrl` against a non-reactive `applied` marker) instead of continuously reconciling it, and the scope chips publish through the same URL so the bar and the chips cannot disagree. Landing on `/search` with a seeded query focuses the bar and puts the caret at the end, because the box the user was typing in belonged to the unmounted route | UI | UR-049, UR-054 | Done |
+| DR-142 | An episode has exactly **one** surface, and it is complete. Two divergent renderings existed: `EpisodeFocusView` (reached from Continue Watching, the series episode list, the TV landing page and Downloads — i.e. every real entry point) offered only Play and Favourite, while the bare `/library/<episodeId>` page nobody routed to carried the download button, the series/season breadcrumbs and the cast section. Opening an episode the normal way therefore silently lost the ability to download it. The Focus View is now the single surface and carries the full §5B.2 composition — hero action row `Play / Download / Favourite`, series name and `SxEy` badge as links back to the series and to that season's anchor, then genres → cast → similar shows *below* the episode strip, never above it (DR-062). `/library/<episodeId>` redirects into it (`episodeRedirectTarget`, the same rule seasons follow under DR-103), and an episode with no `seriesId` renders the same component series-less rather than falling back to a second, lesser page. The focused episode is fetched in full rather than reused from the season fan-out, because that is a *list* query and carries neither cast nor genres — the sections would have rendered empty. The strip hides itself when the episode has no siblings, a card that only shows the episode you are already on being noise | UI | UR-048, UR-058 | Done |
+| DR-141 | The device profile states how many channels the audio route can actually voice. `MediaCodecList` answers "can this device *decode* 5.1", which is not the question that decides whether the user hears anything — a phone decodes an AC-3 5.1 track happily and still has two channels to play it out of. With no `MaxAudioChannels` in the profile, Jellyfin was free to direct-play the multichannel track, and the result is device dependent: a failed `AudioSink` configuration (silence) or dialogue folded into surround channels that go nowhere. media3's `AudioCapabilities.maxChannelCount` for the current route is reported over JNI alongside the codec lists, and bounds both the direct-play profile and the transcoding profiles, so the server downmixes rather than shipping channels the sink cannot take. Codecs are never removed from the profile — a device with genuine surround output keeps direct-playing it. A missing or zero reading means "route not yet established", not "no audio", and falls back to stereo, the one capability every sink has | Playback | UR-004 | Done |
+| DR-145 | Video playback starts only once the app actually holds audio focus. Video manages focus by hand (`handleAudioFocus=false`, because ExoPlayer's automatic handling is reserved for the audio path), and the request's three outcomes were all treated as success: `AUDIOFOCUS_REQUEST_DELAYED` — which `setAcceptsDelayedFocusGain(true)` explicitly invites, and which means the system is *withholding our audio* until it calls back — and an outright `REQUEST_FAILED` were logged and then followed by `playWhenReady = true`. The picture rolled with no sound, indistinguishable to the user from a broken stream. Playback is now held when focus is not granted and started from the `AUDIOFOCUS_GAIN` callback; an explicit `play()` re-requests focus rather than resuming into a stream the system is still muting, guarded by a held-focus flag so repeated plays do not leak focus requests. A `LOSS` clears the pending flag, so an unrelated later `GAIN` cannot start playback the user never asked for | Playback | UR-004 | Done |
+| DR-146 | The no-audio-track fallback picks a track the renderer can actually play. When ExoPlayer selected no audio track, the recovery forced group 0 / track 0 unconditionally — but the most likely reason nothing was selected is that this very track cannot be decoded on this device, so the override reinstated the silence it was meant to fix. It now scans the groups for the first `isTrackSupported` track and overrides to that, and clears `setTrackTypeDisabled(TRACK_TYPE_AUDIO)` because audio may equally have been off at the type level, which an override alone does not undo. When no group holds a supported track the condition is logged as an error — the server was expected to transcode — rather than leaving a silent video with no explanation in the log | Playback | UR-004 | Done |
+| DR-148 | The video direct-play profile advertises only what the **webview** can decode. The audio codec list comes from `MediaCodecList`, which describes ExoPlayer — but video does not play through ExoPlayer on either platform: Android force-renders every video in the webview `<video>` element (the interim override in `VideoPlayer.svelte`, because the native SurfaceView sits behind an opaque webview) and Linux always has. Chromium and WebKit decode a far narrower set than the platform does, and the gap is widest on devices whose vendor licenses Dolby: a phone shipping `/vendor/etc/media_codecs_dolby_audio.xml` reports `ac3,eac3`, so Jellyfin direct-played an E-AC-3 track with `static=true` and the webview built a video decoder and no audio decoder at all — full picture, no sound. The defect is triggered by *capability*, not the lack of it, which is why it reproduced on one Motorola while a Fairphone and an Honor tablet played the same file on the same build: a device without the Dolby decoder never claims the codec, so the server transcodes to AAC and it plays. `video_audio_codecs` narrows the platform list to the webview-decodable set (`aac,mp3,opus,vorbis,flac`) for the video direct-play profile *only* — the audio-only profile keeps the full list, since that playback really is the native player's and narrowing it would transcode music that plays perfectly well. A list with nothing decodable still claims `aac` rather than going out empty, because a profile that claims nothing invites the server to give up instead of transcoding. The video codec list is deliberately untouched: HEVC direct-plays through the webview correctly, so the constraint is specific to audio | Playback | UR-004 | Done |
+| DR-149 | The client decides whether its own renderer can decode the audio, rather than trusting the server's negotiation. Advertising a webview-shaped profile (DR-148) turned out to be necessary but not sufficient: Jellyfin 10.11.5 enforces a `DirectPlayProfile`'s `Container` and `VideoCodec` — excluding either returns `SupportsDirectPlay: false` with `TranscodeReasons=ContainerNotSupported` / `VideoCodecNotSupported` — but **ignores its `AudioCodec`**, offering an E-AC-3 track for direct play against a profile listing only `aac,flac,mp3,opus,vorbis`. Neither a `VideoAudio` `CodecProfile` forbidding the codec nor a `MaxAudioChannels: 2` against a 6-channel track changes the answer, so no profile the client can send fixes it and the picture plays silent. The negotiated source's audio is therefore checked locally against what the webview decodes, and an undecodable track forces the existing h264/aac HLS transcode URL regardless of the server saying direct play is fine — `direct_play` and `needs_transcoding` are corrected to match, so the frontend and the reporting path agree with the URL actually used. The track judged is the one the server would serve: the default, or the first when nothing is marked default, since a supported track further down the list is not the one that plays. A source with no audio streams, or a stream whose codec the server did not name, is left alone — forcing a transcode on a guess spends server CPU on files that already play | Playback | UR-004 | Done |
+| DR-150 | Android video renders on the native ExoPlayer surface behind a transparent WebView, behind the `experimentalNativeVideo` opt-in. Rust already reported `use_html5_element: false` on Android, but two frontend overrides discarded it — `createAdapter()` hardcoded `"html5"`, and `VideoPlayer.svelte` forced `useHtml5Element = true` and stopped the native backend `player_play_item` had just started. The flag is a **suppressor, never a promoter**: off forces HTML5 even where Rust says native, so an in-progress spike cannot ship as the default, but it can never select native where Rust reported HTML5 (Linux cannot composite behind WebKitGTK, so promoting there is a black screen). Compositing requires clearing two independent opaque layers, and clearing only one leaves audio over a black picture — the WebView widget background and window drawable from Kotlin (`AndroidVideoSurface.setTransparent`), and the page's `html`/`body` and app-shell background from CSS (`data-native-video`). Transparency is declared in `tauri.android.conf.json` rather than the base config, because a transparent window on Linux has nothing behind it, and is toggled per playback session rather than set once, because a permanently transparent window shows the launcher through the rest of the app | Playback | UR-003, UR-004 | Done (behind `experimentalNativeVideo`, default off) |
+| DR-151 | The player's video SurfaceView actually reaches the view hierarchy. `JellyTauPlayer.setActivity()` had zero callers, so `currentActivity` was always null and `autoAttachSurface()` returned at "Cannot attach surface - no Activity reference". The surface was created and handed to ExoPlayer but never added to the content view, so native video decoded to a surface that was never on screen — independent of any webview transparency. `MainActivity.onCreate` now supplies the reference, which also revives PiP on the video path: `canEnterPip()` gates on `isVideoSurfaceAttached()`, which had been permanently false | Playback | UR-003, UR-041 | Done |
+| DR-152 | Platform playback facilities are reported by Rust, not sniffed from the user agent. `webviewAudio.ts` re-derived "does this platform have a native audio backend" by matching `navigator.userAgent` against `android`/`linux` — a second copy of the `cfg!` gate the backends are compiled under, free to drift from it. `player_get_capabilities` now returns `usesWebviewAudio` and `supportsNativeVideo` from the same cfg gates, and the frontend consumes them; the settings toggle for native video is hidden entirely where the platform cannot support it | Player | UR-003, UR-005 | Done |
+| DR-153 | The git tag is the single source of truth for a release version. The version lived in four files (`package.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`) that had to be hand-edited in lockstep, and CI's release job rewrote exactly one of them — so a tagged build produced an installer named for the tag wrapped around package metadata naming the previous release, while the Linux job had no version step at all and shipped whatever was committed. `scripts/set-version.sh` writes all four from one argument and is the only thing that does; every release job calls it with the tag. The Android `versionCode` is derived in the same place as `1000 + major*10000 + minor*100 + patch`, which is monotonic in semver order and clears the 1000 floor already installed in the field — a lower code than the installed one makes Android refuse the update. A prerelease suffix is stripped before that arithmetic, which would otherwise abort the script, and a non-tag ref (CI passes `${GITHUB_REF#refs/tags/}` unconditionally) falls back to `git describe` rather than failing a branch build | Build | - | Done |
+| DR-154 | A watch position that cannot reach the server is queued, not dropped. `sync_queue` and its drain (DR-131) were built, tested and running, but the stop-report path never fed them: `HybridRepository::report_playback_stopped` is a bare pass-through to the online repository ("Playback reporting goes directly to server"), and on failure the error surfaced to a frontend `catch` whose own comment read "Server error - could queue, but for now just log". Both producers that *would* have queued it — `PlaybackReporter::queue_for_sync` in Rust and `syncService.queuePlaybackProgress` on the frontend — have no callers on the playback path, so closing a video while the server was unreachable lost the resume point outright even though `user_data.pending_sync` was dutifully set to 1 and nothing ever drains that flag for positions (unlike favourites, DR-120). The command layer now enqueues a `report_playback_stopped` row whenever the push fails, which the existing drain already knows how to parse and replay. The pending row for an item is **superseded in place** rather than appended to: progress is reported every 10s, so a server that stays down would otherwise add a row per tick, all of them obsoleted by the newest — the unbounded queue DR-131 exists to prevent. Only `pending`/`failed` rows are superseded, because an `abandoned` row has been given up on and reviving it would restore that same growing counter. Queueing is best-effort and never fails the command: the local position is already saved, so a failed *queue* write must not be reported as a lost position | Backend | UR-025, UR-002 | Done |
+| DR-155 | A watch position set on another device reaches this one. The resume check reads the local `user_data` row and nothing else, but `mirror_user_data` — the only path by which server `UserData` lands in that table — mirrored `is_favorite` alone, and returned early whenever that field was absent, which is exactly the shape of an ordinary watched episode. So `playback_position_ticks` was write-only from this device's perspective: watch 40 minutes in a browser, open JellyTau, and it resumed from whatever *this* device last saw or offered no resume at all — the same user-visible symptom as DR-150's Android bug, from an unrelated cause, which is why resume read as broadly flaky. The mirror now carries the position alongside the favourite flag under the same `pending_sync = 0` conflict rule, so a local position still waiting to be pushed is never pulled *backwards* by a server that has not yet heard where we got to; `COALESCE(excluded.x, user_data.x)` means a field the server omitted keeps its stored value rather than being nulled, and a row with neither field is still skipped rather than fabricated as zeroes. Mirroring alone was not sufficient: `get_item` — the call the player route makes — returned the cached copy on a hit and never consulted the server, so for an already-cached item the mirror never ran. It now refreshes in the background on a cache hit (`race_with_refresh`, the reusable form of what `get_items` already did inline), which is why browsing a season picked up other devices' state while opening the episode directly did not. The refreshed value lands for the next read, the cache-first race still answering immediately | Backend | UR-025, UR-002 | Done |
+| DR-156 | A page no longer inherits the previous page's scroll position. The shell keeps its scrollers alive across navigation by design — the root layout, the home page and the library layout each own a `flex-1 overflow-y-auto` box that outlives the route inside it, which is what lets `BottomUi` be a flex sibling rather than a measured overlay — but the element therefore never remounts and its `scrollTop` survives the route change. SvelteKit's own scroll restoration could not help: it saves and restores `window` scroll, and in this app the window never scrolls at all, so there was no scroll handling of any kind. The symptom was that opening an item from half-way down a library grid dropped the viewer half-way down the detail page, and returning to the grid landed at the top of it — exactly backwards. `ScrollMemory` (pure, one instance per container, keyed on path + query so a genre-filtered grid keeps its own place) records the offset a route is left at in `beforeNavigate` and decides in `afterNavigate`: `link`/`goto`/`form` reset to the top, `popstate` restores that route's saved offset, and the initial `enter` is left alone. Deciding does not consume the offset, so a route returned to more than once restores each time. Applied via the `scrollContainer` action on all three scrollers | UI | UR-072 | Done |
+| DR-160 | Picture-in-picture works on the path that actually plays video. PiP shrinks the whole *Activity*, so `canEnterPip` demanded a native ExoPlayer `SurfaceView` be attached and rendering — `isPlayingVideo() && getSurfaceView() != null && isVideoSurfaceAttached()`. But the native path sits behind `experimentalNativeVideo`, which defaulted to **off**, so in the shipping configuration video played in the WebView's `<video>` element and all three conditions were false. `enterPip` bailed with "Not entering PiP: no local video playing" every single time: the button was offered (gated only on OS capability) and could not work, however it was pressed. The manager now accepts either surface. The frontend reports the element through `AndroidPictureInPicture.setHtml5VideoState(active, width, height, playing)` — intrinsic size because the PiP window's aspect ratio came from the letterboxed surface's measured bounds, which do not exist here, and play state because `ExoPlayer.isPlaying` is false on this path and the PiP play/pause action would be frozen on "Play" mid-playback. Two behaviours invert when the WebView *is* the video: it must stay visible in PiP rather than be hidden (`hideWebView` is now gated on the native path — hiding it would leave an empty black window), and the play/pause `RemoteAction` has to reach the element, so the receiver dispatches `jellytau-pip-play`/`jellytau-pip-pause` DOM events instead of driving ExoPlayer. `jellytau-pip-entered`/`-exited` let the player strip its own chrome, since controls, title and gradients would otherwise be rendered into a window a couple of inches wide. The `<video>` is deregistered on teardown so PiP is never offered over a video that has gone | UI | UR-041 | Done (pending device verification) |
+| DR-167 | Each downloaded library shows only its own media. Cached items carry no link back to their library — `library_id` and `parent_id` are NULL on every row ([[offline-libraries-never-cached]]) — so `get_downloaded_items` matched the library branch with `EXISTS (SELECT 1 FROM libraries l WHERE l.id = ?)`, which asserts only that the requested library *exists* and never constrains the item to it. Opening any downloaded library therefore listed every downloaded top-level item on the server: films under Music, albums under TV. The sibling query that decides which libraries *appear* already carried the right rule — a `collection_type` ↔ `item_type` mapping — so the two disagreed about the same question. That mapping is now the named constant `LIBRARY_HOLDS_ITEM`, used by both, and a library of unknown collection type still keeps everything rather than being emptied by a rule that cannot classify it. The taxonomy stays in Rust, never the frontend | Downloads | UR-055 | Done |
+| DR-168 | Pause and resume actually stop and restart the bytes. `pause_download` wrote `status = 'paused'` and did nothing else, and no cancellation existed anywhere in the download stack — no token, no flag, no abort — so the streaming task ran on, kept writing, and overwrote the row with `completed`/`failed` when it finished: the row flicked to "paused" and undid itself. `resume_download` had the mirror defect, flipping the row to `pending` without calling `pump_download_queue`; the pump runs when something calls it rather than polling, so a resumed download sat untouched until an unrelated event happened to pump the queue. A per-download stop flag (`download::stop`) is the missing half — a module-level registry because the two sides never meet, the command holding Tauri state and the worker running detached in `async_runtime::spawn`. The worker reads it between chunks and on retry (so a pause is not swallowed by a 45-second backoff), flushes, and returns `Stopped`, which is deliberately **not** retryable and **not** recorded as a failure: the `.part` file is left intact because that is exactly what the resume's Range request continues from. Registering returns a *fresh* flag, or a resumed download would inherit the pause that stopped it and halt instantly. Cancel and `clear_stale_downloads` signal it too, so neither deletes a file still being written | Downloads | UR-055 | Done |
+| DR-169 | Partial files are actually reaped. The worker named its sidecar with `Path::with_extension("part")`, which *replaces* the extension — `movie.mp4` became `movie.part` — while every cleanup path deleted `"{file_path}.part"`, i.e. `movie.mp4.part`. The two never matched, so the partial file of every cancelled or failed download stayed on disk indefinitely, invisible to the disk-usage totals because no `downloads` row pointed at it. `partial_path` appends instead, is the single definition both the writer and the cleaners use, and incidentally removes a collision the old form had, where `movie.mp4` and `movie.mkv` mapped to one `movie.part` | Downloads | UR-055 | Done |
+| DR-173 | Downloading an album queues the **whole** album, and every track it queued is findable offline afterwards. Two independent gaps left an album with a handful of its tracks on the device while the button reported the album as downloaded. First, `download_album` took its track list from `items WHERE album_id = ?` — the local catalog cache. Jellyfin does not return `AlbumId` on every listing endpoint, so tracks cached by one of those endpoints sit in `items` with a NULL `album_id` and are invisible to that query; on the reporter's database three whole albums (18, 12 and 9 tracks) had it NULL on *every* track, so "download album" would have queued nothing for them, and a partially-linked album queued only the linked subset. Second, the frontend then resolved one stream URL per track from its own list and paired it with the returned row ids **by position** — a pairing with no basis, since the ids came back in the backend's `index_number` order over a different set of rows, so a row could be handed another track's URL and any track past the end of the shorter list was never started at all; on Android that loop also stopped wherever the webview was suspended. The same `album_id` is what `OfflineRepository::get_items` joins a track to its album on, so a track that did download stayed invisible under its album offline — the two halves of the same missing link. The operation now belongs to Rust end to end: `HybridRepository::get_album_tracks` asks the **server** what the album contains (cache-first `get_items` is right for browsing and wrong for deciding what to download) and errors offline so the caller falls back to the ungated local catalog, keeping the queue-while-offline flow; `queue_album_tracks` writes the album link onto every track it queues — queuing a track *is* the statement that it belongs to the album, rather than something to hope a listing endpoint recorded — and the stream URLs are resolved here through the existing reconnect resolver, now scoped to the rows just queued so one album cannot start every unrelated pending row. Nothing crosses the IPC boundary but the album id. Re-queuing a broken album heals it: the missing tracks are added and the tracks already on disk get their link. `download_series`/`download_season` still derive their episode lists from the cache the same way and want the same treatment | Downloads | UR-018, UR-055 | Done |
+| DR-170 | Downloads at a chosen bitrate are no longer corrupted by their own retries. Only the `original` preset asks for `Static=true`; every other rung requests a **transcode**, which Jellyfin serves chunked, with no `Content-Length`, and cannot byte-seek — so it ignores `Range` and answers `200` with the whole stream from the beginning rather than `206` with the requested tail. The worker sent the Range header whenever a `.part` existed and appended the body unconditionally, so each retry and each resume concatenated a fresh copy of the entire transcode onto the bytes already on disk: the file grew past its real size and would not play, which is why "downloads for different bitrates" stayed broken after the `videoBitRate` casing fix (DR-adc460f3) corrected the *request*. `resume_offset` makes the response decide — append only on a `206`, otherwise truncate and take the stream from the top — and the total size is computed from that offset rather than from a partial length the server never agreed to | Downloads | UR-071 | Done |
+| DR-172 | Native Android video is opt-in again, because as a default it shipped as **audio with no picture**. DR-161 flipped `experimentalNativeVideo` on so picture-in-picture could shrink a real video surface; on a device that produced sound and a blank screen. The decode path was never the problem — logcat showed ExoPlayer running (`Position update` ticks) and feeding a live `SurfaceView` with an active BufferQueue. The compositing was: the SurfaceView sits *behind* the WebView, and the step that clears the opaque layers above it never took effect, with `WebView transparent = false` logged and `= true` never appearing. So the video rendered correctly the whole time, behind an opaque page. This is exactly the defect the flag existed to contain — `VideoPlayer.scrubRegression.test.ts` had recorded that "the native SurfaceView has never been visible through the webview" — and enabling it by default shipped a verified decode path on top of an unverified display path. Reverting costs nothing that matters: PiP does not depend on it (DR-160 drives PiP from the WebView `<video>`), and working video outranks PiP showing a native surface. The flag stays available in Settings, now described as incomplete rather than as a performance win, and the scrub-regression mocks that were made explicit under DR-161 are kept explicit so those tests state which path they guard rather than inheriting a default that has now moved twice. Fixing the compositing is the prerequisite for trying this default again | UI | UR-003, UR-004, UR-041 | Done |
+| DR-171 | A downloaded video keeps audio the device can actually decode. `original` quality asked for `Static=true`, which hands back the source file byte-for-byte — E-AC-3/AC-3/DTS/TrueHD track included — and video is rendered on both platforms by the webview `<video>` element, which decodes none of them. Streaming already knew this: DR-149 judges the track the server would serve against `WEBVIEW_AUDIO_CODECS` and forces a transcode over Jellyfin's own direct-play offer, because 10.11.5 honours a `DirectPlayProfile`'s container and video codec but ignores its audio codec. The download path never consulted that policy, so the *same film* had sound when streamed and played as picture in silence once downloaded — and offline a download is the only source a video has, so there was no working path left to fall back to. The rule is now one rule: `served_audio_codec` picks the track the server will serve (the default, or the first when none is marked) and both callers judge it, the streaming verdict staying a bool and the download path needing the codec itself so it can say what to re-encode. Only the audio is re-encoded — `allowVideoStreamCopy=true` keeps an h264 source's picture byte-for-byte and no bitrate or resolution cap is added, so `original` still means original quality; a source the webview could not have rendered anyway (HEVC) becomes h264 as a side effect, which is the only form of it that would have played. The decision is per item rather than blanket because the transcode costs the byte-range resumability `Static=true` gives the download worker (see DR-170 for what a chunked, length-less response does to a resume), so a file whose audio already plays keeps the direct copy. An unknown codec — item not fetchable, or the server named none — changes nothing: the policy only ever *adds* a transcode, so it cannot make a working download worse. The codec set judged against is the **webview's**, not the platform's, even though DR-161 made ExoPlayer the Android default: `experimentalNativeVideo` is a user setting, a downloaded file outlives whatever it was set to when the file arrived, and the narrow list is the only one that holds on both sides of it — at the cost of a Dolby-licensed device re-encoding a track its ExoPlayer could have played. `resolve_video_download_url` is the single entrance for all three resolution sites (the frontend's per-item command, the bulk series/season enqueue, and the offline-queued resume), since the pure builder cannot look a codec up and a caller that forgets to is exactly how the silent downloads shipped. **Files already downloaded stay silent** — the bytes on disk are the wrong bytes and only a re-download replaces them | Downloads | UR-071, UR-004 | Done |
+| DR-162 | Video streams are opened against a **bandwidth ceiling the user chose**, instead of a fixed allowance nobody could change. Every video URL carried `MaxStreamingBitrate=20000000`/`VideoBitrate=18000000`, `PlaybackInfo` negotiated at 20 Mbps, and the device profile advertised `999999999` — so on a metered or slow connection the only lever was not watching. `StreamingQuality` is a ladder of ceilings (Original, 20/10/8/4/2/1 Mbps, 720 kbps) in which a step is not a label but a bundle of transcode parameters: the total ceiling, the audio share of it, and the resolution that budget can carry. It lives in Rust because those numbers are Jellyfin encoding vocabulary — the frontend names a variant and reads labels back over `player_get_streaming_qualities`, the same arrangement as the EQ preset curves. The video bitrate is the total *minus* the audio share, so the two together honour the cap rather than overshooting it by the size of the audio track, and `MaxHeight` falls with the ladder so a small budget is not spent on pixels it cannot afford. The cap has to reach the **negotiation**, not only the transcode URL: `max_static_bitrate` in the device profile is what makes the server refuse to direct-play a source fatter than the ceiling, and without it a 30 Mbps remux is handed over untouched and every URL parameter downstream is moot — which is why it is applied at all four places that decide bandwidth (the HLS builder, `PlaybackInfo`, `open_live_stream`, and the background-audio handoff, which takes the lower of the cap and its own 384 kbps). The ceiling is process-wide rather than a field on `OnlineRepository`, mirroring `INCLUDE_CATALOG_BROWSE`: it is a preference about *this device's connection*, it must survive a repository rebuilt on re-login, and every builder plus the negotiation have to agree on it or the cap leaks. Settings owns the durable default and is the only writer to `app_settings` — persisted unlike the rest of `VideoSettings`, because a limit set for a metered connection that silently reverts to uncapped on the next launch spends the user's data with no changed setting to show for it — and it is restored at startup from the async runtime, defaulting to uncapped if the read fails so a database problem degrades to the old behaviour rather than to an arbitrary limit. The in-player menu is the per-video override: a cap is a property of the stream the server is producing, so it cannot be applied to one already in flight — `player_set_stream_quality` re-opens the stream at the new quality and resumes at the current position, reloading a native backend itself and handing HTML5 a URL for the same `reloadSource` primitive the audio-track switch uses, so no strategy branch lives in the UI. It deliberately does not persist. This gives UR-070 its resume-at-the-same-point mechanism; the server-offered per-item rendition list that requirement also asks for remains proposed | Playback | UR-074, UR-070 | Done |
+| DR-174 | Tiles of mixed shapes are laid out **justified** rather than gridded. A CSS grid gives every cell one box, so on a page holding square music covers, 16:9 library backdrops and 2:3 posters at once, everything that is not the chosen shape is cropped to it — the home shortcut strip was explicitly forcing `aspect="video"` on music libraries for exactly this reason, which lined the row up by cutting the covers down. `layoutMosaic` packs tiles into rows of a **shared height** and gives each its own width from its own aspect ratio: it adds tiles to a row until the height needed to fill the container has fallen to the target, closes the row there (so rows land at or below the target, never above), and justifies the row to the container width by absorbing the rounding remainder into its widest tile, where a pixel is least visible. The last row is deliberately *not* justified — with one tile left over, filling the width would inflate it to a banner — so it sits at the target height, left-aligned. Ratios are clamped to a band, which costs a crop on genuine outliers and stops one panorama owning a row or one very tall image shrinking to a sliver. It is a pure module with no DOM: the component supplies only the two things the DOM knows — the measured container width, and the artwork's *decoded* aspect ratio, reported by `CachedImage` so the layout uses the shape an image actually has rather than the one its item type implies. Those measurements are committed in one debounced batch rather than per image, because artwork arrives over several hundred milliseconds and re-packing on each arrival would shuffle the grid under the pointer repeatedly. Labels are drawn *over* the bottom of each tile rather than beneath it: a caption below sits outside the computed box, and one that wraps to two lines would break the row alignment the layout exists to provide | UI | UR-075 | Done |
+| DR-175 | A library knows which favourites category it belongs to, and the frontend does not work it out. The mosaic offers a favourites tile per category beside its library, which needs a collection-type → category answer; deriving it in Svelte would have re-created the exact leak `SearchScope::item_types` was extracted to close (docs/specs/scoped-search-boundary.md) — one table of Jellyfin vocabulary, differing only in which vocabulary. `SearchScope::for_collection_type` maps `movies`/`tvshows`/`music` and returns `None` for everything else, so a Live TV or books library gets no tile at all rather than one opening an unfiltered list; `All` is never derived from a library, being the cross-library entry offered beside them rather than a property of one. `Library::new` stamps the result onto every library at construction — a constructor rather than a struct literal precisely so a derived field cannot be forgotten at one of the four sites — and it rides to the frontend as an optional `favoritesScope`, absent rather than null when there is none. The UI's remaining share is presentation only: what to call the tile, where to put it, and showing a category's tile **once** however many libraries share it, since two movie libraries have one favourites list between them | UI | UR-075, UR-067 | Done |
+| DR-176 | The server is never asked to burn a subtitle into the picture. `PlaybackInfo` omitted `SubtitleStreamIndex`, which does not mean "none" — the server then honours the source's default/forced flag and picks a track itself. On a source whose default subtitle is image-based (PGS/DVD/DVB) that track cannot go out as a sidecar, so the server falls back to `SubtitleMethod=Encode` and composites it into the video. The cost lands on the *video*, not the subtitle: burn-in rules out remuxing, so an HEVC stream the device could have taken untouched is re-encoded frame by frame. Observed on an HEVC + E-AC-3 + PGSSUB episode, where only the audio actually needed transcoding: the server could not sustain the re-encode in real time, the buffer never grew past a single segment, and playback stalled every few seconds — taking seeking with it, since each seek restarted the encoder and cost seconds before the first frame. The fix is to request `SubtitleStreamIndex=-1` explicitly and to advertise every *text* format we can render (`srt`/`subrip`/`ass`/`ssa`/`vtt`) as `External`, so a subtitle can only ever arrive as a sidecar. Nothing is lost, because the app already fetches subtitle tracks itself and draws them over the video (UR-020) — the server's composited copy was always redundant. Image-based tracks are consequently not offered, which is honest rather than a regression: the renderer cannot composite a bitmap, and the previous behaviour paid for them by making the whole stream unwatchable. Both halves of that hold at the layer that can enforce them. The sentinel travels on the stream URL as well as in the negotiation, because the negotiation is not what opens most streams — a quality switch, a transcoded seek and an audio-track switch each rebuild the URL on their own, and an omitted index there lets the server pick the default track back up out of whatever session state it still holds. And "not offered" is enforced where the offer is made: each subtitle stream crosses the boundary carrying the backend's verdict on whether it can arrive as a sidecar, so the picker lists only tracks the app can draw instead of showing an entry that ticks and displays nothing. Only an explicit "no" hides a track, so a stream carrying no verdict behaves as before | Playback | UR-020, UR-004 | Done |
+| DR-177 | Each video transcode this device opens is its own server-side job, and the one it replaces is stopped. Jellyfin keys a transcode job by device **and** play session, and every stream URL the app built carried the same hardcoded `DeviceId` with no `PlaySessionId` at all — so the second stream for an item was indistinguishable from the first. Re-opening a stream is not rare: a mid-playback quality switch (UR-074), a transcoded seek and an audio-track switch all do it, each leaving the previous ffmpeg running. Observed on-device when switching bitrate mid-film: the server served the new playlist, then rejected the new job's segments with `400 hls1/main/0.ts` while the two jobs contended for one transcode path, and playback stalled — reproducible against the server, where a second stream for a live job's item alternates between serving bytes and 400ing per attempt, which is what made it read as flaky rather than broken. `begin_video_play_session` mints a session id per open and reports the one it supersedes; the URL builder stops that job (`DELETE /Videos/ActiveEncodings`, un-retried and best-effort — a slow stop must not delay playback, and the new stream no longer collides either way) before returning. Placing it in the URL builder rather than in each caller means every re-open path is covered by construction. Two client faults made the same incident worse and are fixed with it: the fatal-HLS-error handler added the transcode seek offset to a position that already included it, so past roughly the halfway mark of a film any transient network error cleared the "near end" threshold and was reported as end-of-stream — turning a recoverable stall into a skip to the next item, exactly when a quality switch had just made the offset large; and the HTML5 reload primitive resolved on its own `canplay` timeout, so a reload the server never served reported success, leaving the picker showing a quality that was not playing and the caller with nothing to revert | Playback | UR-074, UR-004 | Done |
+| DR-178 | Every position that leaves the app is read from the controller, not from a backend that may not be playing anything. `PlayerController::position()` forwards to the native backend, which is authoritative for exactly one of the three ways this app renders media. On the **webview** path — the shipping default for video on both platforms — nothing is loaded into that backend at all: the `<video>` element is the player, its ticks were re-emitted to the frontend and then dropped, and the backend answered 0 forever. During a **background-audio handoff** the base that converts the stream's relative timeline to the episode's is applied once at the native tick boundary (DR-159), so before ExoPlayer's first tick nothing has applied it and the reading is 0 there too. Both holes surfaced as the same user-visible bug through different doors: returning to the foreground while the audio-only transcode was still opening handed the frontend `0.0`, and the video reloaded at `StartTimeTicks=0` — the episode restarting from the beginning — while the `Stopped` report that followed wrote that zero to Jellyfin as the resume point. `absolute_position()` answers for all three paths: the maximum of the backend's reading, the last position webview-rendered media reported, and the handoff base. The maximum is exact rather than a heuristic, because at most one term is ever meaningful at a time and the base is a floor the stream cannot physically be behind. `duration()` gains the same fallback for the same reason. The element's reading is cleared wherever it stops being the player — teardown, a handoff taking over, a different item loading — so it can never be attributed to what plays next | Player | UR-005, UR-025, UR-040 | Done (pending device verification) |
+| DR-179 | Jellyfin is told what was played: progress while it plays, and a stop when it ends. A device trace of 35 minutes' playback requested `/Sessions/Playing/Progress` **zero** times and sent 14 `Stopped` reports, every one of them at position 0. Three faults, one subject. *Progress never left the device*: the frontend service writes it to the local DB by design, and nothing on the Rust side reported it for webview-rendered media — so the server learned a position only when the player was closed, and a crash or a swipe-away cost the session. It is now reported from the controller's own position ticks, through the 30s throttler it already owned and shares with the native audio path, which covers all three rendering paths in one place instead of adding a second frequent IPC caller. *Zero-position stops were sent*: Jellyfin stores the reported position as the resume point, so a zero does not merely fail to inform, it instructs the server to forget — and no zero was ever real, each one coming from asking a player that was not rendering the media (see DR-178). They are withheld; one landed 40s after the frontend had correctly reported 15:22 for the same episode, overwriting it. *A finished episode reported nothing at all*: Jellyfin decides "watched" from the stop report and its percentage, and in background audio-only mode nobody sends one — the webview is suspended and its element was torn down at the handoff, while the backend advances to the next episode without a word about the one that ended, so an episode listened to end-to-end on the lockscreen never counted as watched. `on_playback_ended` now reports it stopped at its **runtime** (not the last tick, which can be seconds short or, on a handoff whose ticks stopped early, nowhere near the end) before any advance, since after one the queue's current item is the next episode. Scoped to the audio-only handoff, the case the frontend provably cannot cover, so foreground playback keeps its single existing report; music ending natively remains unreported and wants its own change. The reporting seam is a `PlaybackReportSink` the controller sends to, which also collapses three copies of the spawn-a-task-and-hope block into one and is what let all of this be written as failing tests rather than found on a device a second time | Player | UR-025, UR-005, UR-040 | Done (pending device verification) |
+| DR-180 | A background-audio handoff of a **downloaded** episode starts where the video left off. The handoff prefers a local file over the audio-only stream (DR-128), but the two begin in different places and were treated alike: a stream is built with `StartTimeTicks`, so the server makes the handoff point that stream's zero and the base is the handoff position with no seek — while a file has no such parameter and begins at the episode's own zero, so basing it at the handoff position claimed minutes of audio that were about to play from the beginning. Backgrounding a downloaded episode therefore restarted it while the lockscreen scrubber, dutifully adding the base, showed the position it should have been at. `background_audio_plan` splits the two: a file gets no base and a real seek, a stream keeps the base and no seek (seeking one would skip *past* the content by the handoff position again). The same distinction settles an inbound seek — `seek_absolute` re-opens a *streamed* handoff at the requested position because a chunked length-less transcode cannot honour a seek, which is not true of local media, and `resume_stream_at` refuses a non-remote source outright, so routing a lockscreen scrub of a downloaded episode through it failed the seek rather than performing it | Player | UR-040, UR-071 | Done (pending device verification) |
+| DR-181 | A resumed transcode plays. Every video stream URL carried the resume position as `StartTimeTicks`, which is correct for a progressive response and fatal for an HLS one: Jellyfin builds each segment URI by echoing the **master playlist's** query string into it, and its segment handler opens by rejecting any request carrying `StartTimeTicks > 0` (`ArgumentException` → `400`). One position on the playlist therefore 400s every `hls1/main/N.ts` behind it, so hls.js exhausted its retries and gave up — presenting as an episode that will not resume while the same episode from the beginning is fine, the `> 0` being exactly why the beginning survived. The parameter is also unnecessary there: a playlist spans the whole item and asking for segment N *is* the seek, which the server transcodes from. So it is removed from the URL builder entirely rather than conditionalised — the builder has one caller shape and no way to know whether the response will be segmented — and the position becomes what it always was for HLS, a seek issued once the player has loaded: the seek path reloads at zero and seeks the element, and the resume path lets the player seek itself. The progressive `/Audio/universal` builder used by the background-audio handoff is a different endpoint with no segments and keeps its `StartTimeTicks`, which is why an audio-only handoff resumes correctly and a video one did not | Playback | UR-004, UR-074 | Done |
+| DR-182 | Native video shows a picture. The poster/title card is an opaque `bg-black` overlay drawn over the whole video area while `isMediaReady` is false, and **every** signal that clears it is emitted by the HTML5 `<video>` element — `canplay`, `loadedmetadata`, hls.js `FRAG_BUFFERED`, the `playing` event, and two `readyState` timeouts. The native path renders no such element (`{#if !!useHtml5Element}`), so on Android nothing could ever clear it: ExoPlayer decoded to a live SurfaceView behind a black div for the entire session. That is DR-172's "audio with no picture" report, and it is indistinguishable on screen from the compositing failure DR-172 attributed it to — which is why the flag was reverted rather than fixed. Both the overlay and the native branch date from the original POC commit, so the native path has never been able to reveal itself; the 2026-08-11 device verification predates neither and does not contradict this, since a spike run that never reached a steady state would not have shown it. The backend's own events are the equivalent signals and `nativeSignalRevealsVideo` is the rule for reading them: `state === "playing"` mirrors the element's `playing` event, and a position tick carrying a real position or duration mirrors the `readyState` backstops, covering a first state event that is dropped or arrives before the listener is attached. `buffering`/`paused`/`stopped`/`error` deliberately do not qualify — revealing on `error` would replace the title card with a transparent hole showing the launcher through the app. The rule is a pure module rather than a branch inside the component because the decision that was missing is exactly the part worth guarding, and the component needs a DOM and a mounted player to exercise | UI | UR-003, UR-004, UR-041 | Done |
+| DR-183 | The JavaScript bridges are installed before the page that uses them loads. WebView binds an injected object into JS at **page-load time**: an `addJavascriptInterface` call landing after the page has loaded does not appear to that page. They were installed from `configureWebViewForMedia`, which finds the WebView by walking the view tree 500 ms after `onCreate` — a race against Tauri's own page load, and one that is *permanent* when lost, because the identity guard added for DR-097's stale-proxy bug then declines to re-inject on every later resume pass. The whole set (`AndroidVideoSurface`, `AndroidPictureInPicture`, `AndroidBackgroundAudio`, `AndroidNetworkType`, `AndroidImmersive`, `AndroidInsets`) would simply be absent from `window`, and silently: every call site optional-chains the bridge, so a missing one is a no-op rather than an error. This is a candidate explanation for DR-172's other piece of evidence — `WebView transparent = false` logged, `= true` never appearing, i.e. the enable call never reaching Kotlin at all. `WryActivity.setWebView()` calls the `onWebViewCreate` hook immediately before wry issues the first `loadUrl` (confirmed in wry 0.55's `main_pipe.rs`, where the `setWebView` JNI call precedes `load_url`), so a bridge installed there is bound by the time any page runs. The hook can fire during `super.onCreate()`, before the rest of our own `onCreate`, so only work needing nothing but the WebView moves into it — insets stay in `configureWebViewForMedia`, which runs later and on every resume. The tree-walk path is kept as a fallback, and `enableNativeVideoCompositing` now logs an explicit error when the bridge is missing, so the ambiguity that left DR-172 unresolved cannot recur silently | Android | UR-003, UR-004, UR-040, UR-041 | Done |
+| DR-184 | The video SurfaceView leaves the view hierarchy when the video does. `VideoOverlayManager.detachVideoSurface` had **no callers anywhere in the tree** — the mirror of the DR-151 defect, where `setActivity` had none — so `attachVideoSurface` was one-way: `JellyTauPlayer.clearVideoSurface()` dropped its `surfaceView` reference and cleared ExoPlayer's without removing the view, leaving it parented to the content view for the life of the process, with the next native video adding another SurfaceView beneath it. The stack was invisible while the WebView was opaque, which is why it went unnoticed. Two consequences outlive the leak: `isVideoSurfaceAttached()` gates `PictureInPictureManager.canEnterPip` through `isNativeVideoPath()`, so it reported an attached surface forever after the first native video (saved from offering PiP over nothing only by the `isPlayingVideo()` check beside it), and every abandoned surface held its `OnLayoutChangeListener` on the content view. Detach is called from `clearVideoSurface`, which covers stop, the switch to audio, and the background-audio handoff, and always runs on the main thread because every caller is already inside a `mainHandler.post`. It removes the view from its *own* parent rather than looking the content view up from an Activity reference, so an Activity recreated underneath it cannot strand the view | Android | UR-003, UR-041 | Done |
+| DR-185 | The app shell stops painting over the video surface. `app.css` clears the page's opaque layers for native video through three selectors, and one of them — `html[data-native-video="active"] [data-app-shell]` — was written against an attribute **no component has ever set, in any commit**. The shell is `+layout.svelte`'s root `div`, which paints `--color-background` across the entire viewport; VideoPlayer is `fixed inset-0 z-50` and correctly makes *itself* transparent on the native path, but it stacks *above* the shell, so the WebView still composited the shell's opaque background over the whole screen and the SurfaceView behind it could never be seen. This is the missing half of the compositing DR-172 went looking for: the spec's own layer table lists this layer as "cleared by `data-native-video` → app.css", which was written but never wired, and `html`/`body` being genuinely transparent made the CSS look correct in isolation. The failure is invisible three ways over — the CSS is valid, the selector is plausible, and a rule matching nothing looks exactly like a rule matching something already transparent — while the symptom (black screen, audio fine) is identical to a real compositing failure, which is how it survived DR-150 through DR-172. Fixed by setting the attribute the rule was written for, and guarded by asserting the *relationship* rather than the rule: every attribute the compositing block targets must be set somewhere in the app, so a selector aimed at nothing fails the suite instead of failing silently on a device | UI | UR-003, UR-004, UR-041 | Done |
+| DR-186 | The play overlay comes down when the backend plays. `isPlaying` was assigned once from the `player_play_item` response and thereafter only by the `player://state-changed` listener — a channel the backend never emits, the same dead wire that DR-182's first fix was mistakenly hung on. On the native path the flag therefore froze at whatever the initial response said: with ExoPlayer playing, the UI still believed it was paused, so the `bg-black/30` play-button overlay stayed raised across the whole video area and the transport button kept showing ▶. The video was simultaneously dimmed and covered while it played, which reads as "the overlay never goes away" and is easily mistaken for a second compositing fault. The mirror reads the same `player` store `playerEvents.ts` feeds, which is what the architecture already says is authoritative — the player reports state, the UI consumes it — and is gated to the native path so HTML5 keeps its element-event wiring, which is authoritative there | UI | UR-003, UR-005 | Done |
+| DR-187 | The system bars go away with the player, not only with the fullscreen button. `enterImmersive()` had exactly one caller, `toggleFullscreen()`, so opening the player left the status and navigation bars painted over it until the user pressed a button most never press. On the native path this is worse than cosmetic: the SurfaceView fills the content view, so the bars sit directly on top of the video. The player is a full-screen surface by construction — `fixed inset-0 z-50` over a `MATCH_PARENT` surface — so entry is the right moment. Called synchronously in `onMount` before any `await`, per the native-mode pitfall, and paired with the `exitImmersive()` already unconditional in `onDestroy`, so a player torn down while immersive cannot leave the rest of the app without bars | UI | UR-066, UR-003 | Done |
+| DR-188 | Native Android video is **ready to be the default except for the background-audio handoff**, and the flip therefore waits. The picture defects behind DR-172 are all found, fixed and device-verified — DR-185 (the app shell painted over the surface through a CSS rule targeting an attribute nothing set), DR-182 (nothing could lift the poster card on a path with no `<video>` element), DR-183 (the JS bridges raced the page load, so `setTransparent(true)` could never arrive), DR-184 (the SurfaceView was never detached), plus DR-186 and DR-187, the two UI defects only this path could reveal. On a device logcat now carries `WebView transparent = true` and `Marking media ready` with video on screen, which is the pair DR-172 went looking for and could not find, and skip, seek and rotation were exercised by hand. Turning the default on then surfaced a *different* unverified sub-path: returning from background audio is HTML5-only (DR-190), so on the native path playback simply stays dead. Shipping it would have repeated DR-161 exactly — a verified sub-path made default over an unverified one — so the default stays off and the flip is gated on DR-190 rather than on more confidence | UI | UR-003, UR-004, UR-041 | Blocked by DR-190 |
+| DR-191 | Forcing the WebView overlay to redraw from the Activity, because with the ExoPlayer **SurfaceView** beneath it the overlay's ordinary damage stopped reaching the screen: the page kept mutating — the clock text every second, the control bar's opacity going to 0 — while the display held whatever frame it last presented, over video that animated perfectly. Not a state defect; the live DOM showed the slider advancing 476 → 479 across three seconds behind a screen showing neither. Only **structural** changes got through, which is why the play overlay always appeared to work (an `{#if}` block, added and removed) while the progress bar never did, and why rotation lost the transport UI. A CSS animation cannot help, since opacity animates on the compositor without repainting the layer. **Superseded by DR-192**: this drove `postInvalidateOnAnimation` in a loop, which treats the symptom — the cause is the SurfaceView's separate layer, and removing that removes the need. Kept as the record of how the mechanism was identified | Android | UR-003, UR-004 | Superseded by DR-192 |
+| DR-195 | Play/pause works on the native path, because the frontend stops claiming a webview element is playing when there is none. `html5_playing` is Rust's record of "a webview `<video>` is active and in this state", and `toggle_playback`, `play` and `pause` all route transport to that element whenever it is set. The player route mirrored element state into it **unconditionally** — from `handleReportStart` and, fatally, from `handleReportProgress`, which VideoPlayer calls on a 10-second interval — so on the native path the frontend re-declared every ten seconds that an element was playing when none existed, and every transport intent was emitted into the void. The pause button was dead from the on-screen tap, from the control bar, and from a direct `player_toggle` invocation, while seek and skip kept working because `player_seek_video` decides elsewhere; that asymmetry is the signature. It also explains the flashing, since the control bar and the JRay overlay both key off `isPlaying`, which was being contradicted on every interval tick. DR-193 clearing the flag at load was necessary but insufficient on its own — the interval put it straight back. The mirror now lives in `mirrorElementStateToRust` in VideoPlayer, gated on `useHtml5Element`, which is the only place that knows whether an element renders at all; the route cannot tell the two paths apart, which is precisely how it came to lie. Confirmed on device by ADB: surface tap and control bar each pause (position frozen across repeated samples, transport label flipped) and resume | Playback | UR-005, UR-003 | Done |
+| DR-194 | The previous frame flashing on rotation. It reads as a TextureView artefact — the view retains its last frame, so between a rotation and `fitSurfaceToScreen()` landing that frame sits at the old size — and two fixes were built on that reading: revealing after two `postOnAnimation` hops, then revealing on `onSurfaceTextureUpdated`, which required owning the `SurfaceTextureListener` and handing ExoPlayer the Surface directly rather than via `setVideoTextureView`. **Neither stopped the flash.** The mechanism is the *window's* rotation animation: Android cross-fades a **screenshot of the old orientation**, that screenshot contains the old video frame at the old size, and no TextureView bookkeeping can reach it — nor can the app pre-empt the screenshot, since `onConfigurationChanged` fires after it is taken. The only lever is to stop the animation: `ROTATION_ANIMATION_JUMPCUT`. That was accepted and silently ignored at first, and the platform said why out loud — `VRI[MainActivity]: setLayoutParams: not fullscreen` — because the attribute is honoured only for a fullscreen window. `FLAG_FULLSCREEN` (deprecated for hiding system bars, which immersive mode does instead, but still what marks the window fullscreen for this decision) is therefore set alongside it, scoped to while native compositing is active so the rest of the app keeps its normal animation. The frame-arrival reveal is kept: it replaced a fixed-timeout guess with a real signal, and its timeout is required rather than defensive, since a resize while paused means no new frame is ever coming. **The flash is not confirmed fixed on device** — the forced-rotation harness (`settings put system user_rotation`) proved unreliable, and `screenrecord` fixes its canvas at start so a rotation inside a recording never changes frame dimensions, which defeated two attempts at measuring it | Android | UR-003, UR-066 | Needs device verification |
+| DR-193 | Play/pause reaches the player that is actually rendering. `toggle_playback`, `play` and `pause` all route to the webview element when `is_html5_active()`, which is `html5_playing.is_some()` — a flag written **only** by the element's own state reports and cleared only when it reports "stopped"/"idle" (or on a background-audio handoff). An element that went away without that final report, or webview-rendered music earlier in the same process, therefore left the flag set, and on Android's native video path every transport intent was emitted as a `ControlCommand` at an element that no longer existed: the pause button did nothing, from the on-screen tap and from the control bar alike, while seek and skip kept working because `player_seek_video` decides elsewhere. Whether it happened at all depended on what had played before, which is exactly what made it read as flaky rather than broken. `load_and_play` — the native load path, and the one the HTML5 video path deliberately avoids via `set_current_item` — now clears the flag, because loading into the native backend *is* the statement that native renders this item. Nothing is lost on the webview path: an element re-establishes its own authority the moment it reports again, so this is the existing "element is gone" semantics applied where it can be known directly rather than inferred from a report that may never arrive | Playback | UR-005, UR-003 | Done |
+| DR-192 | Native video presents through a **TextureView**, not a SurfaceView. A SurfaceView renders on its own layer *outside* the app window and punches a transparent region through it; everything drawn above that hole — for us the entire Svelte UI in a transparent WebView — depends on that composition path, and Android's own graphics documentation states that "overlays do not currently work correctly with SurfaceView or TextureView". The consequences were four symptoms of one cause (DR-191): a frozen progress bar, controls that would not fade, rotation losing the transport UI, and overlays that lingered after the DOM removed them. A TextureView is an ordinary view whose frames are drawn as a texture in the window's normal rendering pass, so there is no second layer and no transparent region, and the WebView above composites like it would over any other view — which is why media3 offers `surface_type="texture_view"` and why it is the standard remedy for ExoPlayer overlay problems. The trade is accepted rather than hidden: TextureView costs more power and memory than SurfaceView and adds a frame of latency, but hardware decode through MediaCodec is untouched, so the reason native video exists survives it. `setVideoTextureView` installs ExoPlayer's own `SurfaceTextureListener`, so the old `SurfaceHolder.Callback` wiring is deleted rather than ported — adding a listener of ours would displace it and the video would never appear. PiP needs no change, since a TextureView is a View and the aspect-ratio probe reads its measured bounds | Android | UR-003, UR-004, UR-041 | Done |
+| DR-190 | The background-audio handoff can return to the native path. Everything that restores playback on the way back is written around the WebView `<video>`: `applyPendingForegroundSeek` returns early on `!videoElement`, the HLS re-init `$effect` returns early on `!useHtml5Element`, and `pendingForegroundSeek`/`pendingForegroundPlay` — which own the post-handoff position and play/pause — are consumed only by `handleCanPlay` and `markMediaReady`, an element event and a path that reaches the same guard. On the native path there is no element, so `exitBackgroundAudioHandoff` completes, clears `handoffState`, blanks and reassigns `currentStreamUrl` to force an effect that will not run, and nothing ever restarts ExoPlayer: the user returns from the lockscreen to a dead player. This never showed while the path was opt-in and its picture was invisible anyway. The return needs the native equivalent of the element reload — re-issue the item to the backend, seek to the position `player_exit_background_audio` reports, then honour `wasPlaying` — routed through the adapter rather than the element, so both paths restore through one contract | Playback | UR-040, UR-003 | Proposed |
+| DR-161 | Native video is the default, so picture-in-picture has a real surface. DR-160 makes PiP work on the HTML5 path, but that path can only ever shrink the *UI* into the PiP window; showing the video itself needs the SurfaceView behind the WebView, which is what `experimentalNativeVideo` gates. The flag now defaults to on when the user has never chosen, with an explicit stored choice still winning in both directions so anyone who turned it off keeps it off. This is a deliberate acceptance of risk: the flag existed because the native path was an unfinished spike, and `VideoPlayer.scrubRegression.test.ts` documents its history — a native init that flipped to HTML5 mid-lifecycle and left seeks going down one path while ExoPlayer played on another. Those tests pin the **flag-off** interim override (native response overridden to HTML5, backend stopped once), which the default no longer selects, so they now mock the flag off rather than inherit it: they still guard that path, but they no longer describe what ships. The native scrub/seek path is consequently not covered by the suite and needs device verification | UI | UR-041, UR-003 | Needs device verification |
+| DR-159 | The background-audio handoff stops leaking its relative timeline. The handoff plays the episode as a *relative* stream — the audio-only URL is built with `StartTimeTicks` = the position the screen was locked at, so ExoPlayer's zero is the handoff point — and `background_audio_base` holds the offset that turns one back into a real position. The base was a **display-only** correction, applied in exactly two places (the lockscreen scrubber and the internal truncation maths) while every other consumer worked in the relative timeline treating the number as absolute. Each crossing threw away exactly `base` seconds, which is why the jump-back distance varied with where the screen was locked and read as random. Three crossings were live: progress reporting to Jellyfin sent the relative position every 30s, so the server was told `real − base` — and since DR-155 now mirrors the server's position back and refreshes on a cache hit, that regressed value returned as the resume point (lock at 40 min, listen to 90, reopen at 50); lockscreen seeks went out absolute and came back relative, against a chunked length-less transcode that cannot honour a seek at all, so a clamped seek landed at stream zero; and media3's own `seekToDefaultPosition`/`seekBack`/`seekForward` bypassed the `ForwardingPlayer` wrapper entirely, reaching the real ExoPlayer — `Util.handlePlayButtonAction` seeking an ended player to the relative zero being the same mechanism as DR-129's truncation bug through a different door. The fix converts **once, at the boundary**: `JellyTauPlayer`'s position tick adds the base (and shifts the duration with it, since the stream's own length is only what remains) before either `nativeOnPositionUpdate` or the lockscreen sees it, so position updates, progress reports, the frontend and the truncation check all speak the episode's timeline and none needs to know a handoff happened. The base is consequently *removed* from `claim_stream_resume`, `truncated_stream_resume_position` and `player_exit_background_audio`, where adding it now double-counts, and the lockscreen's `positionOffsetMs` addition goes with it (the field remains, read-only, as the tick's input). Inbound seeks go the other way: `seek_absolute` is the new boundary for every outside seek, re-opening the stream at the requested position via `resume_stream_at` when a handoff is active — which is what `onSeekTo` had claimed for months in a comment describing code that did not exist — and an ordinary seek otherwise. `seekToDefaultPosition` is swallowed rather than forwarded, since Rust already owns what "play after the stream ended" means and the `play()` that follows reaches it. Exit reads the position *before* clearing either base, or a tick landing in between hands back a relative one | Player | UR-040, UR-005, UR-025 | Done (pending device verification) |
+| DR-158 | A watched toggle, on the episode row, the season header, the series and movie hero, and the Episode Focus View. Both halves of the backend already existed and neither had a caller: `mark_played` (`POST /PlayedItems`) was reachable only from the sync drain replaying rows the *reporter* had queued, and `clear_watch_history` (`DELETE /PlayedItems`) only from the destructive "erase this series' history" button — so the sole way to mark something watched was to play it. Jellyfin applies both recursively over a season or series, so the container case needs no client-side fan-out *online*. Offline it does: `storage_set_watched` writes the item **and its descendants** (drawn from `items` by `parent_id`/`album_id`/`season_id`/`series_id`, so an uncached id selects nothing and the statement no-ops instead of raising a foreign-key error), because otherwise marking a season watched with no server would tick the season and leave every episode inside it unwatched. It is deliberately separate from `storage_mark_played`, which stays the single-item "this finished playing" path that increments `play_count`. Un-marking clears the resume position as well as the flag, matching the server. `QueuedOp::MarkUnplayed` gives the queue the missing direction — pushing as `clear_watch_history` — so the toggle works offline both ways rather than only one; without it un-marking would have been the half that needed a connection. The button is an everyday toggle, so unlike `ClearHistoryButton` it does not confirm, and it holds an optimistic state because the caller's `watched` prop only catches up after a reload (a season means a round trip, during which the button would otherwise appear to ignore the tap) | UI | UR-073 | Done |
+| DR-157 | Full-screen video on Android actually goes full screen. `toggleFullscreen` called `document.documentElement.requestFullscreen()` and nothing else, which inside an Android WebView does not touch the Activity window — it expands the element within a viewport that already spans the whole screen, because `enableEdgeToEdge()` is called in `onCreate` and SDK 36 ignores the opt-out. So the control did nothing visible while the status bar and navigation/gesture bar stayed painted over the video, and (unlike DR-112's chrome-clearance work, which is about *reserving* space for the bars) here the bars should not be there at all. `ImmersiveModeBridge` hides them via `WindowInsetsControllerCompat` with `BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE`, so an edge swipe brings them back transiently over the video instead of resizing the window mid-playback, and the system's own gestures stay reachable. Exposed as the `AndroidImmersive` bridge and posted to the main thread, since `@JavascriptInterface` methods arrive on a WebView binder thread. `requestFullscreen()` is kept for the platforms where it does work, but its rejection is caught rather than allowed to abort the immersive call. Restoring is wired to three paths, not one: leaving fullscreen, Escape (which previously called `document.exitFullscreen()` directly, bypassing the flag and the bars), and `onDestroy` — the bars belong to the Activity, so a player torn down while immersive would strand every screen behind it without them. The `--jt-inset-*` properties need no special handling: hiding the bars fires the decor view's inset listener with zeroes and `WindowInsetsBridge` republishes them | UI | UR-066 | Done |
+| DR-143 | Flipping the offline downloaded-only gate actually re-queries the listing. The gate (DR-078) is a process-wide flag in Rust consulted only *while a query runs*, but no library surface re-queried when its inputs changed: `useServerReachabilityReload` fires only on the offline → **online** transition, and `GenericMediaListPage`, `GenericGenreBrowser` and the favourites page never even called its `checkServerReachability`. So going offline left the full server catalog on screen under a now-closed gate, and toggling "Show all server media" only greyed cards — `MediaCard.isServerOnly` is a pure frontend derivation that updates instantly — without adding or removing a single row. The filter therefore read as "shows everything until I filter, then greys some of it" while the backend gate was correct and simply never exercised. `catalogFilterVersion` is the refetch signal: `pushCatalogVisibility` now awaits `set_show_server_catalog` and bumps the version only **after** the backend accepts the new flag, since a reload racing the push would re-query under the old gate and undo itself. A failed push clears `lastIncludeCatalog` instead of latching it, so the next identical transition is retried rather than skipped as a no-op and left permanently disagreeing with the backend. `useOfflineFilterReload` subscribes pages to that signal, skipping the value they already loaded under; it is wired into both generic list components and the movies/music/tv/favourites landing pages and the `/library/[id]` detail page | UI | UR-052 | Done |
+| DR-135 | A download's media type comes from the item, not a default. `download_item` — the path a media card uses to queue an item while offline — never records `media_type`, and the reconnect resolver read that NULL as `'audio'`, so a **movie** queued from a card had its URL resolved by `get_audio_stream_url`. The file that landed on disk was an audio-only transcode, which is why a "downloaded" film could never play offline no matter how the path or protocol was fixed. The resolver now falls back to the item's own `item_type` (`VIDEO_ITEM_TYPES` in Rust, so the frontend never learns which types are video) and only defaults to audio when the item is not cached locally. An explicit `media_type` on the row still wins | Downloads | UR-071, UR-052 | Done |
+| DR-136 | Rows already downloaded under the audio default are repaired, not just prevented. They are identifiable after the fact — no `media_type`, but a video item — so on reconnect they are reset to `pending` with their audio URL cleared and re-resolved by DR-135's corrected logic, overwriting the audio file in place. Without this the fix is invisible to anyone who had already queued a film: the row still reads "downloaded" and still fails to play. Rows carrying an explicit `media_type` and genuine audio downloads are left untouched | Downloads | UR-071 | Done |
+| DR-137 | Local media is served to the player over a loopback HTTP server, not the asset protocol. Tauri's `asset` protocol answers a request carrying no `Range` header by reading the whole file into memory, and only advertises `Accept-Ranges: bytes` from *inside* its range branch — so the first request never learns ranges exist and a multi-gigabyte body is attempted instead. Chromium abandoned it with `PIPELINE_ERROR_READ` after ~31s, which reached the user as "downloaded video does not play offline". Real HTTP on `127.0.0.1` is chosen over a custom URI scheme deliberately: range support becomes a property of the transport rather than depending on whether a platform's webview forwards `Range` to a custom scheme. No response ever exceeds a 4 MiB chunk and bodies stream from the file handle, so memory is bounded regardless of file size. Because **loopback is shared between apps on Android**, the server binds `127.0.0.1` only and every URL carries a random per-session token; paths are additionally confined to the app data directory, so a leaked URL cannot read outside it. This is stage 1 of making the server the single media origin — remote passthrough and download-while-watching are deliberately out of scope here | Playback | UR-071 | Done |
+| DR-138 | Loopback is exempted from Android's cleartext ban, and nothing else is. Release builds set `usesCleartextTraffic="false"`, so the webview's request to the local media server (DR-137) was rejected by network security policy before any I/O — `<video>` failed in the same millisecond as `loadstart`, with `NETWORK_NO_SOURCE` and no server-side log at all, which is why it looked identical to a missing file. A `network-security-config` resource permits cleartext for `127.0.0.1` only and keeps `base-config cleartextTrafficPermitted="false"`, so a remote server must still be HTTPS; this is deliberately not a blanket opt-in. The manifest attribute is ignored once the config is present, so the config is the single authority. `sync-android-sources.sh` also had to learn to copy `res/xml`, which it skipped — the manifest references the resource, so a missed copy fails the resource link rather than degrading quietly | Security | UR-071 | Done |
+| DR-093 | Traceability coverage gate derives its requirement denominators from `requirements.md` at run time rather than hardcoded literals: `countDefinedRequirements` counts an ID only where it leads a markdown table row (ignoring the "Traces To" column and prose) and deduplicates IDs listed both in the definition tables and in the §3 traceability matrix; `computeCoverage` reports the *intersection* of traced and defined IDs so an ID traced in code but absent from `requirements.md` is surfaced as `orphaned` instead of inflating the ratio past 100%. UT/IT test identifiers are excluded as a separate taxonomy. CI and `bun run traces:coverage` share this computation and fail on both a sub-threshold and an impossible >100% result | Tooling | - | Done |
+
+---
+
+## 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, DR-182, DR-183, DR-184, DR-185, DR-186, DR-187, DR-188, DR-190, DR-191, DR-192, DR-193, DR-194, DR-195 |
+| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006, DR-129, DR-171, DR-176, DR-177, DR-181, DR-182, DR-183, DR-185, DR-188 |
+| UR-005 | - | DR-001, DR-005, DR-009, DR-178, DR-179, DR-186, DR-193, DR-195 |
+| UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
+| UR-007 | IR-010 | DR-007, DR-008, DR-016 |
+| UR-008 | IR-010 | DR-007, DR-011 |
+| UR-009 | IR-009, IR-010, IR-011 | - |
+| UR-010 | IR-012, IR-021 | DR-037, DR-059 |
+| UR-011 | IR-013 | DR-003, DR-015, DR-018 |
+| UR-012 | IR-009, IR-014 | - |
+| UR-013 | IR-013 | DR-017 |
+| UR-014 | IR-010 | DR-014, DR-019 |
+| UR-015 | - | DR-005, DR-020 |
+| UR-016 | - | - |
+| UR-017 | - | DR-014, DR-021 |
+| UR-018 | IR-013 | DR-015, DR-018, DR-173 |
+| UR-019 | IR-015 | DR-022 |
+| UR-020 | IR-016, IR-018 | DR-023, DR-176 |
+| 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, DR-131, DR-132, DR-178, DR-179 |
+| UR-026 | - | DR-029, DR-048, DR-050 |
+| UR-027 | IR-020 | DR-030 |
+| UR-028 | - | DR-031 |
+| UR-029 | - | DR-032 |
+| UR-030 | IR-010 | DR-033 |
+| UR-031 | - | DR-034 |
+| UR-032 | - | DR-035 |
+| UR-033 | - | DR-036 |
+| UR-034 | IR-010, IR-024 | DR-038, DR-039 |
+| UR-035 | IR-022, IR-023 | DR-040, DR-044 |
+| UR-036 | IR-022, IR-023 | DR-041 |
+| UR-037 | IR-010 | DR-042 |
+| UR-038 | IR-010 | DR-043 |
+| UR-039 | - | DR-045, DR-046 |
+| UR-040 | IR-025 | DR-051, DR-052, DR-129, DR-130, DR-159, DR-178, DR-179, DR-180, DR-183, DR-190 |
+| UR-041 | IR-026 | DR-053, DR-160, DR-161, DR-172, DR-182, DR-183, DR-184, DR-185, DR-188 |
+| UR-042 | IR-009, IR-014 | DR-054 |
+| UR-043 | IR-027 | DR-055 |
+| UR-044 | - | DR-056 |
+| UR-045 | - | DR-057 |
+| UR-046 | IR-028 | DR-058 |
+| UR-047 | IR-013 | DR-060 |
+| UR-048 | - | DR-061, DR-062, DR-142 |
+| UR-049 | IR-010 | DR-063, DR-064, DR-065, DR-147 |
+| UR-050 | - | DR-066, DR-067 |
+| UR-051 | - | DR-068, DR-069, DR-070 |
+| UR-052 | IR-027 | DR-078, DR-079, DR-080, DR-143 |
+| UR-053 | IR-029 | DR-074 |
+| UR-054 | - | DR-075, DR-076, DR-077, DR-147 |
+| UR-055 | - | DR-081, DR-082, DR-083, DR-084, DR-167, DR-168, DR-169, DR-173 |
+| UR-056 | - | DR-085 |
+| UR-057 | - | DR-086 |
+| UR-058 | - | DR-087, DR-142 |
+| UR-060 | - | DR-090, DR-091, DR-111 |
+| UR-061 | - | DR-092 |
+| UR-062 | - | DR-101, DR-102, DR-103, DR-104, DR-107 |
+| UR-063 | - | DR-105 |
+| UR-064 | - | DR-106 |
+| UR-065 | IR-030 | DR-108, DR-109, DR-110, DR-111 |
+| UR-066 | IR-031 | DR-112, DR-157, DR-187, DR-194 |
+| UR-067 | - | DR-115, DR-116, DR-117, DR-118 |
+| UR-068 | - | DR-119 |
+| UR-069 | - | DR-113, DR-114, DR-120 |
+| UR-070 | - | DR-121, DR-122 |
+| UR-071 | IR-032 | DR-123, DR-124, DR-125, DR-126, DR-127, DR-128, DR-133, DR-134, DR-135, DR-136, DR-137, DR-138, DR-170, DR-171, DR-180 |
+| UR-072 | - | DR-156 |
+| UR-073 | - | DR-158 |
+| UR-074 | - | DR-162, DR-177, DR-181 |
+| UR-075 | - | DR-174, DR-175 |
+
+---
+
+## 4. Test Traceability
+
+### Unit Tests to Software Requirements
+
+| Test ID | Test Description | Traces To | Status |
+|---------|-----------------|-----------|--------|
+| UT-001 | Player state transitions | DR-001 | Pending |
+| UT-002 | MediaItem source URL resolution | DR-002, DR-003 | Pending |
+| UT-003 | Queue next/previous navigation | DR-005 | Pending |
+| UT-004 | Queue shuffle order generation | DR-005 | Pending |
+| UT-005 | Queue repeat mode behavior | DR-005 | Pending |
+| UT-006 | Jellyfin authentication flow | IR-009 | Pending |
+| UT-007 | Jellyfin library items parsing | IR-010 | Pending |
+| UT-008 | Repository pattern online/offline switching | DR-013 | Pending |
+| UT-009 | Offline mutation queue persistence | DR-014 | Pending |
+| UT-010 | Download queue management | DR-015 | Done |
+| UT-011 | Resume position storage and retrieval | DR-022 | Pending |
+| UT-012 | Sleep timer countdown logic | DR-029 | Pending |
+| UT-013 | Playback progress reporting throttling | DR-028 | Pending |
+| UT-014 | Database open and in-memory mode | IR-013, DR-012 | Done |
+| UT-015 | Database migrations run successfully | IR-013, DR-012 | Done |
+| UT-016 | All database tables created | IR-013, DR-012 | Done |
+| UT-017 | FTS5 search table created | IR-013, DR-012 | Done |
+| UT-018 | Server CRUD operations | IR-013, DR-012 | Done |
+| UT-019 | User CRUD operations | IR-013, DR-012 | Done |
+| UT-020 | Cascade delete server removes users | IR-013, DR-012 | Done |
+| UT-021 | Item insert and FTS search | IR-013, DR-012 | Done |
+| UT-022 | User data playback position storage | IR-013, DR-012, DR-022 | Done |
+| UT-023 | Sync queue operations | IR-013, DR-014 | Done |
+| UT-024 | Downloads table operations | IR-013, DR-015 | Done |
+| UT-025 | Migrations are idempotent | IR-013, DR-012 | Done |
+| UT-026 | NullBackend volume default value | DR-004 | Done |
+| UT-027 | NullBackend set volume | DR-004 | Done |
+| UT-028 | NullBackend volume clamping (high/low) | DR-004 | Done |
+| UT-029 | NullBackend volume boundary values | DR-004 | Done |
+| UT-030 | PlayerController volume default | DR-004, DR-009 | Done |
+| UT-031 | PlayerController set volume | DR-004, DR-009 | Done |
+| UT-032 | PlayerController muted default | DR-004, DR-009 | Done |
+| UT-033 | PlayerController volume delegates to backend | DR-004, DR-009 | Done |
+| UT-034 | Download event serialization roundtrip | DR-015 | Done |
+| UT-035 | Download event completed serialization | DR-015 | Done |
+| UT-036 | Download event failed serialization | DR-015 | Done |
+| UT-037 | Download worker exponential backoff | DR-015 | Done |
+| UT-038 | Download worker error retryable check | DR-015 | Done |
+| UT-039 | Download manager creation | DR-015 | Done |
+| UT-040 | Download manager set max concurrent | DR-015 | Done |
+| UT-041 | Download info serialization | DR-015 | Done |
+| UT-042 | Download command filename sanitization | DR-015, DR-018 | Done |
+| UT-043 | Download command filename extension preservation | DR-015, DR-018 | Done |
+| UT-044 | Offline item serialization | DR-017 | Done |
+| UT-045 | Smart cache default config | DR-015 | Done |
+| UT-046 | Smart cache album affinity tracking | DR-015 | Done |
+| UT-047 | Smart cache queue precache config | DR-015 | Done |
+| UT-048 | Smart cache storage limit check | DR-015 | Done |
+| UT-049 | Playlist create (offline) | DR-019, JA-019 | Done |
+| UT-050 | Playlist delete (offline) | DR-019, JA-019 | Done |
+| UT-051 | Playlist rename (offline) | DR-019, JA-019 | Done |
+| UT-052 | Playlist get items (offline) | DR-019, JA-019 | Done |
+| UT-053 | Playlist add items (offline) | DR-019, JA-020 | Done |
+| UT-054 | Playlist remove items (offline) | DR-019, JA-020 | Done |
+| UT-055 | Playlist reorder items (offline) | DR-019, JA-020 | Done |
+| UT-056 | Playlist entry serialization | DR-019, JA-019 | Done |
+| UT-057 | Playlist Tauri command param naming (camelCase) | DR-019, JA-019, JA-020 | Done |
+| UT-058 | Playlist repository client methods | DR-019, JA-019, JA-020 | Done |
+| UT-059 | Audio-only stream URL builder for a video item (selected audio-stream index) | JA-032, DR-052 | Pending |
+| UT-060 | Background-audio handoff state machine (background→audio, foreground→video; no dual audio) | DR-052 | Pending |
+| UT-061 | Background-audio Tauri command param naming (camelCase) | DR-052 | Pending |
+| UT-062 | `setBackgroundAudioEnabled` reports whether the native bridge was actually reached (missing bridge, stale proxy, throwing method) so a dead bridge cannot look armed | UR-040, IR-025, DR-051 | Done |
+| UT-067 | Offline `get_items` gates the synced-catalog UNION on the catalog-browse flag (downloads only when off, full catalog when on) | DR-078 | Done |
+| UT-068 | Catalog visibility resolves to `serverReachable \|\| showServerCatalog`, and is pushed to the backend on every change of either input | DR-078, DR-079 | Done |
+| UT-069 | `isConnected` follows backend reachability alone: false when the server is unreachable on a live link, true for a reachable server while `navigator.onLine` is false | DR-079 | Done |
+| UT-070 | Hybrid `get_items` returns an empty offline result as-is when the catalog-browse gate is off, without querying the server | DR-080 | Done |
+| UT-066 | WiFi-only download gate: cellular and metered WiFi blocked, unmetered WiFi/Ethernet allowed, unknown/none fail closed, desktop default ungated; plus the frontend network reporter (transport reporting, change subscription, teardown, fail-open queries) | DR-074 | Done |
+| UT-071 | Byte-size formatter: zero/negative/non-finite → "0 B"; decimal unit thresholds; 2–3 significant-figure banding; trailing-zero trimming; largest-unit cap | DR-085 | Done |
+| UT-072 | Downloaded-only browse returns a downloaded leaf and its container, filtered to the requested album parent; a non-downloaded sibling is omitted | DR-082, DR-083 | Done |
+| UT-073 | An empty downloaded-only browse is authoritative — no rows, no error — regardless of the catalog-browse flag | DR-082 | Done |
+| UT-074 | Only libraries with downloaded content are listed; an empty one is omitted | DR-082 | Done |
+| UT-075 | Disk usage reports a leaf's own size, a container's summed descendants, and reconciles the device total with the sum of leaves | DR-085 | Done |
+| UT-076 | Downloaded library browse lists album containers, not their individual tracks; drilling into the album returns the tracks | DR-082, DR-083 | Done |
+| UT-077 | Downloaded TV library browse lists the series, not seasons/episodes; drilling returns the season then the episode | DR-082, DR-083 | Done |
+| UT-078 | A downloaded leaf with no cached container (e.g. a movie) still surfaces at the library level | DR-082, DR-083 | Done |
+| UT-079 | Each EQ preset returns a 10-band gain curve within range; Flat is all zeros; Bass Boost lifts lows and leaves highs flat | DR-030 | Done |
+| UT-080 | `with_equalizer_normalised` clamps out-of-range gains and forces the band vector to exactly 10 entries (pad short, truncate long) | DR-030 | Done |
+| UT-081 | Old persisted AudioSettings JSON without EQ fields loads as disabled + flat | DR-030 | Done |
+| UT-082 | EQ fields serialize as camelCase (`equalizerEnabled`/`equalizerBands`) and round-trip | DR-030 | Done |
+| UT-083 | EQ filter entries are empty when disabled or when the curve is flat (clears the `af` filter) | IR-020 | Done |
+| UT-084 | Enabled EQ builds one peaking `equalizer` per non-zero band at the right frequency and gain inside a single `lavfi` chain | IR-020 | Done |
+| UT-085 | A first tap resolves to `togglePlayPause` immediately — no deferral and no timer | DR-092, DR-098 | Done |
+| UT-086 | A second tap inside the window seeks (+30 s right half, −10 s left half) with the matching feedback side **and** re-toggles play/pause, so the two toggles cancel and the play state is unchanged by a double tap | DR-092, DR-098 | Done |
+| UT-087 | A tap after the window, and the tap following a consumed pair, are each fresh first taps that toggle (there is no third-tap case); repeated double taps keep seeking; `cancel()` makes the next tap a first tap so an interpreted swipe cannot seek | DR-092, DR-098 | Done |
+| UT-088 | `resolveSeekTarget` applies the delta to the reported position, clamps into `[0, duration - END_SEEK_MARGIN_SECONDS]`, chains off an in-flight pending target so rapid skips accumulate, and ignores that target once the player reports past it | DR-092, DR-095 | Done |
+| UT-089 | A touch drag on the video seek bar seeks to the dragged position, never toggles play/pause, and never alters brightness — the container gesture layer stays out of a control drag entirely | DR-098, DR-099 | Done |
+| UT-090 | The seek bar commits its seek on `touchend` even when the engine never fires `change`, and commits exactly once when both signals arrive | DR-099 | Done |
+| UT-091 | Transport intents (play/pause/toggle) reach the backend even while a video adapter is registered, and never call the adapter's own `play`/`pause`/`toggle` — the webview must not decide play-vs-pause from the DOM | DR-097 | Done |
+| UT-092 | `shouldReuseActivePlayback` reuses backend playback for an already-loaded audio track but never for video, and never when an explicit start position or a next-episode restart was requested | DR-100 | Done |
+| UT-093 | `resolvePlayerSurface` returns `video` only with a stream URL, `pending` for video whose stream URL is still missing (never `audio`), and `audio` for audio content | DR-100 | Done |
+| UT-094 | `parseNativeInsets` accepts the bridge's JSON or a decoded object, and coerces missing/negative/non-finite edges to 0 rather than emitting `NaNpx` (which would invalidate the whole padding declaration) | DR-112 | Done |
+| UT-095 | `safeAreaCssVars`/`applySafeAreaInsets` emit px-suffixed `jt-inset` custom properties for all four edges | DR-112 | Done |
+| UT-096 | `readNativeInsets` returns null with no bridge and survives a stale WebView proxy (missing or throwing `get`) instead of throwing out of layout init | IR-031, DR-112 | Done |
+| UT-097 | `initSafeArea` primes the document on start, re-applies on `jellytau-insets-changed` (rotation, nav-mode switch), unsubscribes on teardown, and writes nothing without a bridge so `env()` still wins on iOS/desktop | IR-031, DR-112 | Done |
+| UT-098 | `shellReservesBottomInset` gives the bottom inset to BottomUi wherever one renders and to the app shell only on routes without one, so the gesture bar is never ignored nor double-padded | DR-112 | Done |
+| UT-099 | A Jellyfin item payload carrying `UserData.IsFavorite` maps to `MediaItem.user_data.is_favorite` | DR-113, JA-034 | Done |
+| UT-100 | `OnlineRepository::get_favorites` builds `Filters=IsFavorite` + `Recursive=true` + the scope's `IncludeItemTypes`, and omits the type filter entirely for `SearchScope::All` | DR-115, JA-033 | Done |
+| UT-101 | `OfflineRepository::get_favorites` returns only `is_favorite = 1` rows, honours the scope type filter, and stays downloads-only when the catalog-browse gate is off | DR-115 | Done |
+| UT-102 | The `save_to_cache` favourite mirror does not overwrite a row with `pending_sync = 1` | DR-114 | Done |
+| UT-103 | The reconnect drain pushes pending favourites, clears `pending_sync`, and leaves failed rows pending | DR-120 | Done |
+| UT-104 | `get_items` with `favorites_only` filters online (endpoint) and offline (SQL) | DR-116 | Done |
+| UT-105 | `favorites` store precedence: override beats `userData.isFavorite` beats `false` | DR-119 | Done |
+| UT-106 | Un-favouriting removes an item from a favourites listing view | DR-117, DR-119 | Done |
+| UT-107 | The hybrid background refresh emits `favorites-changed` only for ids whose favourite state actually flipped | DR-120 | Done |
+| UT-109 | Search covers synced-but-not-downloaded items when catalog browse is on, and stays downloads-only when off | DR-108 | Done |
+| UT-110 | Search item-type filter is bound, not interpolated: a quote-bearing type neither errors nor widens results | DR-108 | Done |
+| UT-111 | FTS prefix queries quote each token, so apostrophes/hyphens/slashes are data; empty or punctuation-only input returns no rows rather than erroring | DR-108 | Done |
+| UT-112 | Repeated catalog passes leave one `items_fts` entry per item, not one per pass | DR-110 | Done |
+| UT-113 | The stale-catalog sweep removes vanished synced rows, keeps downloaded ones, keeps uncrawled types, and stays scoped to one server | DR-110 | Done |
+| UT-114 | Cached people are reachable from unscoped search and excluded from scoped search | DR-111 | Done |
+| UT-115 | Re-index staleness policy: never-indexed and unparseable timestamps are due, fresh ones are not, future ones are not | DR-109 | Done |
+| UT-116 | `resolve_local_media_path` returns a completed download's file, and `None` for an in-progress download, a row whose file has been deleted, or an unknown item | DR-123 | Done |
+| UT-118 | `resolveVideoSource` prefers a downloaded file, never marks a local file as needing transcoding, and falls back to streaming for a blank path | DR-123 | Done |
+| UT-119 | The audio-only handoff picks a downloaded file over the audio-only stream URL, preserving the Jellyfin id for progress sync | DR-128 | Done |
+| UT-120 | Expiry reclaim takes only expired temporary entries: derived from `completed_at`+TTL, honouring an `expires_at` override, never a user download, and disabled by a zero TTL | DR-127 | Done |
+| UT-108 | LRU eviction reclaims only `'auto'` downloads and never a user's own, even when the user's is the oldest | DR-126 | Done |
+| UT-117 | A background audio-only stream cut short resumes where it died instead of ending the episode; a real end still advances; the absolute position is compared against the runtime; retries at a stuck position give up. A recoverable error resumes music and video too, with growing backoff, leaving the rest of the queue intact and the seekable stream's URL untouched; local and DirectUrl sources are excluded | DR-129 | Done |
+| UT-124 | `downloadedFilePath` leaves a completed download's absolute path alone (POSIX and Windows) and only roots one that is still relative | DR-133 | Done |
+| UT-125 | A NULL `media_type` resolves from the item type — Movie and Episode as video, a track as audio — an uncached item still defaults to audio, and an explicit `media_type` overrides the item | DR-135 | Done |
+| UT-126 | Requeueing takes only video rows downloaded under the audio default, clearing their URL, and leaves correctly-typed video rows and real audio downloads alone | DR-136 | Done |
+| UT-127 | The media server bounds and confines every response: a range-less request yields one chunk rather than the whole file, no range exceeds the chunk cap, explicit/open-ended/suffix ranges resolve correctly, a range past the end is unsatisfiable rather than clamped, a malformed header falls back to the first chunk, path traversal and unrelated absolute paths are refused, a wrong or absent token is rejected, and content type comes from the extension then the magic bytes | DR-137 | Done |
+| UT-121 | An EOF reads as the last observed timestamp, not zero: live readings win while the file is loaded, a not-yet-established duration is not recorded as a real zero, a seek updates the position before the next poll, and loading a new file clears the previous one's | DR-130 | Done |
+| UT-122 | The sync-queue drain pushes queued playback reports oldest-first, defers failures for the next reconnect, abandons a row after `MAX_SYNC_ATTEMPTS`, ignores other users' rows, and parses both payload dialects | DR-131 | Done |
+| UT-123 | Pending-sync rows describe themselves: every queueable operation has a label, an unknown one still renders, the item title falls back to its id, and rows list oldest-first | DR-132 | Done |
+| UT-130 | Video and background-audio stream URLs omit `AudioStreamIndex` when no track was chosen, and carry the exact index when one was | DR-140 | Done |
+| UT-131 | The Episode Focus View hero offers a download control | DR-142 | Done |
+| UT-132 | The series name links to the series and the `SxEy` badge to that season's anchor | DR-142 | Done |
+| UT-133 | Cast renders below the "More Episodes" strip, never above it | DR-062, DR-142 | Done |
+| UT-134 | The episode strip is hidden when the episode has no siblings | DR-142 | Done |
+| UT-135 | An episode with no `seriesId` still renders the Focus View, with title, Play and download | DR-142 | Done |
+| UT-136 | `episodeRedirectTarget` sends a bare episode page into its series' Focus View, and returns null with no series | DR-142 | Done |
+| UT-137 | Going offline with the toggle off pushes the closed gate and bumps `catalogFilterVersion` | DR-143 | Done |
+| UT-138 | The version bumps only after `set_show_server_catalog` resolves, never before | DR-143 | Done |
+| UT-139 | A failed visibility push is retried on the next identical transition rather than latched | DR-143 | Done |
+| UT-140 | `useOfflineFilterReload` skips the value a page already loaded under and reloads on each later change | DR-143 | Done |
+| UT-141 | The advertised channel cap: an unknown or zero reading falls back to stereo, a real route keeps its channels, an absurd driver reading is capped at 7.1, and mono is taken at its word | DR-141 | Done |
+| UT-148 | Forcing a transcode from the client: an undecodable default track forces one, a decodable track does not, the default track decides rather than the first, the first decides when nothing is marked default, and neither an audio-less source nor an unnamed codec is second-guessed | DR-149 | Done |
+| UT-149 | `createAdapter` returns the native adapter only when Rust reports native AND `experimentalNativeVideo` is on; the flag off forces HTML5 even when Rust says native, and the flag on never promotes a platform Rust reported as HTML5 | DR-150 | Done |
+| UT-150 | `set-version.sh` stamps all four manifests without touching dependency versions, and the Android versionCode is monotonic across an upgrade sequence, clears the 1000 floor, and survives a prerelease suffix | DR-153 | Done |
+| UT-151 | An unreportable stop lands in the queue and is pushed by the existing drain; re-queueing the same item supersedes the earlier position rather than adding a row, distinct items keep their own positions, and an abandoned row is not revived by a later report | DR-154 | Done |
+| UT-152 | Caching a server result mirrors its watch position locally — including for an item carrying a position but no favourite flag — without inventing a row for an item the server reported no user data for, and without pulling a still-unsynced local position backwards | DR-155 | Done |
+| UT-162 | Each downloaded library lists only its own media: the music library shows the album and neither the film nor the series, the movie library only the film, the TV library only the series | DR-163 | Done |
+| UT-163 | `partial_path` appends rather than replacing the extension, so it matches what the cleanup paths delete, keeps two sources for one title apart, and still produces a sidecar for an extension-less target | DR-165 | Done |
+| UT-170 | `queue_album_tracks` queues a row for every track of the album — including tracks the cache holds without an `album_id` and tracks it has never seen at all — links each one to its album so offline browsing can find it, returns the row ids in track order, and is idempotent: re-queuing fills the gaps without duplicating rows or resetting a completed track. `cached_album_tracks` (the offline fallback) finds tracks by either album link and does not sweep in another album's | DR-173 | Done |
+| UT-171 | `resolve_pending_download_urls` restricted to a set of row ids resolves only those rows and leaves other pending rows untouched, and an empty id set resolves nothing rather than sweeping everything | DR-173 | Done |
+| UT-172 | `album_file_names` gives every track of an album its own file: a title repeated within the album (deluxe edition, two discs) is disambiguated by track number and item id instead of the second download overwriting the first, an unambiguous title keeps its own name, and path separators in a title are sanitised so a track cannot escape the album directory | DR-173 | Done |
+| UT-164 | `resume_offset` appends only when the server answered `206`; a `200` after a Range request restarts the file, because that body is the whole stream | DR-166 | Done |
+| UT-165 | A registered download starts unflagged, `signal` sets the flag its worker reads, signalling an unregistered id reports not-in-flight, `clear` forgets it, and re-registering drops a previous stop so a resumed download does not halt instantly | DR-164 | Done |
+| UT-166 | `original` quality re-encodes audio the webview cannot decode (E-AC-3/AC-3/DTS/TrueHD) to AAC without capping bitrate or resolution, keeps the `Static=true` direct copy for audio that plays here (AAC/MP3/Opus/Vorbis/FLAC) and for an unknown codec, leaves the explicit quality presets untouched, and picks the served track by the same default-or-first rule the streaming verdict uses | DR-171 | Done |
+| UT-155 | A seek during a background-audio handoff re-opens the stream at the requested absolute position (`StartTimeTicks`) and rebases the handoff to it, while a seek outside a handoff stays an ordinary seek and invents no base | DR-159 | Done |
+| UT-154 | `mark_unplayed` parses to `QueuedOp::MarkUnplayed` and is rejected without an item id, and a queued un-mark drains to the server as `clear_watch_history` | DR-158 | Done |
+| UT-156 | A capped step reaches the transcode URL as all four of its parts (total ceiling, the video/audio split summing to the cap, and a `MaxHeight`), the uncapped default keeps the historical 20/18 Mbps allowance and constrains no resolution, and the background-audio handoff takes the lower of the cap and its own 384 kbps | DR-162 | Done |
+| UT-157 | The quality ladder is internally consistent — video + audio equals the cap at every step, audio never consumes the budget, only `Original` is uncapped — descends in bitrate, resolution and audio share together, and round-trips through the serde token it is persisted as | DR-162 | Done |
+| UT-158 | Justified rows fill the container width exactly and never overflow it, every tile in a row shares one height, and each tile's width follows its own aspect ratio — a 16:9 tile coming out more than twice the width of a 2:3 tile at the same height | DR-174 | Done |
+| UT-159 | The awkward cases of the packing: a short last row is left at the target height rather than stretched across the container, a last row that would overflow is brought down, an extreme ratio is clamped instead of taking a row to itself, a missing or nonsensical ratio falls back to square instead of collapsing the tile, an unmeasured container renders nothing rather than 1px tiles, and every tile is placed exactly once in order | DR-174 | Done |
+| UT-160 | The default row height suits its container: it grows with the width, stays inside its bounds, and at phone width still fits two 16:9 tiles side by side | DR-174 | Done |
+| UT-161 | A collection type maps to its favourites scope (`movies`/`tvshows`/`music`), every other kind — Live TV, channels, box sets, books, unknown — maps to none rather than to `All`, and a constructed library carries the scope across the wire as `favoritesScope`, omitted entirely when it has none | DR-175 | Done |
+| UT-167 | The mosaic's composition: the cross-library favourites entry leads, each library is followed by its own category tile pointing at that category's tab, a category shared by two libraries still yields one tile, a library kind favourites do not carve up yields none, a scope the page offers no tab for is ignored, and every tile is uniquely keyed | DR-174, DR-175 | Done |
+| UT-168 | Subtitles are negotiated as sidecars, never burned in: the requested `SubtitleStreamIndex` is the explicit "none" sentinel (`-1`) rather than omitted, every text format we can render (`srt`/`subrip`/`ass`/`ssa`/`vtt`) is advertised as `External`, and the burn-in verdict is by format — text never forces it, image formats (PGSSUB, dvdsub) always do, case-insensitively. The same sentinel rides the stream URL itself, so a stream re-opened without a fresh negotiation cannot inherit a subtitle. And the verdict reaches the picker: a subtitle stream carries `supportsExternalDelivery` — set only for subtitles, `false` for a bitmap format and for one the server left unnamed — which drops the tracks the app could never draw from the menu, the `<track>` children and the native play request alike, without even fetching their URLs, while a stream carrying no verdict at all is still offered | DR-176 | Done |
+| UT-173 | Every video stream URL carries a `PlaySessionId`, each open mints a fresh one, and the open reports the session it superseded so that job can be stopped | DR-177 | Done |
+| UT-174 | A fatal HLS network error is read against the *absolute* position: mid-film — including after a quality switch, where the seek offset carries the whole resume position — it is retried rather than reported as the end of the stream, the last tenth of a known runtime is treated as the end, an unknown runtime retries, and retries stop once the budget is spent | DR-177 | Done |
+| UT-175 | A stream reload that never becomes playable is reported as a failure instead of resolving as success, so the caller can revert its selection rather than leave the UI claiming a stream that is not playing | DR-177 | Done |
+| UT-176 | A handoff's position is floored at its base: with no tick yet landed the exit position is the point the screen was locked at rather than 0, and once ticks are flowing (the base already applied natively) it is not added twice | DR-178 | Done |
+| UT-177 | Webview-rendered media's reported position and duration are the controller's, and are dropped the moment that element stops being the player — on teardown, and when a handoff takes over | DR-178 | Done |
+| UT-178 | A stop report at position 0 is withheld rather than sent (it would clear the resume point), while a real position is still reported from either rendering path — the element's on the webview path, the backend's on the native one | DR-179 | Done |
+| UT-179 | An audio-only episode that ends naturally is reported stopped at its runtime, so Jellyfin marks it played; a truncated stream, which is about to be re-opened, reports nothing | DR-179 | Done |
+| UT-180 | Position ticks report progress to the server, throttled to one report per item per window rather than one per tick | DR-179 | Done |
+| UT-181 | The handoff plan matches its source: a downloaded file takes no base and a seek, a stream takes the base and no seek, and a handoff at 0:00 takes neither; a downloaded handoff's absolute seek stays an ordinary seek instead of a stream rebuild | DR-180 | Done |
+| UT-153 | Scroll handling per navigation kind: a forward move always lands at the top even when the previous page was scrolled and even when the target was visited before, Back restores that route's own saved offset (and the top when it has none), offsets are kept per route rather than shared, a repeated Back still restores, and the initial load leaves the container alone | DR-156 | Done |
+| UT-142 | The audio codecs offered for video direct play: a Dolby device's real `MediaCodecList` output drops `ac3`/`eac3`, AMR and raw PCM are dropped too, a fully-supported list is passed through untouched, a list with nothing decodable still claims `aac`, and stray spacing or casing does not decide whether the user gets sound | DR-148 | Done |
+| UT-143 | Subtitle URLs resolve to plain strings before they reach the markup (never a Promise), unresolvable tracks are dropped, a stale selection collapses to "Off", and a server-default track is never auto-selected | UR-020, DR-023 | Done |
+| UT-144 | VideoPlayer actually renders `<track kind="subtitles">` children carrying `data-stream-index`, with no `default` attribute and no async `getSubtitleUrl()` bound to `src` | UR-020, DR-023 | Done |
+| UT-145 | The frontend's subtitle payload survives the IPC hop: a camelCase `PlayItemRequest` carrying `subtitles` deserializes, `create_media_item` lands them on `MediaItem.subtitles` in the order sent, and a request without the field still defaults to empty | UR-020, IR-016 | Done |
+| UT-146 | The subtitle JSON serialized across the JNI boundary uses the keys `JellyTauPlayer.load()` reads — `url`, `language`, `label` and `mime_type`, never `mimeType` | UR-020, IR-016, JA-008 | Done |
+| UT-147 | The native subtitle payload and the track-selection index come from the same resolved list: the wire shape keeps `mime_type` and stream order, `playerPlayItem` actually sends it, and the index is a position in the sent list (so a track whose URL failed to resolve cannot shift the others) rather than the menu's row number | UR-020, IR-016 | Done |
+| UT-182 | An HLS video URL never carries `StartTimeTicks` — with a position supplied or not — while the master playlist, codec, media source and chosen audio track still ride on it | DR-181 | Done |
+| UT-183 | A reloaded stream is resumed by seeking the element to the absolute position with the transcode offset cleared to zero — never by carrying the position as an offset base, which since DR-181 would display the position while playing the item from its start — and a reload to 0:00 waits for no seek | DR-181 | Done |
+| UT-184 | The native reveal rule fires on `state === "playing"` and on a position tick carrying a position or a duration, and on nothing else — not `buffering`, `paused`, `stopped`, `ended` or `error`, not an empty tick, and not a negative position | DR-182 | Done |
+| UT-189 | On the native path the player never calls `player_report_state` — driven through the real 10-second progress interval under fake timers, which is the call site that mattered; asserting on a freshly mounted player passes with the guard deleted and guards nothing | DR-195 | Done |
+| UT-187 | On the native path the play overlay follows the backend: it clears when the backend resumes after a pause and is raised again when the backend pauses, and the system bars are hidden on player entry rather than only by the fullscreen button | DR-186, DR-187 | Done |
+| UT-186 | Every attribute the native-video compositing block in app.css targets is set somewhere in the app — `[data-app-shell]` in particular — so a selector aimed at nothing fails the suite instead of failing silently on a device | DR-185 | Done |
+| UT-185 | Mounted on the native path (backend reports native, opt-in flag on, no `<video>` element rendered and the backend not stopped), VideoPlayer keeps the poster card up until the backend reports something, drops it on a playing state or a position tick with a duration, and keeps it up through `error` and `stopped` | DR-182 | 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 |
+| IT-013 | Background-audio handoff on Android: background/lock continues audio via native service and stops video decode; foreground resumes video at position | IR-025, UR-040 | Pending |
+| IT-016 | Offline library listing end-to-end: with the server unreachable, a library page lists only downloaded media with the toggle off, and additionally reveals greyed-out cached catalog entries with the toggle on | UR-052, DR-078, DR-079, DR-080 | Done |
+| IT-017 | A download queued from a greyed-out offline catalog entry persists and is resolved and started on reconnect | UR-052, UR-011 | Done |
+
+---
+
+## 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 | ❌ | ❌ | Not implemented (blocked on MPV) |
+| Gapless playback | ✅ | ⚠️ | Implemented, pending on-device verification |
+| Volume normalization | ✅ | ⚠️ | Implemented (LoudnessEnhancer — gain stage, approximate vs MPV's dynaudnorm), pending on-device verification |
+| Equalizer (10-band) | ✅ | ⚠️ | Implemented (resampled onto device bands), pending on-device verification |
+| Position updates | 250ms | On-demand | Inconsistent |
+
+**Status** (see docs/specs/android-audio-settings-parity.md):
+1. ✅ `set_audio_settings()` implemented in `ExoPlayerBackend` (JSON over JNI)
+2. ✅ Gapless via ExoPlayer's `pauseAtEndOfMediaItems`
+3. ✅ Volume normalization via `LoudnessEnhancer`
+4. ✅ Equalizer via `android.media.audiofx.Equalizer`, canonical 10 bands
+   resampled onto the device's band centres
+5. ⬜ **Not yet verified on a physical device** — the EQ/normalization effects
+   depend on device-specific `AudioEffect` availability and band layouts
+6. ⬜ Flip the trait's `set_audio_settings` default from `Ok(())` to
+   `Err(not_implemented())` so a backend that omits it fails loudly instead of
+   silently reporting success. Deferred until (5) confirms the Android path works
+7. ⬜ Standardize position update frequency across platforms
+
+Crossfade is deliberately absent: it is unimplemented on every platform and
+architecturally blocked on MPV, so building it on Android alone would invert the
+parity gap. (The previously suggested `ConcatenatingMediaSource` is also
+deprecated in current Media3.)
+
+**Impact**:
+- Medium - Android users lack audio enhancement features advertised in requirements
+- User experience differs between platforms
+- UR-032 (Gapless), UR-033 (Normalization) and UR-027 (Equalizer) are now
+  implemented on Android as well as Linux, pending on-device verification
+- UR-031 (Crossfade) works nowhere — see DR-034
+
+**Traces To**: IR-004, UR-031, UR-032, UR-033, DR-034, DR-035, DR-036
+
+---
+
+### Frontend Playback Code Duplication
+
+**Issue**: Playback control handlers and state derivations are duplicated between `AudioPlayer.svelte` and `MiniPlayer.svelte`.
+
+**Symptoms**:
+- Identical try-catch wrapped handler functions in both components (~44 lines duplicated)
+- Same `$derived` state merging logic for local/remote playback in both components
+- Position conversion (ticks ↔ seconds) scattered across multiple files
+
+**Affected Files**:
+- [src/lib/components/player/AudioPlayer.svelte](../src/lib/components/player/AudioPlayer.svelte) - Duplicate handlers
+- [src/lib/components/player/MiniPlayer.svelte](../src/lib/components/player/MiniPlayer.svelte) - Duplicate handlers
+- [src/lib/services/playbackControl.ts](../src/lib/services/playbackControl.ts) - Position conversion
+- [src/lib/stores/playbackMode.ts](../src/lib/stores/playbackMode.ts) - Position conversion
+- [src/lib/services/playbackReporting.ts](../src/lib/services/playbackReporting.ts) - Position conversion
+
+**Duplicated Code**:
+```typescript
+// These handlers are identical in both AudioPlayer and MiniPlayer:
+handlePlayPause(), handleNext(), handlePrevious(),
+handleToggleShuffle(), handleCycleRepeat(), handleVolumeChange()
+
+// These derived states use identical logic:
+displayMedia, displayIsPlaying, displayPosition, displayDuration
+```
+
+**Future Fix**:
+1. Create `src/lib/utils/playbackUnits.ts`:
+   ```typescript
+   export const TICKS_PER_SECOND = 10_000_000;
+   export const secondsToTicks = (s: number) => Math.floor(s * TICKS_PER_SECOND);
+   export const ticksToSeconds = (t: number) => t / TICKS_PER_SECOND;
+   ```
+
+2. Create `src/lib/composables/useMergedPlaybackState.svelte.ts`:
+   - Export `displayMedia`, `displayIsPlaying`, `displayPosition`, `displayDuration`
+   - Single source of truth for merged local/remote state
+
+3. Simplify handler wrappers using a utility:
+   ```typescript
+   export const withErrorHandler = (fn: () => Promise<void>, context: string) =>
+     async () => { try { await fn(); } catch (e) { console.error(`${context}:`, e); } };
+   ```
+
+**Impact**:
+- Low - Code works correctly but violates DRY principle
+- Maintenance burden when logic needs to change
+- Risk of handlers diverging over time
+
+**Traces To**: DR-009

docs/specs/SPEC-REVIEW-CHECKLIST.md

@@ -0,0 +1,68 @@
+# Spec review checklist
+
+Run a spec past this before accepting it. It exists because JellyTau's
+backend/frontend boundary is a **stated rule with, historically, no gate** — the
+rule lived in the architecture docs, but nothing forced a spec author to check a
+new design against it, and a "minimal-change" spec quietly leaked domain
+taxonomy into the frontend (see [scoped-search-boundary.md](scoped-search-boundary.md)).
+This checklist is the human gate. The CI check
+(`scripts/check-frontend-boundary.sh`) is only a crude tripwire for one leak
+signature — it does **not** replace this.
+
+Copy the boxes into the review comment (or the PR) and tick them.
+
+## Boundary (the one that bites)
+
+- [ ] **The spec has a filled-in "Layer assignment" table**, and it assigns
+      *logic*, not files. A spec without this section is not ready to review.
+- [ ] **No domain vocabulary is placed in the frontend.** In particular: Jellyfin
+      item-type sets that define a *category* (what "Music"/"TV"/"Movies" means),
+      query-shaping rules, business rules, reachability/sync policy. If the
+      frontend names a *set* of item types to define a category, that is a leak —
+      it belongs behind an opaque enum the backend expands.
+- [ ] **"The backend already accepts this parameter" was not used as the reason**
+      to place the deciding logic in the frontend. Accepting a parameter ≠ owning
+      the decision of its value.
+- [ ] **The `Scope:` / effort framing is not optimizing for "least backend
+      change."** "Frontend only, no Rust changes" is a description, never a goal.
+      The goal is *correct layer placement*; sometimes that is more Rust work.
+- [ ] Ran the litmus test on each borderline responsibility: *would it change if
+      Jellyfin's API changed?* → Rust. *Only if the UI were redesigned?* →
+      frontend. Borderline defaults to Rust.
+- [ ] Single-type presentation (`itemType: "Movie"`, "this page shows albums")
+      is **not** over-corrected into the backend. The rule targets category
+      *taxonomy*, not every mention of a type. Don't invent a backend enum per
+      list page.
+
+## IPC contract
+
+- [ ] Anything crossing the boundary has its wire shape specified.
+- [ ] camelCase rule accounted for: top-level params auto-convert; nested structs
+      get `#[serde(rename_all = "camelCase")]`; tagged unions match tags on both
+      sides; events are kebab-case. (CLAUDE.md §IPC,
+      [04-type-sync-and-threading.md](../architecture/04-type-sync-and-threading.md).)
+- [ ] Any result that arrives *twice* (command return **and** a later event —
+      e.g. the search cache/server merge) has **both** payloads in the new shape.
+- [ ] `bindings.ts` is regenerated from Rust, not hand-edited.
+
+## Requirements & traceability
+
+- [ ] Linked to existing URs, or new URs/DRs are allocated in
+      [requirements.md](../requirements.md).
+- [ ] Requirement-implementing code will carry `// TRACES:` comments (CLAUDE.md).
+- [ ] Traceability coverage stays ≥ 50% (the CI gate).
+
+## Conflicts & hygiene
+
+- [ ] If this spec revises/supersedes another, the older spec gets a banner
+      pointing here — no two specs silently contradicting.
+- [ ] Acceptance criteria include the standard gates: `bun run check`,
+      `bun run test`, `bun run check:boundary`, and (if Rust changed)
+      `cargo fmt`/`cargo clippy`/`bun run test:rust`.
+- [ ] Notes flag that a parallel Claude session may be active in the repo.
+
+---
+
+**If any Boundary box can't be ticked, the spec is not ready** — fix the layer
+assignment first. Every other section can be negotiated; that one is the whole
+reason this file exists.

docs/specs/SPEC-TEMPLATE.md

@@ -0,0 +1,105 @@
+# Spec: <feature name>
+
+<!--
+  Copy this file to docs/specs/<kebab-name>.md and fill it in. Delete the HTML
+  comments as you go. The section that matters most for this project is
+  "Layer assignment" — read its comment before writing it.
+
+  Before merging a spec, run it past docs/specs/SPEC-REVIEW-CHECKLIST.md.
+-->
+
+**Status:** Proposed <!-- Proposed | Accepted | Implemented | Superseded -->
+**Requirements:** <!-- UR-xxx → DR-yyy; allocate new DRs in requirements.md. -->
+**UX spec:** <!-- link to the relevant ux-flows.md section, or "n/a". -->
+**Supersedes / revises:** <!-- link any spec this changes, or delete this line. -->
+
+## Summary
+
+<!-- 2–4 sentences. What changes for the user, in plain terms. -->
+
+## Motivation
+
+<!-- Why now. The problem being solved. -->
+
+## Layer assignment
+
+<!--
+  🔴 THIS IS THE SECTION THAT KEEPS THE ARCHITECTURE HONEST. Do not skip it, and
+  do NOT reframe it as "how little backend work can we get away with."
+
+  The project rule (CLAUDE.md, architecture/02-svelte-frontend.md): the Rust
+  backend owns ALL business logic — auth, catalog, sessions, downloads, offline,
+  playback, AND domain vocabulary (e.g. what Jellyfin item types the category
+  "Music" means). The Svelte frontend is PRESENTATION ONLY: rendering, layout,
+  navigation, view/order preferences, input handling.
+
+  For each distinct piece of *logic* this feature introduces, put it in the table
+  and name the layer it belongs to and WHY. "It's less work in the frontend" and
+  "the backend already accepts this parameter" are NOT reasons to place logic in
+  the frontend — the backend accepting a parameter does not make deciding that
+  parameter's value a presentation concern.
+
+  Litmus test for "does this belong in Rust?": Would this logic have to change if
+  Jellyfin changed its API, added an item type, or altered a business rule? If
+  yes, it is domain logic → Rust. Would it change if we redesigned the UI? If
+  yes (and only yes), it is presentation → frontend.
+
+  A past incident: scoped-search.md placed the item-type taxonomy (what "Music"
+  means as a set of Jellyfin types) in the frontend because the backend already
+  accepted an includeItemTypes filter. That was a boundary leak; see
+  scoped-search-boundary.md. This section exists to catch that class of mistake
+  at spec time, not in review three features later.
+-->
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| <!-- e.g. scope → item-types --> | Rust | <!-- domain vocabulary; changes with Jellyfin's API --> |
+| <!-- e.g. group display order --> | Frontend | <!-- pure presentation; changes only if UI is redesigned --> |
+
+<!--
+  If a row is genuinely borderline, say so and give the tie-breaker you used.
+  Borderline defaults to Rust for anything touching domain data or vocabulary.
+-->
+
+## Design
+
+<!--
+  How it works. Wire shapes for anything crossing the IPC boundary. Remember:
+  - Command NAME must match the Rust fn name exactly.
+  - Top-level params auto-convert snake_case → camelCase (Tauri v2).
+  - Nested struct fields need #[serde(rename_all = "camelCase")].
+  - Events are kebab-case.
+  (See CLAUDE.md §IPC and architecture/04-type-sync-and-threading.md.)
+
+  Regenerate bindings.ts from Rust types; never hand-edit it.
+-->
+
+## Out of scope
+
+<!-- What this spec deliberately does NOT do. -->
+
+## Acceptance criteria
+
+<!-- Checkable statements. Include the standard gates: -->
+
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes (if Rust changed).
+- [ ] `bun run check:boundary` passes (no taxonomy leak into the frontend).
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated if Rust types changed.
+
+## Testing
+
+<!-- Rust: cargo test. Frontend: vitest, src/lib/**/*.test.ts. What to cover. -->
+
+## TRACES
+
+<!-- Suggested tags per new/changed piece: UR-xxx | DR-yyy | tests. -->
+
+## Notes for the implementer
+
+<!--
+  - A parallel Claude session may be active in this repo — `git diff` before
+    "repairing" unexpected changes (see project memory / CLAUDE.md gotchas).
+  - Anything else non-obvious.
+-->

docs/specs/account-menu.md

@@ -0,0 +1,164 @@
+# Spec: Account menu and global chrome availability
+
+**Status:** Implemented
+**Scope:** Frontend only. No Rust changes required.
+**Requirements:** UR-054 → DR-075, DR-076, DR-077 (see
+[requirements.md](../requirements.md)).
+**UX spec:** [ux-flows.md §1.2–1.4](../ux-flows.md).
+
+## Summary
+
+Account actions — Settings, Downloads, Display preferences, Sign out — are
+currently reachable **only from `/library/*`**. Move them into a single shared
+account menu anchored to the user's name, and make that menu available on every
+authenticated non-immersive screen.
+
+## Motivation
+
+A user sitting on the home screen cannot open Settings or sign out. The bottom
+nav offers Home / Search / Library only, and the header that hosts those actions
+belongs to the library layout. The user has to guess that account actions live
+*inside* Library — an unrelated section — and navigate there first.
+
+Desktop and mobile also disagree today: desktop shows an unlabeled logout icon
+with no grouped menu, mobile shows a three-dot overflow with labelled items. The
+same two actions are found two different ways.
+
+## Background: verified current state
+
+1. **The header is not global.** It is defined in
+   [library/+layout.svelte](../../src/routes/library/+layout.svelte). The root
+   layout [+layout.svelte](../../src/routes/+layout.svelte) renders no header at
+   all.
+
+2. **`routeOwnsLayout`** in
+   [layoutShell.ts](../../src/lib/utils/layoutShell.ts) returns true for
+   `/library`, `/player/`, `/login` — those routes own their own full-height
+   flex column. Everything else renders into the root scroller with the root's
+   `BottomUi` below it.
+
+3. **Bottom nav is Home / Search / Library only**
+   ([BottomNav.svelte](../../src/lib/components/BottomNav.svelte)) — no Settings
+   or account entry.
+
+4. **Net effect:** on `/`, `/search`, and `/downloads` there is no route to
+   Settings or Sign out.
+
+5. **Desktop username is inert text** — a `<span>` next to the icons, not a
+   trigger.
+
+6. **The mobile overflow menu already has the right contents** (Downloads,
+   Settings, divider, Sign out) and the right dismissal behaviour (backdrop
+   click, keyboard handler). **Extract and reuse it rather than rewriting it.**
+
+7. **`viewMode` is already a persisted store** in
+   [library.ts](../../src/lib/stores/library.ts) (`jellytau-view-mode`,
+   `localStorage`). The Display setting is a second view onto it — **no new
+   state, no migration.**
+
+## Design
+
+### `AccountMenu` component (DR-075)
+
+One component used by both breakpoints. Contents in fixed order:
+
+```
+Signed in as <name>        ← identity block, not interactive
+<server host>
+────────────────────────
+Downloads
+Settings
+Display                    ← grid/list preference
+────────────────────────
+Sign out                   ← destructive, last, after a divider
+```
+
+- **Trigger is the username/avatar**, not a bare three-dot icon. On mobile where
+  horizontal space is tight, the avatar (or initial) alone is acceptable; the
+  name shows inside the open menu regardless.
+- **Same items, same order, both platforms.**
+- Preserve the existing dismissal behaviour: click-outside backdrop, `Escape`,
+  and focus return to the trigger on close.
+- Menu items are real links/buttons — keyboard reachable, correct roles,
+  `aria-expanded` on the trigger.
+
+"Display" may either navigate to the Settings Display section or expose the
+grid/list choice inline. Prefer navigating — it keeps one source of truth for
+preferences and avoids a nested control inside a dropdown.
+
+### Global chrome (DR-076)
+
+Make the header — and therefore the account menu — available on `/`, `/search`,
+and `/downloads`.
+
+The cleanest route is to lift the header out of the library layout into a shared
+component rendered by the root layout, with the library layout consuming the
+same component rather than defining its own. **Do not duplicate the markup into
+each route.**
+
+Constraints that must survive the change:
+
+- `/player/*` and `/login` stay chrome-free.
+- `/settings` already owns its layout; it needs no account menu (the user is
+  already there), but must not double up on chrome.
+- The root layout's flex/scroller structure is deliberate — the comments in
+  [layoutShell.ts](../../src/lib/utils/layoutShell.ts) and
+  [+layout.svelte](../../src/routes/+layout.svelte) explain why routes own their
+  own column. Preserve the scroll containment; a regression here reintroduces
+  the "last row hidden behind the nav" bug called out in those comments.
+- Mini-player and bottom-nav visibility rules (`showGlobalMiniPlayer`,
+  `showBottomNav`) must be unchanged.
+
+### Display section in Settings (DR-077)
+
+Add a Display section to [settings/+page.svelte](../../src/routes/settings/+page.svelte)
+with the grid/list control bound to the existing `viewMode` store via
+`library.setViewMode(...)`. The page-header toggle in `LibraryGrid` stays — both
+controls drive the same store, so they stay in sync for free.
+
+## Out of scope
+
+- Redesigning the Settings page or reorganising its existing sections.
+- Multi-server / account switching (UR-047) — the identity block displays the
+  active server but offers no switcher.
+- Changing the bottom nav's three destinations.
+
+## Acceptance criteria
+
+- [ ] Settings and Sign out are reachable from `/`, `/search`, and `/downloads`
+      without first navigating into Library.
+- [ ] Desktop and mobile show the same account menu items in the same order.
+- [ ] The username/avatar opens the menu; it is a real button with
+      `aria-expanded`.
+- [ ] Sign out is last, after a divider, and still logs out + resets library
+      state + redirects as it does today.
+- [ ] `/player/*` and `/login` remain chrome-free.
+- [ ] Settings has a Display section that changes grid/list, and the change is
+      immediately reflected by the library page-header toggle (same store).
+- [ ] No regression in scroll containment, mini-player visibility, or bottom-nav
+      visibility on any route.
+- [ ] `bun run check` and `bun run test` pass.
+
+## Testing
+
+- Extend the existing `layoutShell` tests: chrome-visibility for `/`, `/search`,
+  `/downloads` (now true) and `/player/*`, `/login` (still false).
+- `AccountMenu`: renders the documented items in order; trigger toggles
+  `aria-expanded`; `Escape` and backdrop click close it; Sign out invokes the
+  logout handler.
+- Display setting: writes through to the `viewMode` store and persists.
+
+New requirement-implementing code needs `TRACES:` comments — see
+[CLAUDE.md](../../CLAUDE.md). Suggested: `AccountMenu` → `UR-054 | DR-075`,
+shell/header changes → `UR-054 | DR-076`, Settings Display section →
+`UR-054, UR-029 | DR-077`.
+
+## Notes for the implementer
+
+- Read [ux-flows.md §1.2–1.4](../ux-flows.md) first — behavioural spec; this is
+  the implementation plan.
+- The layout shell is subtle and the existing comments record real bugs that
+  were fixed there. Read them before restructuring.
+- Another session may be active in this repo, including in
+  `src/routes/settings/+page.svelte`. Check `git diff` before "repairing"
+  unexpected changes, and expect to coordinate on that file.

docs/specs/android-audio-settings-parity.md

@@ -0,0 +1,209 @@
+# Spec: Android audio settings parity (EQ, normalization, gapless)
+
+**Status:** Proposed
+**Requirements:** UR-031, UR-032, UR-033, UR-027 → DR-034, DR-035, DR-036, DR-030; IR-004
+**UX spec:** n/a — no UI change; Settings › Audio already renders these controls
+**Supersedes / revises:** closes the audio half of the parity gap recorded in [playback-backend-unification.md](playback-backend-unification.md)
+
+## Summary
+
+Implement `set_audio_settings` / `audio_settings` on `ExoPlayerBackend` so the
+equalizer, volume normalization, and gapless playback settings actually take
+effect on Android. Today the Settings › Audio panel renders these controls on
+Android and they silently do nothing — `ExoPlayerBackend` is the only backend
+that does not override the trait's no-op defaults.
+
+Crossfade is explicitly **not** included; see Out of scope.
+
+## Motivation
+
+`PlayerBackend` declares `set_audio_settings` with a default `Ok(())` body.
+`MpvBackend`, `NullBackend`, and `WebviewAudioBackend` all override it;
+`ExoPlayerBackend` does not. The settings are persisted, pushed to the backend on
+every track load, and displayed in the UI — and then dropped on the floor.
+
+This is the single most user-visible platform divergence in the app: a user who
+sets a "Rock" EQ preset on Android sees the sliders move and hears no change.
+
+The backend-unification investigation ruled out fixing this by swapping engines
+(video cannot be unified; see the sibling spec), so the fix is to implement the
+trait methods where they are missing.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Band count, centre frequencies, gain range, preset→curve map | Rust (existing) | Already domain-owned in `settings.rs` per [audio-equalizer.md](audio-equalizer.md). Android must consume the same `AudioSettings`, not define its own bands. Duplicating the band layout in Kotlin would be a taxonomy leak of exactly the kind `check:boundary` guards against. |
+| Mapping `AudioSettings` → Android audio-effect parameters | Rust → JNI boundary | Platform playback detail, the direct analogue of `build_af_filter` in `mpv_backend.rs`. Belongs with the other `set_audio_settings` code. |
+| Attaching/detaching `Equalizer` and `LoudnessEnhancer` to the ExoPlayer audio session | Kotlin (`JellyTauPlayer.kt`) | Android platform API mechanics; needs the live `audioSessionId`, which only the Kotlin layer holds. |
+| Normalization preset (Loud/Normal/Quiet) → target gain | Rust (existing) | `VolumeLevel` is domain vocabulary; the same preset must mean the same loudness on every platform. |
+| Rendering sliders / preset chips | Frontend (existing) | Pure presentation; unchanged by this spec. |
+
+Borderline row: attaching the effects could arguably be driven entirely from
+Rust via JNI property calls. It goes to Kotlin because `AudioEffect` construction
+requires the audio session id and must be re-attached when ExoPlayer rebuilds its
+audio sink — lifecycle state that lives in `JellyTauPlayer.kt`. Rust still owns
+*what* the values are; Kotlin owns *when* the effect objects exist.
+
+## Design
+
+### Rust — `ExoPlayerBackend` (`src-tauri/src/player/android/mod.rs`)
+
+Override the two defaulted methods, mirroring the shape of the existing
+`set_audio_track` JNI call:
+
+```rust
+fn set_audio_settings(&mut self, settings: &AudioSettings) -> Result<(), PlayerError> {
+    let s = settings.clone().with_crossfade_clamped().with_equalizer_normalised();
+    // Serialize as JSON — the same pattern load() already uses for subtitles,
+    // avoiding a 6-arg JNI signature that has to change every time a field lands.
+    let json = serde_json::to_string(&s).map_err(|e| PlayerError { message: e.to_string() })?;
+    // Kotlin: fun setAudioSettings(json: String)
+    self.call_player_method_string("setAudioSettings", &json)?;
+    self.shared_state.lock_safe().audio_settings = s;
+    Ok(())
+}
+
+fn audio_settings(&self) -> AudioSettings {
+    self.shared_state.lock_safe().audio_settings.clone()
+}
+```
+
+`ExoPlayerState` gains an `audio_settings: AudioSettings` field. Note
+`ExoPlayerBackend` currently holds no such state — `position`/`state`/`volume` are
+all pushed in by JNI callbacks — so this is the first *pull*-side field. That is
+correct: audio settings are commanded downward, never reported upward.
+
+### Kotlin — `JellyTauPlayer.kt`
+
+```kotlin
+fun setAudioSettings(json: String) {
+    val s = JSONObject(json)
+    applyEqualizer(s.getBoolean("equalizerEnabled"), s.getJSONArray("equalizerBands"))
+    applyNormalization(s.getBoolean("normalizeVolume"), s.getString("volumeLevel"))
+    exoPlayer.pauseAtEndOfMediaItems = !s.getBoolean("gaplessPlayback")
+}
+```
+
+Three independent mechanisms:
+
+- **Gapless** — nearly free. ExoPlayer is gapless by default for compatible
+  formats; honouring the setting means *disabling* it when the user turns it off,
+  via `pauseAtEndOfMediaItems`. Note this only applies within a loaded playlist;
+  our queue loads one item at a time, so verify behaviour before claiming DR-035
+  on Android (see Testing).
+- **Equalizer** — `android.media.audiofx.Equalizer` bound to
+  `exoPlayer.audioSessionId`. Android's EQ exposes a device-dependent band count
+  (commonly 5) at fixed centre frequencies, which will **not** match our 10-band
+  ISO layout. Rust owns the canonical 10 bands; Kotlin resamples them onto the
+  device's bands by nearest-centre-frequency interpolation. Gains are in
+  millibels (`setBandLevel` takes mB, we store dB → ×100), clamped to the
+  device's reported `getBandLevelRange()`.
+- **Normalization** — `android.media.audiofx.LoudnessEnhancer`, also bound to the
+  audio session, `setTargetGain(mB)` derived from `VolumeLevel`. This is a gain
+  booster, not a true EBU R128 normalizer like MPV's `dynaudnorm`; parity is
+  approximate and should be documented as such rather than overclaimed.
+
+Lifecycle: build the effects lazily on first use, release them in `release()`,
+and re-attach on `onAudioSessionIdChanged` — ExoPlayer can rebuild its audio sink
+(e.g. on a format change), which invalidates effects bound to the old session.
+
+### Make the silent-failure mode impossible
+
+The trait's default is the root cause of this whole class of bug:
+
+```rust
+// backend.rs:85 — reports success while doing nothing
+fn set_audio_settings(&mut self, _settings: &AudioSettings) -> Result<(), PlayerError> {
+    Ok(())
+}
+```
+
+Android inherits this, so every EQ/normalization change on Android returns `Ok`
+and silently does nothing — the UI ships and has no effect, with no error anywhere.
+
+Once `ExoPlayerBackend` implements the methods, **change the trait default to
+`Err(PlayerError::not_implemented())`**, matching how `set_audio_track` /
+`set_subtitle_track` already behave. Any future backend that forgets to implement
+audio settings then fails loudly instead of lying.
+
+Check the call sites before flipping it: `NullBackend` overrides both methods, so
+the graceful-degradation path is unaffected, but confirm nothing treats a
+`set_audio_settings` error as fatal to playback.
+
+### Re-application on track load
+
+`PlayerController` already re-pushes `AudioSettings` per track on the platforms
+that implement it; the Android path inherits that for free once the trait methods
+exist. No controller change.
+
+### 🔴 Threading note
+
+`setAudioSettings` is invoked from Rust on whatever thread the command lands on.
+`AudioEffect` construction must not happen on the ExoPlayer application thread
+from inside a player callback — that is the re-entrancy hazard CLAUDE.md warns
+about, and the same shape as the `AutoplayDecision` deadlock. Post the work to
+the player's handler rather than doing it inline in a listener.
+
+## Out of scope
+
+- **Crossfade (UR-031 / DR-034).** Not implemented on *any* platform today, and
+  architecturally blocked on MPV (single-stream audio chain; `acrossfade` needs
+  two inputs). Implementing it on Android alone would invert the parity gap. It
+  needs its own spec and probably two player instances.
+- True EBU R128 normalization. `LoudnessEnhancer` is a gain stage; matching
+  `dynaudnorm` exactly is out of reach without a custom `AudioProcessor`.
+- Windows audio settings — see [windows-native-audio-backend.md](windows-native-audio-backend.md).
+
+## Acceptance criteria
+
+- [ ] `ExoPlayerBackend` overrides `set_audio_settings` and `audio_settings`.
+- [ ] EQ preset change on Android audibly changes playback; setting persists across track changes and app restart.
+- [ ] Normalization toggle audibly changes level; the three presets are ordered Loud > Normal > Quiet.
+- [ ] Disabling gapless produces a gap between consecutive tracks; enabling it does not.
+- [ ] Effects are released on `release()` and survive an audio-session rebuild.
+- [ ] `requirements.md` parity matrix updated: EQ and normalization ✅ Android.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated if Rust types changed.
+
+## Testing
+
+**Rust** (`cargo test`): `set_audio_settings` stores the sanitized settings and
+`audio_settings()` returns them — assert clamping/normalisation is applied
+(crossfade clamped to 12s, band vector normalised to `EQ_BANDS.len()`). The JNI
+call itself is not unit-testable; extract the JSON serialization into a pure
+function and test that its shape matches what the Kotlin parser expects. That
+serialization contract is the part most likely to silently break.
+
+**Kotlin**: the band-resampling function (10 canonical bands → N device bands) is
+pure arithmetic — extract it and unit-test it, including the degenerate cases of
+a 5-band device and a device reporting 10 bands.
+
+**Manual, on device** (these are the ones that actually prove it):
+1. Set Bass Boost, play a track, confirm audible change.
+2. Toggle normalization mid-track; confirm level change without a playback stall.
+3. Queue two gapless-encoded tracks, toggle the setting, confirm the gap appears/disappears.
+4. Force a format change (44.1kHz → 48kHz track) and confirm the EQ still applies afterwards — this exercises the session-rebuild re-attach.
+
+## TRACES
+
+- `ExoPlayerBackend::set_audio_settings` → `// TRACES: UR-027, UR-032, UR-033 | DR-030, DR-035, DR-036`
+- Kotlin `setAudioSettings` / `applyEqualizer` / `applyNormalization` → same IDs
+- Band-resampling helper + its tests → `DR-030 | UT-xxx`
+
+## Notes for the implementer
+
+- Read [audio-equalizer.md](audio-equalizer.md) first — it defines the canonical
+  band layout and the preset→curve rule this spec consumes. Do not redefine bands
+  in Kotlin.
+- Android source edits go in `src-tauri/android/src` (canonical tree), then run
+  `scripts/sync-android-sources.sh`. Never edit the `gen/` tree.
+- There is a **stale duplicate** `JellyTauPlayer.kt` (285 lines) at
+  `src-tauri/android/app/src/main/java/com/dtourolle/jellytau/player/` alongside
+  the real 1103-line file at `src-tauri/android/src/main/java/...`. Edit the
+  latter. Consider deleting the former as a separate change.
+- A parallel Claude session may be active — `git diff` before "repairing"
+  unexpected changes.

docs/specs/android-native-video-spike.md

@@ -0,0 +1,306 @@
+# Spec: Android native video — transparent-webview spike
+
+**Status:** Spike succeeded (2026-08-11); shipped behind `experimentalNativeVideo`,
+default off. Flipping that default shipped **audio with no picture** and was
+reverted (DR-172). Three defects behind that have since been fixed — DR-182
+(nothing on the native path could lift the poster overlay), DR-183 (the JS
+bridges raced the page load), DR-184 (the SurfaceView was never detached).
+Branch `fix/android-native-video-visible`. **The default stays off until the
+device criteria below are green.**
+
+**The spike's central question is answered: yes.** A `SurfaceView` *can* be
+composited behind a transparent Tauri WebView on Android. Nothing upstream
+blocked it and nothing upstream demonstrated it — this is, as far as the issue
+trackers show, the first working instance. The remaining flag is about test
+coverage and the unverified cases below, not about viability.
+**Requirements:** IR-004, UR-003, UR-004, UR-041 → DR-001, DR-004, DR-150, DR-151, DR-152
+**Note:** the original draft cited DR-023/DR-024 here. Those are the *subtitle*
+and *audio-track selection UI* requirements — unrelated to this work. The IDs
+actually implemented are DR-150 (native rendering behind the flag), DR-151 (the
+severed SurfaceView attach chain) and DR-152 (capabilities reported by Rust).
+**UX spec:** n/a — no intended visual change; the video surface must land exactly where the `<video>` element is today
+**Supersedes / revises:** acts on finding 2 of [playback-backend-unification.md](playback-backend-unification.md)
+
+## Summary
+
+Test whether ExoPlayer's existing `SurfaceView` video path can be composited
+behind a transparent Tauri WebView on Android. If it works, Android regains
+hardware video decoding (MediaCodec) and libass-quality ASS/SSA subtitles, both
+of which the current webview path lacks. If it does not, we document why and
+delete the dead code.
+
+This is a **spike**, not a feature commitment. The deliverable is a yes/no answer
+with evidence, plus either a working path behind a flag or a removal.
+
+## Motivation
+
+`createAdapter()` hardcodes `const effectiveKind = "html5"` and does
+`void backendKind`, discarding the `use_html5_element` value Rust computes in
+`get_player_status`. As a result:
+
+- `NativePlayerAdapter` is dead code.
+- `JellyTauPlayer.kt`'s `getOrCreateSurfaceView()` — which already calls
+  `setZOrderMediaOverlay(false)` and wires `setVideoSurfaceHolder` — is
+  unreachable.
+- Android video decodes in the WebView instead of via MediaCodec, despite
+  `CodecDetector.kt` going to the trouble of reporting hardware codec
+  capabilities back to Rust for DeviceProfile generation.
+
+The code comment in `nativeAdapter.ts:11-14` justifies this by citing
+tauri#10152 as an upstream blocker. **That justification is stale.**
+
+### Why the blocker no longer holds
+
+- tauri#10152 is open but **dead since 2024-07-01**, and it is a *feature
+  request* ("Support transparent webviews on mobile"), not a bug report about
+  compositing.
+- The capability shipped in tauri commit `27d01834` (2024-09-02) — a clippy
+  cleanup that moved `transparent()` out of the desktop-gated impl block, fencing
+  only the tao call behind `#[cfg(desktop)]`. Because it landed as unrelated
+  cleanup, nobody closed the issue.
+- The black/white-screen reports (tauri#8381, tauri#9408) were a real but
+  *different* bug: a broken JNI signature for `setBackgroundColor`, fixed in
+  **wry 0.39.4** (PR #1237). We ship wry 0.55.x.
+- Current wry calls `setBackgroundColor(0)` unconditionally on Android when
+  transparency is requested.
+
+### The honest caveat
+
+**Nobody has demonstrated SurfaceView-behind-WebView on Tauri Android.** A search
+of both `tauri-apps/tauri` and `tauri-apps/wry` issues for `surfaceview` returns
+zero results, and the one native-video Tauri plugin
+(`YeonV/tauri-plugin-videoplayer`) sidesteps compositing by launching a separate
+fullscreen Activity. Nothing upstream blocks this; nothing upstream proves it.
+Hence: spike, not feature.
+
+Note this is the *Android* question only. The equivalent Linux compositing
+problem is maintainer-declared unfixable and is **not** in scope — see the
+unification spec.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Which video backend this platform uses | Rust (existing) | `get_player_status` already computes `use_html5_element`. The frontend must *consume* it, not decide it. Restoring that is the point of the spike. |
+| Surface creation, z-ordering, `setVideoSurfaceHolder` lifecycle | Kotlin | Android platform mechanics; already written in `JellyTauPlayer.kt`. |
+| Seek/audio-track *strategy* | Rust (existing) | Already returned by `player_seek_video` / `player_switch_audio_track`; `NativePlayerAdapter` executes the chosen primitive. Unchanged — this is exactly what the `PlayerAdapter` contract was built for. |
+| Positioning the surface under the video viewport | Frontend | Pure presentation/layout. **This is the risk area** — see Design. |
+
+## Design
+
+### Phase 1 — prove compositing (no app changes)
+
+Before touching the adapter factory, verify the primitive works at all:
+
+1. Set `"transparent": true` in `tauri.conf.json` for the Android build, plus
+   `html, body { background: transparent; }`.
+2. Confirm the WebView is genuinely transparent (a native view behind it is
+   visible) and that the app does not regress to a black/white screen.
+
+If this fails, stop — everything downstream is moot, and the finding is that
+Tauri Android transparency is still broken in practice despite the shipped fix.
+
+### Phase 2 — un-hardcode the factory
+
+```ts
+// src/lib/player/adapters/index.ts
+export function createAdapter({ backendKind, host, bridge }: CreateAdapterArgs): PlayerAdapter {
+  return backendKind === "native"
+    ? new NativePlayerAdapter(host)
+    : new Html5PlayerAdapter(host, bridge);
+}
+```
+
+`backendKind` comes from `get_player_status` (`VideoBackend::Native` on Android).
+Gate behind a setting — `experimentalNativeVideo`, default **off** — so a broken
+spike cannot ship as a regression. Rust already owns this decision; the flag only
+suppresses it.
+
+**Also in scope: remove the user-agent sniffing in
+`src/lib/services/webviewAudio.ts:30-41`.** It re-derives which audio backend the
+platform has from `navigator.userAgent` ("matching the Rust cfg gate", per its own
+comment) — the frontend deciding a backend fact it should be told. Same root cause
+as the hardcode above, same fix: consume the value Rust already computes. Fold it
+in here rather than leaving a second, subtler copy of the bug behind. If
+`get_player_status` does not currently expose enough to cover the audio case, add
+the field — that is backend work, and correct.
+
+### Implementation findings (2026-08-11)
+
+Two blockers existed that this spec did not anticipate. Both were in code the
+spec assumed was merely *unreachable*; it was also *broken*.
+
+**1. The Kotlin attach chain was severed.** `JellyTauPlayer.setActivity()` had
+**zero callers** anywhere in the tree. `currentActivity` was therefore always
+null, so `autoAttachSurface()` logged "Cannot attach surface - no Activity
+reference" and returned. The `SurfaceView` was created and wired to ExoPlayer but
+never added to the view hierarchy — video would have decoded to a surface that
+was never on screen, *regardless* of webview transparency. Fixed by calling
+`JellyTauPlayer.setActivity(this)` from `MainActivity.onCreate`.
+
+Note the knock-on: `PictureInPictureManager.canEnterPip()` gates on
+`VideoOverlayManager.isVideoSurfaceAttached()`, which was permanently false. PiP
+on the video path was dead for the same reason.
+
+**2. `createAdapter()` was not the real gate.** It is never called by production
+code — `VideoPlayer.svelte` constructs `Html5PlayerAdapter` directly. The actual
+override was `VideoPlayer.svelte`'s INTERIM block, which read Rust's
+`useHtml5Element`, forced it to `true`, and called `playerStop()` to kill the
+native backend `player_play_item` had just started. Both sites are now fixed;
+`VideoPlayer.svelte` routes through `createAdapter()` so there is one gate.
+
+**Transparency needs two independent layers cleared,** not one. The spec's
+Phase 1 named only `html, body`. Clearing just the page leaves the WebView
+widget's own background opaque, which is a black screen with audio — the exact
+symptom the INTERIM comment described as "native surface not visible". Both are
+now toggled together by `$lib/utils/videoSurface.ts`:
+
+| Layer | Cleared by | Reachable from |
+|-------|-----------|----------------|
+| WebView widget background + window drawable | `AndroidVideoSurface.setTransparent()` (MainActivity) | Kotlin only |
+| `html`/`body` + app-shell `--color-background` | `data-native-video` attribute → app.css | CSS only |
+
+Transparency is scoped to `tauri.android.conf.json` rather than the base config:
+a transparent window on Linux is a regression, since nothing renders behind it.
+It is also toggled per-session rather than set once — a permanently transparent
+window shows the launcher through the rest of the app.
+
+### Phase 3 — surface positioning
+
+The hard part, and where this most likely fails. The webview's `<video>` element
+occupies a laid-out box; the `SurfaceView` must be positioned to match it, and
+kept matched through scroll, rotation, and mini-player transitions.
+
+Approach: the video view reports its `getBoundingClientRect()` to Rust, which
+forwards the rect to Kotlin to position the `SurfaceView`. This is the same
+"faking it" technique the ecosystem uses on desktop — acceptable here *only if*
+the video is effectively fullscreen on Android, which it is in the player route.
+
+**Explicit failure criterion**: if the surface cannot be kept aligned during
+rotation or the mini-player transition without visible artefacts, the spike fails
+and we keep HTML5. Do not ship a janky native path for a codec win.
+
+**Update: no rect plumbing was needed.** The premise — that the surface must be
+positioned to match a laid-out `<video>` box — does not hold on the player route,
+where video is fullscreen. `VideoOverlayManager` adds the SurfaceView at index 0
+of `android.R.id.content` with `MATCH_PARENT`, and `fitSurfaceToScreen()`
+(`JellyTauPlayer.kt`) already letterboxes/pillarboxes to the real video aspect
+ratio and re-centres via a `Gravity.CENTER` `FrameLayout.LayoutParams`. Rotation
+is handled by an `OnLayoutChangeListener` that re-fits on any bounds change. The
+frontend's native branch is a bare `flex-1` box, so there is no rect to report
+and nothing to keep in sync.
+
+Fullscreen playback is confirmed working on device. But this reasoning rests
+entirely on the fullscreen assumption, so **the mini-player transition is the
+known gap** — it is the one case where the surface is *not* fullscreen, and
+therefore the one case where the "no rect plumbing needed" conclusion could
+still turn out to be wrong. If artefacts appear there, the fix is the rect
+reporting this section originally proposed, scoped to that transition alone.
+
+### A trap for the next implementer
+
+There is a **stale duplicate player** at
+`src-tauri/android/app/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt`
+(only commit: `cfddc1e` "First working POC"). No `sourceSets` entry points at it,
+so it is not compiled — but edits made there silently do nothing. The canonical
+tree is `src-tauri/android/src`, synced into `gen/` by
+`scripts/sync-android-sources.sh`.
+
+### What we gain if it works
+
+- **Hardware decode via MediaCodec** — `CodecDetector.kt` already reports
+  capabilities; the DeviceProfile would finally match what actually plays.
+- **ASS/SSA subtitles** are *not* automatic. ExoPlayer cannot render them; that
+  would require libmpv, which is a separate and much larger decision (see the
+  unification spec's engine comparison). Scope this spike to hardware decode
+  only, and do not claim subtitle improvements from it.
+
+## Out of scope
+
+- Linux native video. Maintainer-declared unfixable on WebKitGTK/Wayland.
+- Replacing ExoPlayer with libmpv on Android.
+- Windows native video.
+- Removing the HTML5 path. It stays as the default and the fallback.
+
+## Acceptance criteria
+
+The spike is **complete** when one of these is true:
+
+**Success path**
+- [x] Transparent WebView confirmed working on a physical device (reported by the maintainer; the config that enables it is now committed in `tauri.android.conf.json`).
+- [x] `experimentalNativeVideo` off → behaviour byte-identical to today. Guarded by `adapterSelection.test.ts`, which asserts the flag-off case forces HTML5 even when Rust reports native.
+- [x] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust (`player_get_capabilities` → `usesWebviewAudio`).
+- [x] `experimentalNativeVideo` on → video plays via ExoPlayer, correctly positioned, on a physical device (2026-08-11). The surface reaches the hierarchy and is visible through the transparent WebView — the whole point of the spike.
+- [x] The poster/title card comes down on the native path. It never could: every `markMediaReady()` call site is a `<video>` element event and the native branch renders no element, so an opaque `bg-black` overlay covered the ExoPlayer surface for the whole session. See DR-182; guarded by `mediaReady.test.ts` (UT-184) and `VideoPlayer.nativeReveal.test.ts` (UT-185), the latter written failing first.
+- [x] The `AndroidVideoSurface` bridge is installed before the page that calls it loads, via `WryActivity.onWebViewCreate` instead of a 500 ms tree walk, and a missing bridge now logs an error instead of no-oping. See DR-183.
+- [x] The SurfaceView is detached when video stops, instead of accumulating one leaked view per native video. See DR-184.
+- [ ] Seek, audio-track switch and subtitle selection exercised through `NativePlayerAdapter`. Playback is confirmed; these individual controls are not yet each verified on the native path.
+- [ ] No artefacts on rotation, background/foreground, or **mini-player transition** — the last is the one case the fullscreen assumption does not cover, so it is the likeliest place to find a problem.
+- [ ] `adb shell dumpsys media.metrics` (or logcat) confirms a hardware decoder is in use. Plausible but unmeasured — do not claim the MediaCodec win until this is read.
+- [ ] Measured battery/thermal or CPU improvement over the HTML5 path on the same clip.
+
+**Failure path**
+- [ ] The blocking behaviour is documented in this spec with evidence.
+- [ ] `NativePlayerAdapter` and the unreachable `SurfaceView` code are deleted, or explicitly retained with a *correct* comment.
+- [ ] `nativeAdapter.ts:11-14` no longer cites tauri#10152.
+
+Either way:
+- [x] `bun run check` (0 errors), `bun run test` (997 passed), `bun run check:boundary` pass.
+- [x] `cargo fmt` / `cargo clippy` clean (no new warnings); `cargo test` passes (603 lib + 7 doc).
+
+### Why the 2026-08-11 verification and DR-172 do not contradict each other
+
+The spike was reported working on device; the same path then shipped as audio
+with no picture. Both are consistent with DR-182: the poster overlay is drawn
+only while `isMediaReady` is false, and the native path has no way to set it, so
+what the surface shows depends entirely on **whether that overlay is on screen**
+— not on whether compositing works. Any run that reached the player through a
+path leaving `isMediaReady` already true (a handoff return, a re-render, a
+session that had previously played on the HTML5 path) shows video; a cold start
+into the native path never does. That is also why DR-172 read the symptom as a
+compositing failure: on screen the two are identical, and the one piece of
+evidence separating them — `WebView transparent = true` never being logged —
+points at DR-183 rather than at the compositing itself.
+
+**This reasoning is not yet device-confirmed.** It explains the reports and is
+backed by the code, but the criteria above are what settle it.
+
+> Note: this environment has no host WebKitGTK dev packages, no Android SDK and
+> no `bun`, so all of the above were run inside the CI builder image
+> (`gitea.tourolle.paris/dtourolle/jellytau-builder:latest`). On Fedora the bind
+> mount needs `:z` for SELinux, and `scripts/build-android.sh` hardcodes
+> `ANDROID_HOME="$HOME/Android/Sdk"`, so the image's SDK at `/opt/android-sdk`
+> must be symlinked there rather than passed by env var.
+
+## Testing
+
+Adapter-selection logic is pure and testable without a device: assert
+`createAdapter` returns `NativePlayerAdapter` for `backendKind: "native"` with
+the flag on, and `Html5PlayerAdapter` in every other combination — including that
+the flag off forces HTML5 even when Rust says native. That last case is the
+regression guard.
+
+Everything else is manual on-device; there is no meaningful way to unit-test
+surface compositing. Test on at least two devices — compositing behaviour varies
+by OEM and Android version.
+
+Per CLAUDE.md, if the spike turns into a bug fix (e.g. seek breaks under the
+native adapter), write the failing test first.
+
+## TRACES
+
+- `createAdapter` → `// TRACES: UR-003, UR-004 | DR-004, DR-150 | UT-149`
+- Adapter-selection tests → `UT-xxx`
+- No new requirement IDs; this spike either satisfies existing IR-004 expectations or documents why it cannot.
+
+## Notes for the implementer
+
+- **Do not skip Phase 1.** If transparency does not work, phases 2 and 3 are
+  wasted effort.
+- `VideoPlayer.svelte` has a documented hazard: no lifecycle calls after an
+  `await` in `onMount` — it flips to HTML5 mode and breaks Android seek. The
+  adapter swap touches exactly this code path.
+- tauri-specta tagged responses keep Rust field names (`new_url`, not `newUrl`).
+- Android source edits go in `src-tauri/android/src`, then run
+  `scripts/sync-android-sources.sh`.
+- A parallel Claude session may be active — `git diff` first.

docs/specs/audio-equalizer.md

@@ -0,0 +1,176 @@
+# Spec: Audio equalizer
+
+**Status:** Accepted
+**Requirements:** UR-027 → DR-030 (EQ UI), IR-020 (MPV EQ integration).
+**UX spec:** n/a (extends the Settings › Audio section, ux-flows §8.1 instant-apply).
+**Supersedes / revises:** —
+**Revised by:** [android-audio-settings-parity.md](android-audio-settings-parity.md) — lifts the "Android is a no-op" limitation below.
+
+## Summary
+
+Add a graphic audio equalizer to playback. Users pick a preset (Flat, Rock,
+Pop, Jazz, Classical, Bass Boost, Treble Boost, Vocal) or set custom per-band
+gains, from a new block in Settings › Audio. On Linux the gains apply live via
+MPV's audio-filter chain; the settings persist and re-apply on the next track
+and at startup, exactly like crossfade/gapless/normalize do today. Android is a
+no-op for now (documented parity gap, same as those three features).
+
+## Motivation
+
+UR-027 is one of the few still-unbuilt audio features. The audio-settings
+pipeline it needs already exists — `AudioSettings` + `set_audio_settings` on the
+`PlayerBackend` trait, the `player_set_audio_settings` command, and the Settings
+› Audio UI with instant-apply. Crossfade, gapless, and volume normalization all
+ride that pipeline. The equalizer is the same shape: N more fields on
+`AudioSettings`, an `af` filter on the MPV backend, one more block in the
+settings panel. No new command, no new state machine.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| EQ band count, centre frequencies, gain range/clamping | Rust | Domain of the audio engine; the bands must match what the MPV filter expects. Changing the DSP must not require a frontend change. |
+| Preset name → per-band gain curve | Rust | A preset *is* a domain gain curve, not a label. It changes with the audio engine's band layout, never with the UI. Placing it in the frontend would be the scoped-search taxonomy mistake again (values that look like config but are domain data). |
+| Translating gains → MPV `af` filter string | Rust | Platform playback detail; lives with the other `set_audio_settings` filter code in `mpv_backend.rs`. |
+| Persisting the chosen settings, re-pushing on load | Rust/existing | Same path crossfade/etc. already use; the controller re-applies `AudioSettings` per track. |
+| Rendering band sliders, the preset chips, live readouts | Frontend | Pure presentation; changes only if the settings UI is redesigned. |
+| Which preset chip is highlighted; instant-apply on change | Frontend | Presentation/input handling (UR-057), the same as the normalize preset picker. |
+
+Tie-breaker note: the preset→curve map is the one tempting boundary leak. It goes
+in Rust because a preset is a set of band gains defined *by the band layout*,
+which is an engine property. The frontend only ever names a preset and renders
+the resulting gains; it never defines them.
+
+## Design
+
+### `AudioSettings` (Rust, `settings.rs`)
+
+Add two fields (both `#[serde(rename_all = "camelCase")]` via the existing
+struct attribute):
+
+```rust
+/// Equalizer enabled. When false, no `af` EQ filter is applied.
+pub equalizer_enabled: bool,
+/// Per-band gains in dB, one per FIXED band (see EQ_BANDS). Length is
+/// validated/normalised to EQ_BANDS.len(); clamped to [-12, +12] dB.
+pub equalizer_bands: Vec<f32>,
+```
+
+Fixed 10-band ISO layout (domain constant in `settings.rs`):
+
+```rust
+pub const EQ_BANDS: [f32; 10] =
+    [31.0, 62.0, 125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0, 16000.0];
+pub const EQ_GAIN_MIN: f32 = -12.0;
+pub const EQ_GAIN_MAX: f32 = 12.0;
+```
+
+- `Default`: `equalizer_enabled: false`, `equalizer_bands: vec![0.0; 10]` (flat).
+- New `with_equalizer_normalised(self)` clamps each gain to `[EQ_GAIN_MIN,
+  EQ_GAIN_MAX]` and pads/truncates the vec to 10 bands. Applied in the command
+  alongside `with_crossfade_clamped` (add that call too — it's currently missing).
+- Backward compat: both fields `#[serde(default)]` so old persisted JSON loads.
+
+### Presets (Rust, `settings.rs`)
+
+```rust
+#[derive(specta::Type, Serialize, Deserialize, Clone, Copy, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub enum EqPreset { Flat, Rock, Pop, Jazz, Classical, BassBoost, TrebleBoost, Vocal }
+
+impl EqPreset {
+    /// The 10-band gain curve (dB) for this preset.
+    pub fn gains(&self) -> [f32; 10] { /* table */ }
+}
+```
+
+Preset selection is a *frontend* convenience: tapping a chip sets
+`equalizer_bands = preset.gains()` and pushes settings. The curve tables live in
+Rust; the frontend reads them via a tiny `player_get_eq_presets` command
+returning `Vec<(EqPreset, Vec<f32>)>` (or a map), so the frontend never encodes
+the numbers. (If exposing the whole table is awkward through specta, expose
+`player_eq_preset_gains(preset) -> Vec<f32>` instead — pick at implement time.)
+
+### MPV application (Rust, `mpv_backend.rs::set_audio_settings`)
+
+Build an `equalizer` / `anequalizer` filter from the bands and set the `af`
+property. When `equalizer_enabled` is false or all gains are 0, clear the EQ
+filter (leave any other `af` entries intact). Use `af add`/`af remove` or a
+rebuilt `af` string; keep it isolated so it doesn't stomp a future crossfade
+filter. Errors map to `PlayerError` like the gapless code.
+
+### No new persistence table
+
+`AudioSettings` is already round-tripped by the frontend settings store and
+re-pushed via `player_set_audio_settings` on change and on load. The two new
+fields ride along. `NullBackend`/Android inherit the trait default (no-op).
+
+### Wire summary
+
+- Command names unchanged: `player_set_audio_settings`,
+  `player_get_audio_settings` (now carry the EQ fields).
+- New (optional) read-only command for preset curves — kebab n/a (it's a
+  command): `player_get_eq_presets` (or `player_eq_preset_gains`).
+- Regenerate `bindings.ts` from the Rust types; never hand-edit.
+
+## Out of scope
+
+- Android/ExoPlayer EQ (parity gap tracked with crossfade/gapless/normalize).
+  **Now specified in [android-audio-settings-parity.md](android-audio-settings-parity.md)**,
+  which implements `set_audio_settings` on `ExoPlayerBackend`. The canonical band
+  layout and preset→curve map defined here remain authoritative; the Android side
+  resamples those bands onto the device equalizer rather than defining its own.
+- Per-track or per-library EQ profiles — one global profile only.
+- Automatic loudness/room correction; only manual bands + presets.
+- Changing the crossfade/normalize TODOs in `set_audio_settings` beyond wiring
+  the missing `with_crossfade_clamped` call.
+
+## Acceptance criteria
+
+- [ ] Settings › Audio has an Equalizer block: enable toggle, preset chips, 10
+      band sliders with live dB readouts, instant-apply (no Save button).
+- [ ] Choosing a preset sets the bands from the Rust-defined curve; editing a
+      band switches the highlighted preset to "Custom" (frontend-only label).
+- [ ] Gains clamp to [-12, +12] dB; the band vector always normalises to 10.
+- [ ] On Linux, enabling EQ audibly changes output and persists across tracks
+      and app restart; disabling clears the filter without affecting other audio.
+- [ ] Old persisted settings (no EQ fields) load without error, defaulting flat.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes (no preset curve numbers in the frontend).
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated.
+
+## Testing
+
+- Rust (`settings.rs`): default is flat + disabled; `with_equalizer_normalised`
+  clamps out-of-range gains and pads/truncates band length; serialization
+  round-trips the camelCase fields; backward-compat load of pre-EQ JSON; each
+  preset returns a 10-length curve; Flat is all zeros.
+- Rust IPC param naming for any new command (camelCase rule per CLAUDE.md).
+- Frontend (`settings` page or an extracted helper): selecting a preset sets the
+  expected band array; editing a band flips the label to Custom; enable toggle
+  gates the sliders. Keep DSP untested on the frontend (it's Rust's).
+
+## TRACES
+
+- `AudioSettings` EQ fields + normalise + presets: `UR-027 | DR-030` (+ unit tests)
+- MPV EQ filter application: `UR-027 | IR-020`
+- Settings EQ UI block: `UR-027 | DR-030`
+- Preset-curve command: `UR-027 | DR-030`
+
+## Notes for the implementer
+
+- A parallel Claude session is active in this repo (it has touched
+  `tauri.conf.json`, `Dockerfile`, `package.json`, home components, and added
+  build scripts, and the Rust build is currently broken by its
+  `tauri.conf.json` bundle-target change). `git diff` before "repairing"
+  anything you didn't write; keep EQ changes isolated to `settings.rs`,
+  `mpv_backend.rs`, `backend.rs` (trait default already covers it),
+  `commands/player/settings.rs`, and the settings page.
+- Mirror the volume-normalization block in the settings page for the toggle +
+  preset-picker pattern; mirror the gapless code in `set_audio_settings` for the
+  MPV property handling.
+- Confirm the exact MPV filter name available in the linked libmpv
+  (`equalizer` vs `anequalizer`/`superequalizer`) before committing the filter
+  string; gate cleanly if unavailable.

docs/specs/boundary-tripwire-hardening.md

@@ -0,0 +1,215 @@
+# Spec: Harden the frontend boundary tripwire
+
+**Status:** Implemented
+**Requirements:** DR-094
+**UX spec:** n/a — developer tooling.
+**Supersedes / revises:** revises the detection rule in
+[scripts/check-frontend-boundary.sh](../../scripts/check-frontend-boundary.sh);
+the boundary *policy* in [scoped-search-boundary.md](scoped-search-boundary.md)
+is unchanged.
+
+## Summary
+
+`bun run check:boundary` passes on a tree that contains the exact leak it was
+built to catch. It matches a multi-type array only when written **inline at the
+query site**, so assigning the same array to a named const evades it entirely —
+which is how [searchScope.ts](../../src/lib/utils/searchScope.ts) has kept a
+category→item-type mapping through every green CI run. This spec broadens the
+match to item-type array literals anywhere in `src/`, and resolves the handful
+of legitimate hits that broadening surfaces.
+
+## Motivation
+
+The current pattern is anchored to the `includeItemTypes:` key:
+
+```sh
+PATTERN='includeItemTypes:[[:space:]]*\[[^]]*,[^]]*\]'
+```
+
+The live leak is not written that way:
+
+```ts
+// src/lib/utils/searchScope.ts:29 — invisible to the tripwire
+const SCOPE_ITEM_TYPES = { music: ["MusicAlbum", "MusicArtist", "Audio", "Playlist"], … };
+```
+
+The taxonomy and the query are one indirection apart, and the grep only sees the
+query. The script's own header is admirably honest that it is "a TRIPWIRE, NOT A
+PROOF" — but the gap here is not a subtle judgment call it was designed to
+defer to human review. It is the *crudest form* of the violation, one `const`
+away from the shape it does match, in the very file the founding incident was
+written about.
+
+Broadening the pattern to any item-type array literal finds it, with a
+manageable number of other hits (measured, not estimated):
+
+| Site | Verdict |
+|------|---------|
+| `searchScope.ts:30,32` | 🔴 The leak. Removed by [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md). |
+| `PersonDetailView.svelte:30` | Already allowlisted, with a recorded reason. |
+| `DownloadedBrowse.svelte:95` | Borderline — `["MusicAlbum","Series","Season","BoxSet"].includes(item.type)` as an "is this a container?" predicate. |
+| `GenericMediaListPage.svelte:298` | Borderline — `["MusicAlbum","MusicArtist","Audio","Playlist"].includes(config.itemType)` as a music-styling predicate. |
+| 6 hits in `*.test.ts` | Excluded; tests legitimately name types. |
+
+Four non-test sites total. This is a tractable change, not a boil-the-ocean one.
+
+## Layer assignment
+
+Tooling only — no application logic, nothing crosses IPC. The two borderline
+*application* sites do get a layer decision, below.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Detecting item-type array literals in `src/` | Build tooling (`scripts/`) | Static analysis of repo source; belongs beside the existing check. |
+| "Is this item a container?" (`DownloadedBrowse`) | **Rust** (recommended) | Containers-vs-leaves is Jellyfin structure, and the set grows when Jellyfin adds a container type — the litmus test's "yes". Prefer a `MediaItem.isContainer` boolean from the backend over a type-set predicate in a component. |
+| "Is this music content?" (`GenericMediaListPage`) | **Frontend, allowlisted** | Selects a grid *style*. It reads `config.itemType`, a value the page already declares about itself, and changes only if the UI is redesigned — the litmus test's "no". Single-type presentation is explicitly not the target of the rule. |
+
+`DownloadedBrowse` defaults to Rust per the checklist's borderline rule; see
+Out of scope for why the migration itself is deferred rather than bundled.
+
+## Design
+
+### 1. Broaden the pattern
+
+Replace the key-anchored pattern with one matching an array literal of two or
+more known Jellyfin item types, wherever it appears:
+
+```sh
+# Two or more adjacent item-type string literals inside a bracket.
+TYPES='Movie|Series|Episode|Audio|MusicAlbum|MusicArtist|MusicVideo|Season|BoxSet|Playlist|Book|AudioBook|Video|Person|Folder|CollectionFolder|TvChannel|LiveTvChannel'
+PATTERN="\[[[:space:]]*\"($TYPES)\"[[:space:]]*,[[:space:]]*\"($TYPES)\""
+```
+
+Properties worth stating, because each is a deliberate trade:
+
+- **Not anchored to any key**, so a named const, a function return, a `Record`
+  value, or an inline query all match equally.
+- **Requires two adjacent type literals**, preserving the existing and correct
+  carve-out that single-type presentation (`itemType: "Movie"`) is legitimate.
+- **Requires string literals**, so `item.type === "Audio"` (display inspection)
+  still does not match.
+- **Explicit type list**, not `[A-Z][a-z]+`, so arbitrary string arrays
+  (`["High","Low"]`, `["Songs","Albums"]`) do not produce noise.
+
+Keep `grep -rInE`, the `*.test.*` exclusion, and the allowlist mechanism as they
+are — all three work.
+
+### 2. Resolve the surfaced sites
+
+- `PersonDetailView.svelte` — already allowlisted; entry unchanged.
+- `GenericMediaListPage.svelte` — **add to the allowlist** with the reason from
+  the layer table (grid styling over a self-declared `itemType`).
+- `DownloadedBrowse.svelte` — **add to the allowlist with a `TODO` naming the
+  preferred fix** (backend `isContainer`). An allowlist entry that records a
+  known-borderline decision is honest; silently broadening the pattern to miss
+  it would not be.
+- `searchScope.ts` — **not allowlisted.** It is the leak, and
+  [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md)
+  deletes it.
+
+### 3. 🔴 Sequencing
+
+**This spec must land after Stage 1 of
+[scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md).**
+Hardening the tripwire first turns `master` red on a violation with no fix
+available, and the only ways out are reverting the hardening or allowlisting the
+leak — the second of which is exactly how a boundary rule dies.
+
+### 4. Keep the allowlist honest
+
+The script already warns that a growing allowlist means the boundary is eroding.
+This change takes it from 1 entry to 3, which is close to that line. Add a hard
+cap so drift is caught mechanically rather than by whoever notices:
+
+```sh
+MAX_ALLOWLIST=4
+if [ "${#ALLOWLIST[@]}" -gt "$MAX_ALLOWLIST" ]; then
+  echo "❌ Allowlist has ${#ALLOWLIST[@]} entries (max $MAX_ALLOWLIST)."
+  echo "   Push taxonomy into Rust instead of appending here."
+  exit 1
+fi
+```
+
+The cap is deliberately just above the current count: the next exception forces
+a conversation instead of a one-line append.
+
+### 5. Restate the limits
+
+The header's "tripwire, not a proof" caveat stays and gets sharper. The broadened
+pattern still cannot see:
+
+- a type set built at run time (`[...musicTypes, "Playlist"]`),
+- types split across variables (`const A = "Audio"; [A, B]`),
+- taxonomy expressed as a `switch` or chained `||` rather than an array.
+
+The spec-review checklist remains the real gate. This raises the floor; it does
+not close the class.
+
+## Out of scope
+
+- **Migrating `DownloadedBrowse` to a backend `isContainer` flag.** It touches
+  `MediaItem`, `bindings.ts`, and the offline path — its own spec. Allowlisted
+  with a TODO here so it is recorded, not forgotten.
+- The scoped-search fix itself — [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md).
+- Detecting the run-time-construction cases listed above.
+- Extending the check to Rust or Kotlin (the rule is about `src/`).
+- Changing the boundary *policy* in CLAUDE.md.
+
+## Acceptance criteria
+
+- [ ] With `searchScope.ts` reverted to its leaking form, `bun run check:boundary`
+      **fails** and names `src/lib/utils/searchScope.ts`. This is the criterion
+      that proves the fix — verify it explicitly before landing.
+- [ ] On the post-fix tree, `bun run check:boundary` passes.
+- [ ] A newly introduced `const X = ["Movie", "Series"]` in any non-test `src/`
+      file fails the check (regression test for the const-indirection evasion).
+- [ ] `itemType: "Movie"` and `item.type === "Audio"` do **not** trip the check.
+- [ ] `["High", "Low"]` and other non-item-type arrays do **not** trip it.
+- [ ] Test files are still excluded (the 6 known test hits stay silent).
+- [ ] The allowlist has exactly 3 entries, each with a written reason; a 5th
+      entry fails the check via `MAX_ALLOWLIST`.
+- [ ] The script header still states it is a tripwire, not a proof, and names the
+      evasions it cannot see.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run test:all` passes.
+
+## Testing
+
+The script is bash and has no test harness. Verify by construction — each is a
+temporary edit, run, revert:
+
+1. Reintroduce the `SCOPE_ITEM_TYPES` const → **must fail**.
+2. Add `const T = ["Movie","Series"]` to a scratch `.svelte` file → **must fail**.
+3. Add the same to a `.test.ts` file → **must pass** (exclusion holds).
+4. Add `itemType: "Movie"` → **must pass**.
+5. Add a 5th allowlist entry → **must fail** on the cap.
+
+Record the five results in the PR description. A grep-based gate that has never
+been observed failing is indistinguishable from one that cannot fail — which is
+the precise condition this whole spec exists to correct.
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-094** — "Frontend boundary tripwire detects Jellyfin item-type array
+  literals anywhere in `src/` (not only inline at an `includeItemTypes:` query
+  site), so a category→type mapping cannot evade the check via a named const;
+  allowlist is capped to force taxonomy into Rust rather than accumulating
+  exceptions." Category: Tooling. Status: Done on merge.
+
+Shell scripts carry no `TRACES:` comment convention in this repo; reference
+DR-094 in the script header comment instead.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Land after Stage 1 of the scoped-search fix** — see §3. This is the one
+  ordering constraint that will break `master` if ignored.
+- Test the regex against the current tree *before* committing:
+  `grep -rInE "$PATTERN" src/ | grep -v '\.test\.'` should return exactly the
+  four sites in the Motivation table.
+- The `TYPES` list will need occasional extension as Jellyfin adds types.
+  That is acceptable for a tripwire — an unlisted type produces a false
+  negative, never a false positive, so the check degrades safely.

docs/specs/build-provenance.md

@@ -0,0 +1,250 @@
+# Spec: Build provenance (git describe + build profile)
+
+**Status:** Proposed
+**Requirements:** new DR-093 (build provenance surfaced in-app and in logs); no UR — this is a diagnostic capability, not a user feature
+**UX spec:** n/a — adds an About block to Settings; no new flow
+**Supersedes / revises:** —
+
+## Summary
+
+Make every build say exactly what it is. Today a running JellyTau reports no
+version at all — not in the UI, not in the logs — and the only version string in
+the tree is the hand-maintained `0.2.0` duplicated across three files.
+
+This adds a `build.rs`-generated provenance string (`git describe` + short SHA +
+dirty flag + debug/release profile), exposes it over IPC, and renders it in a new
+Settings › About block. It also removes one of the three hand-bumped version
+files.
+
+## Motivation
+
+The concrete problem: when a user reports "the equalizer does nothing on my
+device" — which is a live risk for v0.2.0, whose Android audio settings are not
+yet device-verified — there is currently no way to tell which build they are
+running. Tag? Master? A local debug build from three weeks ago? The bug report
+cannot distinguish them.
+
+Two smaller irritations this also fixes:
+
+- **Debug builds masquerade as releases.** `0.2.0` is `0.2.0` whether it came
+  from a tagged release or `bun run tauri dev`.
+- **Three files carry the version.** `package.json`, `src-tauri/Cargo.toml` and
+  `src-tauri/tauri.conf.json` must be bumped in lockstep; the release checklist
+  exists partly to stop them drifting.
+
+### What this deliberately does *not* do
+
+**The canonical version stays hand-bumped in `Cargo.toml`.** Cargo requires a
+literal semver string at manifest-parse time and cannot derive it from git. The
+same is true of `tauri.conf.json`. Attempting to source the *release* version
+from a tag trades a scripted, reviewable bump for a fragile build-time
+dependency that breaks in exactly the environment we care most about (CI, in
+Docker, from a shallow clone).
+
+So: **the release version is authored; the build provenance is derived.** They
+answer different questions — "what release is this?" versus "what commit is this
+binary actually built from?" — and only the second benefits from git.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Capturing git describe / SHA / dirty state at compile time | Rust (`build.rs`) | Only the Rust build has a compile step that can shell out to git and bake the result into the binary. A frontend equivalent would report the *dev server's* state, not the shipped binary's. |
+| Degrading to a sentinel when git is unavailable | Rust (`build.rs`) | Build-environment concern. Must never fail the build — CI runs in Docker from a shallow clone. |
+| Release version (`0.2.0`) | Rust (`Cargo.toml`, authored) | Domain fact about the product, not derivable from the environment. |
+| Deciding *what a build is* (release / dev / dirty) | Rust | Domain classification. The frontend must not infer "this is a dev build" from a string shape — it renders what it is told. |
+| Rendering the About block, copy-to-clipboard | Frontend | Pure presentation. |
+
+Borderline row: the release/dev/dirty classification could be done in the
+frontend by pattern-matching the describe string. It goes to Rust because that is
+a *rule about what constitutes a release build*, and it would have to change if
+the tagging scheme changed — the litmus test in the template puts that in Rust.
+Send a typed enum, not a string for the frontend to parse.
+
+## Design
+
+### `build.rs`
+
+```rust
+fn main() {
+    emit_build_provenance();
+    tauri_build::build()
+}
+
+fn emit_build_provenance() {
+    let describe = std::process::Command::new("git")
+        .args(["describe", "--tags", "--always", "--dirty"])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .and_then(|o| String::from_utf8(o.stdout).ok())
+        .map(|s| s.trim().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+
+    println!("cargo:rustc-env=JELLYTAU_GIT_DESCRIBE={describe}");
+
+    // Rebuild when HEAD moves or a ref is written, so the string does not go
+    // stale across commits. Guarded: these paths do not exist in a git-less
+    // source tarball, and emitting rerun-if-changed for a missing path would
+    // force a rebuild every time.
+    for p in [".git/HEAD", ".git/refs"] {
+        if std::path::Path::new("../").join(p).exists() {
+            println!("cargo:rerun-if-changed=../{p}");
+        }
+    }
+}
+```
+
+🔴 **`build.rs` must never fail the build.** Every git call is
+`.ok()`-swallowed; a missing git binary, a shallow clone, or a source tarball all
+yield `"unknown"`. A build that breaks because git is absent would be a worse bug
+than the one this fixes.
+
+Note the `../` prefixes: `build.rs` runs with CWD at `src-tauri/`, so the repo's
+`.git` is one level up.
+
+### The provenance type
+
+```rust
+/// TRACES: DR-093
+#[derive(specta::Type, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BuildInfo {
+    /// Authored release version (Cargo.toml).
+    pub version: String,
+    /// `git describe --tags --always --dirty`, or "unknown".
+    pub git_describe: String,
+    /// What kind of build this is — classified in Rust, not inferred by the UI.
+    pub kind: BuildKind,
+}
+
+/// TRACES: DR-093
+#[derive(specta::Type, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BuildKind {
+    /// Built from a clean, exactly-tagged commit in release mode.
+    Release,
+    /// Release-mode build that is not on a clean tag (e.g. master, or dirty).
+    Untagged,
+    /// debug_assertions build.
+    Development,
+    /// Git state unavailable at build time.
+    Unknown,
+}
+```
+
+Classification:
+
+```rust
+let kind = if cfg!(debug_assertions) {
+    BuildKind::Development
+} else if describe == "unknown" {
+    BuildKind::Unknown
+} else if describe.contains('-') {   // "v0.2.0-3-gcb79a37" or "...-dirty"
+    BuildKind::Untagged
+} else {
+    BuildKind::Release
+};
+```
+
+### Command
+
+```rust
+/// TRACES: DR-093
+#[tauri::command]
+#[specta::specta]
+pub fn get_build_info() -> BuildInfo { … }
+```
+
+No parameters, so the camelCase param rule does not apply; the struct fields do
+need `#[serde(rename_all = "camelCase")]` (above). Regenerate `bindings.ts`.
+
+Also log the provenance once at startup, next to the existing init logging —
+that is what makes a user-submitted log file self-identifying, which is most of
+the value.
+
+### Settings › About
+
+A new block at the bottom of `src/routes/settings/+page.svelte`, rendering
+version, describe string, and a badge for non-release builds. One
+copy-to-clipboard button that yields a paste-ready block for bug reports:
+
+```
+JellyTau 0.2.0 (v0.2.0-3-gcb79a37-dirty, development)
+linux x86_64
+```
+
+Platform/arch come from the existing Tauri APIs; do not shell out.
+
+### Removing one version file
+
+`tauri.conf.json`'s `"version"` field can be omitted, in which case Tauri falls
+back to the Cargo version. That takes the bump from three files to two.
+
+**Verify before adopting**: confirm the Android `versionName`/`versionCode` and
+the NSIS installer version still resolve correctly with the field absent —
+Android packaging in particular reads the Tauri config. If either regresses,
+keep the field and drop this part; it is a convenience, not the point of the
+spec.
+
+## Out of scope
+
+- Deriving the *release* version from git tags (see Motivation).
+- A build-time timestamp. It defeats reproducible builds and adds little over
+  the commit SHA.
+- CI provenance/attestation, SBOM, signing.
+- Displaying the Jellyfin server version (separate concern, already available
+  from `/System/Info`).
+
+## Acceptance criteria
+
+- [ ] `cargo build` succeeds with git absent, from a shallow clone, and from a source tarball with no `.git` — yielding `"unknown"` in each case, never a build failure.
+- [ ] A tagged clean release build reports `BuildKind::Release`; `bun run tauri dev` reports `Development`; a dirty tree reports `Untagged` (release mode) with `-dirty` in the describe string.
+- [ ] The describe string changes after a new commit without a manual `cargo clean` (rerun-if-changed works).
+- [ ] Provenance is logged once at startup.
+- [ ] Settings › About renders version + describe + build-kind badge, with working copy-to-clipboard.
+- [ ] 🔴 CI checkouts that build a shippable artifact set `fetch-depth: 0`, or their artifacts are knowingly stamped `unknown`. Currently only `publish-docs.yml` sets it; `build-release.yml` has five checkouts and `build-and-test.yml` two, all of which would report `unknown` as-is.
+- [ ] **No toolchain installed in CI** — git is already present in the builder image; nothing new is added.
+- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bindings.ts` regenerated.
+- [ ] DR-093 allocated in `requirements.md`; new code carries `// TRACES:`.
+
+## Testing
+
+**Rust**: the classification is pure and must be extracted from the command as
+`classify_build(describe: &str, debug: bool) -> BuildKind` so it can be tested
+directly. Cover: `"v0.2.0"` → `Release`; `"v0.2.0-3-gcb79a37"` → `Untagged`;
+`"v0.2.0-dirty"` → `Untagged`; `"unknown"` → `Unknown`; `debug = true` → always
+`Development` regardless of describe.
+
+`build.rs` itself is not unit-testable. Verify its failure path manually by
+building with `PATH` stripped of git, and from a `git archive` tarball — both
+must succeed with `"unknown"`.
+
+**Frontend**: assert the About block renders each `BuildKind` correctly, and that
+it renders the backend-supplied kind rather than re-deriving it from the string
+(a test that passes a `Release` kind with a `-dirty` describe and asserts the
+badge follows the *kind* would catch that regression).
+
+## TRACES
+
+- `build.rs` provenance emission → `// TRACES: | DR-093`
+- `BuildInfo` / `BuildKind` / `classify_build` → `// TRACES: | DR-093`
+- `get_build_info` command → `// TRACES: | DR-093`
+- Settings About block → `// TRACES: | DR-093`
+- `classify_build` tests → `UT-BUILD-1`
+- Allocate **DR-093** in `requirements.md` ("Build provenance: git describe and
+  build profile surfaced in-app and in logs"). Next free DR at time of writing
+  is DR-093.
+
+## Notes for the implementer
+
+- Do the `build.rs` + command + logging first; the About UI is the smaller half
+  and the logging alone delivers most of the diagnostic value.
+- The `fetch-depth: 0` change is the easiest part to forget and the one that
+  makes CI artifacts useless if missed — it is why that acceptance box is
+  flagged. Weigh it per workflow: test-only jobs do not need it.
+- Do not add a build timestamp "while you are in there" — see Out of scope.
+- A parallel Claude session may be active — `git diff` before "repairing"
+  unexpected changes.

docs/specs/catalog-index-search.md

@@ -0,0 +1,334 @@
+# Spec: Locally-indexed search
+
+**Status:** Implemented
+**Requirements:** UR-065 → DR-108, DR-109, DR-110, DR-111; IR-030
+**UX spec:** [ux-flows.md §6.1](../ux-flows.md) (search surface is unchanged)
+**Revises:** [scoped-search.md](scoped-search.md) and
+[scoped-search-boundary.md](scoped-search-boundary.md) — scope semantics are
+untouched; this changes only *which corpus* the cache leg searches.
+
+## Summary
+
+Search stops depending on a per-keystroke round trip to Jellyfin. The local
+SQLite catalog — which is already synced and already FTS5-indexed — becomes the
+corpus the instant leg of search reads, so results appear as fast as SQLite can
+answer, online or offline. A background indexer keeps that catalog fresh on a
+schedule instead of only at app start, prunes content deleted on the server, and
+covers the item types search groups results by. The server query stays, demoted
+to a background reconciliation that merges in late results for anything indexed
+since the last pass.
+
+## Motivation
+
+The pieces are already built and simply not wired together:
+
+- [`sync_full_catalog`](../../src-tauri/src/commands/catalog.rs) already walks
+  every library `Recursive=true` and persists items with `synced_at`.
+- `items_fts` (schema.rs migration 001) already indexes `name`, `overview`,
+  `album_name`, `album_artist`, `artists`, `series_name` with keep-in-sync
+  triggers.
+- `repository_search` is already two-phase — synchronous cache result, then a
+  spawned server query merged in via the `search-event`.
+
+What breaks the chain is that the cache leg is hard-restricted to *downloaded*
+items. `OfflineRepository::search` wraps its FTS query in a `downloaded_items`
+CTE requiring `d.status = 'completed'`:
+
+```sql
+FROM items i
+ JOIN items_fts fts ON fts.rowid = i.rowid
+ INNER JOIN downloaded_items di ON i.id = di.id
+ WHERE i.server_id = ? AND items_fts MATCH ?
+```
+
+So for a user with no downloads, phase 1 returns nothing on every query, and
+every debounced keystroke falls through to a full `Recursive=true` server
+request with `Limit=10000`. The populated local index is never read.
+
+`get_items` does not have this problem — it gates a third `synced_at IS NOT NULL`
+branch on `include_catalog_browse()` (offline.rs, the "Show all server media"
+toggle). The asymmetry is the bug: **offline you can already browse the whole
+catalog but cannot search it.**
+
+Three further defects found while confirming the above:
+
+1. **The FTS index grows without bound.** `save_to_cache` uses
+   `INSERT OR REPLACE INTO items`, but `recursive_triggers` is never enabled
+   (`storage/mod.rs` sets only `foreign_keys` and `journal_mode`). SQLite fires
+   `AFTER DELETE` triggers on a REPLACE *only* with recursive triggers on — so
+   `items_ad` never runs, the old FTS row is orphaned, and because `items.id` is
+   a `TEXT PRIMARY KEY` the replacement row takes a **new rowid** and inserts a
+   second FTS entry. Every sync appends a duplicate index. Results stay correct
+   (the `INNER JOIN … ON fts.rowid = i.rowid` hides orphans, and no rowid is ever
+   reused because nothing is deleted) but `MATCH` degrades permanently.
+2. **Server-side deletions never propagate.** There is no `DELETE FROM items`
+   anywhere in the codebase. The local catalog is append-only, so media removed
+   from the server would stay searchable forever — tolerable when the cache was
+   only a browse accelerator, not acceptable when it is the search corpus.
+3. **The index omits types search groups by.** `CATALOG_ITEM_TYPES` is
+   `MusicAlbum, Movie, Series, Season, Episode, Audio, BoxSet` — no
+   `MusicArtist`, no `Playlist`, and People live in a separate `people` table
+   with no FTS at all. UR-060 mandates Artists and People result groups, so today
+   those can *only* come from the server.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Which corpus search reads (downloads-only vs full synced catalog) | **Rust** | Sync/availability policy over domain data. Changes if Jellyfin's API or the offline rules change, not if the UI is redesigned. Reuses the existing `include_catalog_browse()` flag so search and browse cannot diverge again. |
+| Index freshness policy — TTL, when a re-index is due, skip-while-offline | **Rust** | Explicitly named as domain policy in [SPEC-REVIEW-CHECKLIST.md](SPEC-REVIEW-CHECKLIST.md) ("reachability/sync policy"). It is currently frontend-driven in `offlineCatalog.ts`; this spec moves it. |
+| Which Jellyfin item types get indexed (`CATALOG_ITEM_TYPES`) | **Rust** | Textbook domain taxonomy — a category→item-type set. Must never appear in `src/`. |
+| Reconciling a crawl against local rows (what to prune) | **Rust** | Operates on domain data and depends on crawl completeness semantics. |
+| FTS query construction, ranking, scope→type expansion | **Rust** | Already there (`search_rank.rs`, `SearchScope::item_types()`); unchanged by this spec. |
+| Rendering a "catalog last indexed N ago" hint and any re-index button | **Frontend** | Pure presentation of a backend-supplied timestamp. |
+| Debounce interval, result group order, scope chips | **Frontend** | Input handling and view preference; changes only if the UI is redesigned. |
+
+Borderline call, recorded: the **TTL value itself** (how many hours before a
+re-index is due) could be argued as a user preference and therefore frontend. It
+is placed in Rust because the frontend must not be able to decide *whether the
+cache is authoritative* — that is the same class of decision as
+`include_catalog_browse`, which already lives in Rust. If the TTL later becomes
+user-configurable it stays a Rust-owned setting the frontend edits through a
+command, not a frontend constant. Borderline defaults to Rust.
+
+## Design
+
+### 1. Search the full synced catalog (DR-108)
+
+`OfflineRepository::search` mirrors `get_items` exactly: rename the CTE to
+`available_items` and add the same third branch, gated on the same flag.
+
+```rust
+let catalog_branch = if include_catalog_browse() {
+    "UNION
+
+        -- Synced catalog: fast online search, or the offline 'Show all
+        -- server media' view. Mirrors get_items; see set_include_catalog_browse.
+        SELECT DISTINCT i.id
+        FROM items i
+        WHERE i.synced_at IS NOT NULL"
+} else {
+    ""
+};
+```
+
+No new IPC surface and no frontend change: `set_include_catalog_browse` is
+already called with `true` when online or when the offline toggle is on, and
+`false` only when offline with the toggle off. Search inherits the correct
+behaviour in all three states, and the "search is restricted to downloads" case
+survives for users who deliberately asked for downloads-only.
+
+Also fix, in the same function, the `type_filter` built by **string
+interpolation** of `include_item_types` rather than bound parameters. It is
+currently safe only because callers pass `SearchScope`-derived values, but
+`SearchOptions.include_item_types` is settable directly from the frontend (as
+`GenericMediaListPage` does). Bind the values.
+
+Phase 2 (the server query) is unchanged and still merges via `search-event`, so
+content added to the server since the last index still surfaces — just late
+rather than first.
+
+### 2. Scheduled background indexer (DR-109, IR-030)
+
+A Rust-owned task replaces the frontend's startup-only trigger.
+
+```rust
+/// How long a full-catalog index stays fresh before a re-index is due.
+const CATALOG_INDEX_TTL: Duration = Duration::from_secs(6 * 60 * 60);
+```
+
+Behaviour:
+
+- On app setup, spawn a tokio task that ticks every 30 min.
+- Each tick: if a repository is active **and** the server is reachable **and**
+  `now - last_catalog_sync > CATALOG_INDEX_TTL`, run a full index pass.
+- On the existing `ConnectivityMonitor` reconnect signal, evaluate the same
+  staleness condition immediately rather than waiting for the next tick.
+- Never run two passes concurrently (the existing `syncInProgress` guard moves
+  into Rust as an `AtomicBool`).
+
+`last_catalog_sync` is already written to `app_settings` by `sync_full_catalog`
+and is currently read only for a UI hint; this makes it load-bearing.
+
+`RepositoryManager` (`commands/repository.rs`) is a `HashMap<String, …>` with no
+notion of an active handle, so the task has nothing to run against. Add:
+
+```rust
+pub struct RepositoryManager {
+    repositories: Arc<Mutex<HashMap<String, Arc<HybridRepository>>>>,
+    active: Arc<Mutex<Option<String>>>,   // set in create(), cleared in destroy()
+}
+```
+
+Progress is reported with a **kebab-case** event (per the project convention):
+
+```rust
+// event name: "catalog-index-event"
+#[derive(specta::Type, Serialize, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogIndexEvent {
+    pub state: CatalogIndexState,   // #[serde(tag = "type")] Idle | Running | Complete | Failed
+    pub libraries_done: usize,
+    pub libraries_total: usize,
+    pub items_indexed: usize,
+}
+```
+
+`sync_full_catalog` stays a command so the UI can still force a pass; it and the
+scheduler share one internal `run_index_pass()`.
+
+### 3. Index hygiene — no orphans, and deletions propagate (DR-110)
+
+**Orphan growth.** Replace `INSERT OR REPLACE INTO items (…)` in `save_to_cache`
+with a true upsert:
+
+```sql
+INSERT INTO items (id, server_id, …) VALUES (…)
+ON CONFLICT(id) DO UPDATE SET
+    name = excluded.name, overview = excluded.overview, …,
+    synced_at = excluded.synced_at
+```
+
+This preserves the rowid (which `items_fts` keys on via `content_rowid`) and
+fires `items_au` instead of silently orphaning a row. Preferred over
+`PRAGMA recursive_triggers = ON` because it also stops the rowid churn, and the
+three FTS triggers are the only triggers in the schema so nothing else depends
+on REPLACE semantics.
+
+A new migration `021_rebuild_items_fts` clears the orphans already accumulated on
+existing installs:
+
+```sql
+INSERT INTO items_fts(items_fts) VALUES('rebuild');
+```
+
+**Deletions.** After a library crawls *successfully and completely*, reconcile:
+delete local rows for that library whose `id` was not seen in the crawl. Two
+constraints the implementation must respect:
+
+- Skip any item with a completed download — the user has the file; removing the
+  row would orphan it. Prune only synced-but-not-downloaded rows.
+- Only sweep libraries whose crawl succeeded. `sync_full_catalog` is
+  deliberately best-effort per library, and `items.parent_id` is
+  `ON DELETE CASCADE` — sweeping on a partial crawl would cascade a whole series
+  away because one request timed out.
+
+### 4. Index the types search groups by (DR-111)
+
+Add `MusicArtist` and `Playlist` to `CATALOG_ITEM_TYPES`.
+
+People need a different mechanism: they live in `people` (`id`, `server_id`,
+`name`, `overview`, `primary_image_tag`, `synced_at`), populated incidentally by
+item-detail fetches, with no FTS table. Migration `022_people_fts` adds one
+mirroring the `items_fts` pattern:
+
+```sql
+CREATE VIRTUAL TABLE IF NOT EXISTS people_fts USING fts5(
+    name, overview, content='people', content_rowid='rowid'
+);
+-- plus people_ai / people_ad / people_au triggers
+```
+
+`OfflineRepository::search` UNIONs `people_fts` matches into its result set as
+`Person`-typed items when the resolved scope permits them (i.e. when
+`include_item_types` is `None` — `SearchScope::All`). `search_rank.rs` already
+handles `MediaKind::Person`, so ranking needs no change.
+
+## Out of scope
+
+- **Incremental indexing** (e.g. Jellyfin's `MinDateLastSaved`). A full crawl is
+  what makes the deletion sweep in §3 sound — it yields the authoritative id set
+  per library. An incremental pass cannot detect deletions, so it would need a
+  separate reconciliation strategy. Worth revisiting if full crawls prove too
+  slow on large libraries; measure first.
+- **Changing search UX** — scope chips, group order, the debounce, and the
+  `/search` route are untouched.
+- **Removing the server leg.** Phase 2 stays.
+- The two dead search implementations (`storage_search_items` in
+  `commands/storage/mod.rs`, `offline_search` in `commands/offline.rs`) — both
+  registered in `lib.rs` and exported to `bindings.ts`, neither called from the
+  frontend. Deleting them is correct but is cleanup, not this feature; file
+  separately so this spec's diff stays reviewable.
+- `GenericMediaListPage` passing raw `includeItemTypes` and re-implementing the
+  store's request-id/event protocol. A real boundary smell, tracked separately.
+
+## Acceptance criteria
+
+- [ ] With a synced catalog and **zero downloads**, typing a query returns
+      results from the local index before any server request completes.
+- [ ] Offline with "Show all server media" **on**, search returns the full
+      catalog (non-downloaded entries greyed out, matching browse).
+- [ ] Offline with the toggle **off**, search returns downloaded media only —
+      the behaviour that exists today.
+- [ ] Re-running a full index pass N times does not grow `items_fts` row count
+      beyond the `items` row count.
+- [ ] An item deleted server-side disappears from local search after one index
+      pass; a **downloaded** item deleted server-side does not.
+- [ ] A library that fails mid-crawl prunes nothing.
+- [ ] Searching an artist or actor name returns results with the server
+      unreachable.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated (new `CatalogIndexEvent` type).
+
+## Testing
+
+Per CLAUDE.md, each defect gets a **failing test first**.
+
+Rust (`cargo test`), against an in-memory DB seeded with synced-but-not-
+downloaded items:
+
+- `search` returns synced items when `include_catalog_browse()` is true, and
+  only downloaded items when false. *Fails today* — the current CTE returns
+  empty in the first case.
+- Upserting the same item twice leaves exactly one `items_fts` row. *Fails
+  today.*
+- The sweep removes a vanished synced item, retains a vanished downloaded item,
+  and no-ops for a library whose crawl errored.
+- `type_filter` binds parameters — a type string containing a quote does not
+  alter the query.
+- Staleness: a `last_catalog_sync` inside the TTL does not trigger a pass; one
+  outside it does; offline never does.
+- `people_fts` matches surface as `Person` items under `SearchScope::All` and
+  are excluded under `Music`/`Movies`/`Tv`.
+
+Frontend (`vitest`): the catalog-index event maps to the staleness hint; no
+change to the search store's request-id/stale-response handling, which stays
+covered by its existing tests.
+
+## TRACES
+
+| Piece | Tag |
+|---|---|
+| `OfflineRepository::search` availability CTE | `// TRACES: UR-065 \| DR-108` |
+| Background indexer task + scheduling | `// TRACES: UR-065 \| DR-109, IR-030` |
+| `save_to_cache` upsert + FTS rebuild migration | `// TRACES: UR-065 \| DR-110` |
+| Deletion reconciliation | `// TRACES: UR-065 \| DR-110` |
+| `CATALOG_ITEM_TYPES` widening + `people_fts` | `// TRACES: UR-065, UR-060 \| DR-111` |
+
+## Notes for the implementer
+
+- **A parallel Claude session may be active in this repo.** Run `git diff`
+  before "repairing" changes you did not make (CLAUDE.md gotchas).
+- The frontend's `offlineCatalog.ts` startup trigger should be **removed**, not
+  left alongside the Rust scheduler — two independent triggers with one
+  `syncInProgress` guard each is how double-crawls happen.
+- `downloads` has a relaxed FK to `items` (migration 005). Verify the deletion
+  sweep's interaction with it before enabling the sweep, and check whether
+  `parent_id`'s `ON DELETE CASCADE` reaches further than intended.
+- The existing 100 ms `cache_with_timeout` in `hybrid.rs` returns *empty* on
+  timeout rather than erroring. Once the cache leg is the primary path, that
+  budget may need raising — an FTS query over a large catalog on cold page cache
+  can exceed it, and the failure mode is a silently empty result.
+- Keep `SearchScope` semantics as-is: `All => None` (no filter), deliberately
+  not a union, so People and folders are not filtered out (DR-063).
+- Noted but deliberately not fixed here: `pushCatalogVisibility` in
+  `offlineCatalog.ts` derives the flag as `connected || showCatalog` — the
+  frontend computing an availability *policy*, even though the flag itself is
+  Rust-stored. DR-108 depends on that derivation being correct and it is, so
+  this spec leaves it alone. Once DR-109 has moved sync policy into Rust, the
+  derivation belongs there too, with the frontend pushing only the raw user
+  toggle. Folding it into this change would enlarge the diff for no behavioural
+  gain — but do not add *new* policy on the frontend side of that line.

docs/specs/downloads-as-offline-library.md

@@ -0,0 +1,166 @@
+# Spec: Downloads as a browsable offline library
+
+**Status:** Draft — ready to implement
+**Scope:** Frontend-heavy; one new repository-client browse path. Minimal Rust.
+**Requirements:** UR-055 → DR-081, DR-082, DR-083, DR-084; UR-056 → DR-085
+(see [requirements.md](../requirements.md)).
+**UX spec:** [ux-flows.md §7.2–7.7](../ux-flows.md).
+
+## Summary
+
+Replace the flat Active/Completed download list with two views under
+`/downloads`:
+
+1. **Downloaded** (default) — the library, filtered to what's on the device,
+   using the *same* browse screens as online (grids, cards, detail pages).
+2. **Transfers** — the existing progress-row list, demoted to a secondary tab,
+   showing only in-flight transfers.
+
+Plus per-item disk usage (UR-056) shown in familiar units on cards, detail
+pages, a device total, and the remove confirmation.
+
+## Motivation
+
+A user who downloaded three seasons and two albums sees ~70 individual transfer
+rows today, with no grouping and no reuse of the library UI. "What do I have
+offline" and "what is downloading" are different questions crammed into one flat
+list. Browsing offline should feel exactly like browsing online.
+
+## Background: verified current state
+
+1. **The offline repository is already a browsable tree.**
+   [offline.rs](../../src-tauri/src/repository/offline.rs) — `get_items` returns
+   downloaded items **plus** containers (MusicAlbum, Series, Season) that have at
+   least one downloaded child. `get_libraries`, `get_item`, and `search` all
+   filter to downloaded content via CTEs. This is the data source for
+   Downloaded; **do not build a new query layer.**
+
+2. **The client cannot reach it independently.**
+   [repository-client.ts](../../src/lib/api/repository-client.ts) `getItems` →
+   `repositoryGetItems` always goes through the **hybrid** repository
+   ([hybrid.rs](../../src-tauri/src/repository/hybrid.rs)), which merges cache and
+   server. There is no "offline only" browse path exposed. This is the one real
+   backend gap (DR-082).
+
+3. **Downloads page is a flat two-tab list.**
+   [downloads/+page.svelte](../../src/routes/downloads/+page.svelte) — Active /
+   Completed tabs, one `DownloadItem` row per transfer, no browsing.
+
+4. **Library browse components are reusable as-is.** `LibraryGrid`, `MediaCard`,
+   the `/library/[id]` detail page (§5A/§5B) render whatever items they are
+   given. Downloaded browse is those components with an offline-scoped source.
+
+5. **A related fallthrough bug is already tracked** (DR-080, another session):
+   `HybridRepository::get_items` treats an empty offline result as a cache miss
+   and falls through to the server. The offline-only browse path (DR-082) must
+   **not** share that behaviour — an empty result there is authoritative "nothing
+   downloaded here."
+
+6. **Concurrency, the 3-download cap, and the auto-pump are backend concerns.**
+   Do not surface them as manual controls; do not loop `startDownload` from the
+   frontend (see [CLAUDE.md](../../CLAUDE.md) gotchas).
+
+## Design
+
+### View split (DR-081)
+
+`/downloads` renders a **Downloaded** / **Transfers** switch. Downloaded is the
+default. Transfers shows a count/badge only while transfers are active.
+Initiating downloads stays on item/album/series detail pages (§7.1) — this page
+does not start downloads.
+
+### Offline-scoped browse source (DR-082, DR-083)
+
+Add an explicit offline-only browse path so Downloaded never merges server
+results and never depends on reachability. Two viable shapes — pick per the
+codebase, do not do both:
+
+- **(a)** A dedicated command (e.g. `repository_get_downloaded_items` /
+  `_libraries`) that calls the offline repository directly, with a matching
+  client method; or
+- **(b)** An explicit `offlineOnly`/scope flag on the existing get-items path
+  that bypasses the hybrid merge and the empty→fallthrough behaviour.
+
+Either way: an empty result is authoritative (do **not** reuse the DR-080
+fallthrough), and the path is available while the server is reachable (a user
+online still wants to browse their downloads).
+
+Downloaded then reuses `LibraryGrid` / `MediaCard` / the detail page against this
+source. Omit libraries and containers with no downloaded content. Badge
+partially- vs fully-downloaded containers. Play uses the local file; remove is
+available at item / album / season / series level and removes a container from
+the browse when its last downloaded child goes.
+
+### Transfers view (DR-084)
+
+The existing list, filtered to in-flight rows only: downloading (with progress),
+queued, paused, failed, waiting-for-WiFi (the DR-074 state from the other
+session). Controls: Pause / Resume / Cancel / Retry. Completed transfers leave
+this view — they appear in Downloaded. Empty state points at the library.
+
+### Disk usage (DR-085, UR-056)
+
+- **Source the bytes from the download manager** — it writes the files and can
+  stat them. Aggregate to album/season/series subtotals and a device total.
+  This is display + aggregation, **not** new tracking.
+- **Format once, consistently.** One shared formatter, human units, 2–3
+  significant figures (`1.2 GB`, `340 MB`). Binary vs decimal — pick one and use
+  it everywhere.
+- **Surface it in familiar places:** a secondary size label on the card and
+  detail page; a device total at the top of Downloaded (`3.4 GB · 12 items`)
+  that reconciles with the listed sum; a reclaim figure in the remove
+  confirmation ("frees 1.2 GB"). No separate "storage report" screen.
+- Sort/filter by size is a nice-to-have, not required for v1.
+
+## Out of scope
+
+- Changing download initiation, the 3-concurrent cap, or the auto-pump.
+- The catalog-browse / show-server-catalog toggle (UR-052, another session) —
+  that governs the *online offline-fallback* library; this is the dedicated
+  Downloads surface. They should be consistent but are separate work.
+- Fixing the DR-080 hybrid fallthrough bug (owned elsewhere) — just don't depend
+  on that behaviour here.
+
+## Acceptance criteria
+
+- [ ] `/downloads` opens on Downloaded and can switch to Transfers.
+- [ ] Downloaded lists only libraries/containers with downloaded content, using
+      the same grids/cards/detail pages as online browsing.
+- [ ] Browsing Downloaded never shows non-downloaded server items, online or off.
+- [ ] An empty Downloaded result reads as "nothing downloaded," never falls
+      through to the server.
+- [ ] Play from Downloaded plays the local file.
+- [ ] Remove works at item/album/season/series level and updates the browse.
+- [ ] Transfers shows only in-flight rows with working controls; finished
+      transfers move to Downloaded.
+- [ ] Each downloaded item/container shows its on-disk size; a device total is
+      shown and reconciles with the sum; remove states the reclaim amount.
+- [ ] `bun run check`, `bun run test`, and (if Rust touched) `cargo test` +
+      `cargo clippy` pass.
+
+## Testing
+
+- Repository client: the offline-only browse path returns downloaded content and
+  its containers, and an empty result does **not** trigger server fallthrough.
+- Downloaded view: libraries/containers with no downloads are omitted;
+  partial/full container badging.
+- Transfers: only in-flight statuses render; a completed transfer disappears.
+- Size formatter: rounding and unit thresholds; subtotal aggregation; device
+  total reconciles with listed items.
+- If a Rust command is added, add the tauri IPC param-naming coverage per
+  [CLAUDE.md](../../CLAUDE.md) (camelCase rule).
+
+New requirement-implementing code needs `TRACES:` comments. Suggested tags:
+view split `UR-055 | DR-081`; offline browse path `UR-055 | DR-082, DR-083`;
+Transfers `UR-055 | DR-084`; size display `UR-056 | DR-085`.
+
+## Notes for the implementer
+
+- Read [ux-flows.md §7.2–7.7](../ux-flows.md) first — behavioural spec; this is
+  the implementation plan.
+- The offline repository already does the hard part. The main work is a clean
+  offline-only client path and reusing the library components — resist
+  rebuilding browse UI.
+- Another session is active in downloads/offline/connectivity code (DR-074,
+  DR-078–080). Coordinate on [downloads/+page.svelte](../../src/routes/downloads/+page.svelte)
+  and the repository layer; check `git diff` before repairing unexpected changes.

docs/specs/favorites-browsing.md

@@ -0,0 +1,403 @@
+# Spec: Favourites — marking, browsing, and sync
+
+**Status:** Implemented
+**Requirements:** UR-067, UR-068, UR-069 → DR-113 … DR-120; JA-033, JA-034
+(allocated in [requirements.md](../requirements.md); tests UT-099 … UT-107).
+Note: UR-066/DR-112/IR-031 were claimed by the concurrent safe-area work while
+this spec was being written, so the ids here start one higher than first drafted.
+Existing: UR-017 → DR-021, JA-017, JA-018 (the toggle itself, already built).
+**UX spec:** [ux-flows.md](../ux-flows.md) §3.2 (full-player favourite), §5.2
+(album detail favourite), §5B.3 (movie detail hero: *Play / Download / Favorite*)
+— all three already specify favourite affordances that **do not exist in the
+build**. This spec closes those, and adds a new §5C for the Favourites browse
+surface.
+**Supersedes / revises:** nothing.
+
+## Summary
+
+JellyTau can favourite an item but can never show you what you favourited. The
+heart is mounted in exactly one place (the mini player), no query anywhere asks
+Jellyfin or the local database for favourites, and favourites marked on any other
+client are invisible here. This spec adds the read side (a Favourites page, home
+carousels, an in-library filter), puts the heart on detail pages and media cards,
+teaches the backend to ingest server-side favourite state, and drains favourite
+toggles made while offline.
+
+## Background: what exists today
+
+Verified in code, 2026-08-04. The **write** path is real and mostly correct; the
+**read** path does not exist at all.
+
+1. **Toggling works, from one place only.**
+   [FavoriteButton.svelte](../../src/lib/components/FavoriteButton.svelte) is
+   mounted solely in
+   [MiniPlayer.svelte:381](../../src/lib/components/player/MiniPlayer.svelte#L381).
+   Nothing else in `src/` renders it — so the only favouritable item in the app
+   is the one currently playing.
+
+2. **The toggle's plumbing is sound.**
+   [favorites.ts](../../src/lib/services/favorites.ts) writes local first
+   (`storage_toggle_favorite`,
+   [storage/mod.rs:908](../../src-tauri/src/commands/storage/mod.rs#L908) — sets
+   `user_data.is_favorite` + `pending_sync = 1`), then POST/DELETEs
+   `/Users/{uid}/FavoriteItems/{id}`
+   ([online.rs:1652](../../src-tauri/src/repository/online.rs#L1652)) only when
+   connected. Leave this design intact.
+
+3. **`MediaItem.user_data` is always `None` from the server.**
+   `JellyfinItem` has no `UserData` field, and `to_media_item` hardcodes
+   [`user_data: None`](../../src-tauri/src/repository/online.rs#L656) with the
+   comment *"User data not included in basic item responses"*. The only
+   populated `user_data` in the app comes from
+   [series_progress.rs](../../src-tauri/src/repository/series_progress.rs#L244)
+   and the local read in
+   [offline.rs:115](../../src-tauri/src/repository/offline.rs#L115). **Nothing
+   ingests server favourite state**, which is why the mini player has to fetch
+   `storageGetPlaybackProgress` per track to colour one heart
+   ([MiniPlayer.svelte:75-93](../../src/lib/components/player/MiniPlayer.svelte#L75-L93)).
+
+4. **No favourites query exists.**
+   [`GetItemsOptions`](../../src-tauri/src/repository/types.rs#L278) has no
+   favourites field; `Filters=IsFavorite` appears nowhere; no SQL selects
+   `is_favorite = 1`; there is no `/library/favorites` route and no favourites
+   carousel in [home.ts](../../src/lib/stores/home.ts).
+
+5. **Offline favourites are silently lossy.** Offline `mark_favorite` /
+   `unmark_favorite` are no-ops
+   ([offline.rs:1620](../../src-tauri/src/repository/offline.rs#L1620)), so an
+   offline toggle survives only as a local row with `pending_sync = 1` — and
+   **nothing ever drains that flag**. `syncService.queueFavorite`
+   ([syncService.ts:91](../../src/lib/services/syncService.ts#L91)) exists with
+   no callers.
+
+## Motivation
+
+Favouriting is a promise: the app takes the input and shows a "Added to
+favorites" toast, then discards it as far as the user can tell. Three of the UX
+flows already specify favourite buttons that were never built, and the one that
+was built (mini player) writes to a store nothing reads. Either the feature gets
+its read side or the heart should be removed — this spec takes the first option.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Favourites **scope** → set of Jellyfin item types | Rust | Domain taxonomy. Changes when Jellyfin adds/renames a type, never when the UI is redesigned. Reuses the canonical `SearchScope::item_types()` ([types.rs:324](../../src-tauri/src/repository/types.rs#L324)) — the exact leak class of [scoped-search-boundary.md](scoped-search-boundary.md). |
+| Cross-library favourites query (`Filters=IsFavorite`, `Recursive`, paging, sort field) | Rust | Query shaping against the Jellyfin API is domain logic; the endpoint's contract changes with the server, not the UI. |
+| Offline favourites SQL (join `user_data`, downloaded/catalog gating) | Rust | Storage + domain. Must obey the existing catalog-browse gate (DR-080) which the frontend cannot see. |
+| Deserialising Jellyfin `UserData` into `MediaItem.user_data` | Rust | Provider payload mapping. |
+| Mirroring server favourite state into the local `user_data` table | Rust | Cache/sync policy. |
+| Conflict rule: a local row with `pending_sync = 1` beats the server value | Rust | Business rule about which write wins; nothing to do with rendering. |
+| Draining pending favourite toggles on reconnect | Rust | Sync policy, and it must run whether or not any view is mounted — a frontend-driven drain dies with the component. Consistent with *reachability from real traffic* (DR-055). |
+| Which surfaces show favourites, tab order, row placement on home | Frontend | Pure presentation; changes only if the UI is redesigned. |
+| Heart placement, animation, toast, haptics, empty-state copy | Frontend | Presentation. |
+| In-session optimistic heart state shared across views | Frontend | View state, not persisted truth; the durable write already goes to Rust. |
+
+**Borderline, and the tie-breaker used:** *which* scopes appear as tabs (All /
+Movies / Shows / Music) is a presentation choice — the frontend picks which
+`SearchScope` values to offer. What each scope *means* is Rust's. The frontend
+sends the enum value and never names an item type in connection with favourites.
+Single-type pages (`itemType: "Movie"` on the Movies list page) stay as they are;
+this rule targets category taxonomy, not every mention of a type.
+
+## Design
+
+### 1. Server user data reaches `MediaItem` (Rust, DR-113, JA-034)
+
+Jellyfin returns `UserData` on `/Users/{uid}/Items*` responses. Add the field to
+`JellyfinItem` and map it in `to_media_item`, replacing the hardcoded `None`:
+
+```rust
+// in JellyfinItem
+#[serde(alias = "UserData")]
+pub user_data: Option<JellyfinUserData>,
+```
+
+`JellyfinUserData` deserialises `IsFavorite`, `Played`, `PlaybackPositionTicks`,
+`PlayCount`, `LastPlayedDate` into the existing
+[`UserData`](../../src-tauri/src/repository/types.rs#L44) type (which already
+carries `is_favorite` and already serialises camelCase, so `bindings.ts` needs no
+new type — only regeneration). Add `UserData` to the `Fields=` list in `get_items`
+/ `get_item` so the shape is explicit rather than relying on the default.
+
+Wire shape, unchanged from today's `UserData`:
+
+```ts
+item.userData?.isFavorite // boolean | null | undefined
+```
+
+Delete the now-false `// User data not included in basic item responses` comment.
+
+### 2. Local mirror of server favourites (Rust, DR-114)
+
+Choke point: `save_to_cache(parent_id, &items)` in
+[offline.rs](../../src-tauri/src/repository/offline.rs) — every server result
+that gets cached (including via
+[`cache_items_from_server`](../../src-tauri/src/repository/hybrid.rs#L124) and
+the background cache refresh) passes through it.
+
+For each item carrying `user_data.is_favorite`, upsert:
+
+```sql
+INSERT INTO user_data (user_id, item_id, is_favorite, synced_at, pending_sync)
+VALUES (?, ?, ?, ?, 0)
+ON CONFLICT(user_id, item_id) DO UPDATE SET
+  is_favorite = excluded.is_favorite,
+  synced_at   = excluded.synced_at
+WHERE user_data.pending_sync = 0;      -- local unsynced change wins
+```
+
+The `WHERE` on the conflict clause is the whole conflict rule: a toggle made
+offline is never overwritten by a stale server value before it has been pushed.
+
+### 3. Favourites queries (Rust, DR-115, DR-116, JA-033)
+
+**(a) In-library filter** — one new field on `GetItemsOptions`:
+
+```rust
+#[serde(skip_serializing_if = "Option::is_none")]
+pub favorites_only: Option<bool>,
+```
+
+- online `get_items`: append `&Filters=IsFavorite` when true.
+- offline `get_items`: add `INNER JOIN user_data ud ON ud.item_id = i.id AND ud.user_id = ? AND ud.is_favorite = 1`, composed with the existing `available_items` CTE so the downloads-only gate still applies.
+
+Frontend sends `{ favoritesOnly: true }` (camelCase — nested struct field, needs
+the existing `#[serde(rename_all = "camelCase")]` on `GetItemsOptions`, already
+present).
+
+**(b) Cross-library favourites** — a new trait method, because favourites span
+libraries and `get_items` is `ParentId`-shaped:
+
+```rust
+/// TRACES: UR-067 | DR-115 | JA-033
+async fn get_favorites(
+    &self,
+    scope: SearchScope,
+    options: Option<GetItemsOptions>,
+) -> Result<SearchResult, RepoError>;
+```
+
+```rust
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_favorites(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    scope: SearchScope,
+    options: Option<GetItemsOptions>,
+) -> Result<SearchResult, String>
+```
+
+Frontend call (command name matches the Rust fn exactly; top-level params
+auto-camelCase; `SearchScope` is `#[serde(rename_all = "camelCase")]` so the wire
+values are `"all" | "music" | "movies" | "tv"`):
+
+```ts
+await commands.repositoryGetFavorites(handle, "movies", { limit: 100 });
+```
+
+- **online**: `/Users/{uid}/Items?Filters=IsFavorite&Recursive=true&SortBy=SortName&SortOrder=Ascending` + `&IncludeItemTypes=…` from `scope.item_types()` (omit entirely on `None`, per that function's contract) + the standard `Fields=`.
+- **offline**: `items ⨝ user_data (is_favorite = 1)`, type filter from the same `scope.item_types()`, honouring `include_catalog_browse()`.
+- **hybrid**: same cache-first race as `get_items`, **including the DR-080 rule** — with the catalog-browse gate off, an empty offline result is authoritative and must not fall through to the server. Getting this wrong reproduces Defect B from [offline-downloaded-only-filter.md](offline-downloaded-only-filter.md).
+
+**The cache-first result arrives stale, and there is no second payload.** On a
+cache hit, `hybrid::get_items` returns the local rows and refreshes the cache in
+a background task whose result the frontend never sees — fine for a library
+listing that changes daily, wrong for favourites, where the *point* is that
+another client just changed something. Favourites is the second read path (after
+search) that needs the deferred update, so the background refresh in
+`get_favorites` must emit the same `favorites-changed` event as §4 when the
+server's favourite set differs from what was returned:
+
+```
+favorites-changed  →  { itemIds: string[] }   // union of ids whose is_favorite flipped
+```
+
+Both producers (background refresh, reconnect drain) emit the identical payload,
+and the frontend has one handler that refreshes the `favorites` store. Without
+this, a favourite marked on another client appears in JellyTau only on the
+*second* visit to the page.
+
+### 4. Draining offline toggles (Rust, DR-120)
+
+On the offline→online transition already detected by `ConnectivityMonitor`,
+select `user_data WHERE pending_sync = 1 AND is_favorite IS NOT NULL`, POST or
+DELETE `/Users/{uid}/FavoriteItems/{id}` per row, then set `pending_sync = 0` and
+`synced_at`. Failures leave the row pending for the next transition.
+
+Emit a kebab-case event when anything changed, so open views refresh without
+polling:
+
+```
+favorites-changed  →  { itemIds: string[] }
+```
+
+`syncService.queueFavorite` is dead code once this lands — delete it or point it
+at the backend drain; do not leave two competing queues.
+
+### 5. Frontend surfaces (DR-117, DR-118, DR-119)
+
+**Favourites page** — new route `/library/favorites`:
+- Scope tabs *All / Movies / Shows / Music* via the existing `LibraryViewTabs`; each tab sends a `SearchScope` value, nothing more.
+- Renders through `LibraryGrid` + `MediaCard` (tracklist for Music→tracks if the tab is later split; not in this pass).
+- Entry points: a card on the library overview ([library/+page.svelte](../../src/routes/library/+page.svelte)) and "See all" on the home rows.
+- Empty state per tab: "Nothing favourited yet — tap the heart on anything you like."
+
+**Home carousels** — `favoriteMovies`, `favoriteShows`, `favoriteMusic` added to
+[home.ts](../../src/lib/stores/home.ts), each `repositoryGetFavorites(scope, { limit: 20 })`,
+rendered after *Recently Added* and **only when non-empty** (no empty rows on a
+fresh install).
+
+**In-library filter** — a favourites toggle in the header of
+[GenericMediaListPage](../../src/lib/components/library/GenericMediaListPage.svelte)
+and the Movies/TV landing pages, passing `favoritesOnly: true` into the existing
+`repo.getItems(...)` options. Session-scoped state; not persisted (a persisted
+filter that hides most of a library is a support call waiting to happen).
+
+**Hearts** — mount `FavoriteButton`:
+- Movie / series detail hero button row, beside the download buttons ([library/[id]/+page.svelte:528-553](../../src/routes/library/%5Bid%5D/+page.svelte#L528-L553)) — closes ux-flows §5B.3.
+- `EpisodeFocusView`, `ArtistDetailView`, `PlaylistDetailView`, album detail — closes ux-flows §5.2.
+- `MediaCard` artwork overlay (top-right). Suppressed on `isServerOnly` cards, and must not fight the existing long-press/scroll-guard handlers ([MediaCard.svelte:60-70](../../src/lib/components/library/MediaCard.svelte#L60-L70)) — the heart is its own button and stops propagation.
+
+**Shared optimistic state** — a small `favorites` store (`Map<string, boolean>`
+overlay + `favorites.set(id, value)`), so un-hearting an item on the Favourites
+page removes it from the grid and from any home row without a refetch, and a
+heart tapped on a card is reflected on the detail page. Resolution order:
+
+```
+favorites store override  ??  item.userData?.isFavorite  ??  false
+```
+
+`toggleFavorite()` updates the store alongside its existing local + server
+writes; the `favorites-changed` event refreshes it. This removes the mini
+player's per-track `storageGetPlaybackProgress` fetch once items carry
+`userData`.
+
+### 6. Offline behaviour
+
+Toggling offline keeps working exactly as now (local write + `pending_sync`), and
+now actually reaches the server on reconnect (§4). The Favourites page offline
+shows favourites among downloaded/cached items, subject to the existing
+catalog-browse gate. The offline repo's no-op `mark_favorite`/`unmark_favorite`
+stay no-ops — the local write plus the drain is the offline path.
+
+## Out of scope
+
+- Favouriting people, genres, or collections; favourite **playlists** are included only insofar as they fall under the Music scope.
+- Sorting by "date favourited" — Jellyfin does not expose it. Favourites sort by name.
+- A dedicated bottom-nav tab for favourites (reachable from library overview + home).
+- Building a playlist or download batch from favourites.
+- Reconciling favourites for items that no longer exist on the server.
+- Splitting the Music tab into albums/artists/tracks sub-tabs.
+
+## Acceptance criteria
+
+- [ ] Favouriting is possible from movie, series, episode, album, artist and playlist detail pages, and from media cards in any grid.
+- [ ] A favourite marked in another Jellyfin client shows a filled heart in JellyTau without toggling it here.
+- [ ] `/library/favorites` lists favourites across libraries, filtered by the All/Movies/Shows/Music tabs.
+- [ ] Home shows favourite rows for movies, shows and music, and shows no row when a category has none.
+- [ ] Movies/TV/Music list pages can be filtered to favourites only.
+- [ ] Un-hearting an item on one surface updates the others without a manual refresh.
+- [ ] A favourite toggled while offline reaches the server after reconnect (verified against a real server or a fake repository).
+- [ ] Offline, the Favourites page respects the "Show all server media" gate — with it off, an empty result stays empty and does not fall through to the server.
+- [ ] No item-type set appears in `src/` in connection with favourites; the frontend sends `SearchScope` only.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes (necessary, not sufficient — see CLAUDE.md).
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated from Rust, not hand-edited.
+
+## Testing
+
+**🔴 §4 (the pending-sync drain) is a bug fix — failing test first.** Write a
+test that toggles a favourite with the repository offline, transitions to online,
+and asserts the server call happened; watch it fail before writing the drain.
+
+Rust (`cd src-tauri && cargo test`):
+
+| Test | Covers |
+|------|--------|
+| UT-099 | A Jellyfin item JSON fixture with `UserData.IsFavorite: true` maps to `MediaItem.user_data.is_favorite == Some(true)` |
+| UT-100 | `online::get_favorites` builds an endpoint with `Filters=IsFavorite`, `Recursive=true`, and the scope's `IncludeItemTypes`; `SearchScope::All` omits the type filter entirely |
+| UT-101 | `offline::get_favorites` returns only `is_favorite = 1` rows, respects the scope type filter, and returns nothing extra when the catalog-browse gate is off |
+| UT-102 | `save_to_cache` mirror does **not** overwrite a row with `pending_sync = 1` |
+| UT-103 | Drain pushes pending rows, clears `pending_sync`, sets `synced_at`, and leaves failed rows pending |
+| UT-104 | `get_items` with `favorites_only: true` filters both online (endpoint) and offline (SQL) |
+| UT-107 | The background refresh in `hybrid::get_favorites` emits `favorites-changed` with the flipped ids, and emits nothing when the server set matches the cache |
+
+Frontend (`bun run test`):
+
+| Test | Covers |
+|------|--------|
+| UT-105 | `favorites` store override precedence: store value beats `userData.isFavorite` beats `false` |
+| UT-106 | Un-hearting removes the item from a favourites list view (pure logic extracted to a `.ts` module, per the TrackList/episodeStrip pattern) |
+| IT-0xx | `repositoryGetFavorites` param naming — add to [tauriIntegration.test.ts](../../src/lib/utils/tauriIntegration.test.ts): camelCase top-level params, scope serialised as `"movies"` etc. |
+
+Any component logic worth testing gets extracted into a plain `.ts` module first
+(`favoritesView.ts`), rather than tested through the component.
+
+## TRACES
+
+| Piece | Tag |
+|-------|-----|
+| `JellyfinUserData` + `to_media_item` mapping | `// TRACES: UR-069 \| DR-113, JA-034 \| UT-099` |
+| `save_to_cache` user_data mirror | `// TRACES: UR-069 \| DR-114 \| UT-102` |
+| `get_favorites` (trait, online, offline, hybrid) + command | `// TRACES: UR-067 \| DR-115, JA-033 \| UT-100, UT-101` |
+| `GetItemsOptions.favorites_only` handling | `// TRACES: UR-067 \| DR-116 \| UT-104` |
+| `/library/favorites` route + tabs | `// TRACES: UR-067 \| DR-117` |
+| Home favourite carousels | `// TRACES: UR-067 \| DR-118` |
+| `FavoriteButton` mounts + `favorites` store | `// TRACES: UR-068 \| DR-119 \| UT-105, UT-106` |
+| Pending-favourite drain + `favorites-changed` | `// TRACES: UR-069 \| DR-120 \| UT-103` |
+
+New requirement rows to add to [requirements.md](../requirements.md):
+
+- **UR-067** — Browse favourited media across libraries (page, home rows, in-library filter).
+- **UR-068** — Mark/unmark favourites from browse and detail surfaces, not only the player.
+- **UR-069** — Favourite state stays consistent with the server in both directions.
+- **DR-113 … DR-120** — as tabled above.
+- **JA-033** — Query favourite items (`Filters=IsFavorite`).
+- **JA-034** — Read `UserData` from item responses.
+
+## Implementation notes (as built)
+
+Two things landed differently from the design above, both forced by where the
+`AppHandle` lives:
+
+1. **The `favorites-changed` event is emitted from the command layer, not the
+   repository.** `HybridRepository` has no `AppHandle` — the same reason
+   `search-event` is emitted from `repository_search`. `repository_get_favorites`
+   therefore does the two-phase read itself (cache leg returned, server leg
+   spawned) and diffs the two id sets via `changed_favorite_ids`, which is
+   extracted and unit-tested (UT-107) rather than buried in the spawn.
+2. **The drain hooks the existing `connectivity:reconnected` event** via
+   `app.listen` in `commands/favorites.rs`, rather than reaching into
+   `ConnectivityMonitor` (which knows nothing about repositories). It drains
+   through a narrow `FavoriteSink` trait so it can be tested against a recording
+   double instead of a forty-method `MediaRepository` mock.
+
+3. **The command falls back to `HybridRepository::get_favorites` when nothing is
+   cached.** The two-phase read alone paints "Nothing favourited yet" on a fresh
+   install and corrects it a server round trip later, which is a wrong answer
+   shown to the user. An empty cache leg therefore defers to the repository's
+   own cache-first-then-server read. That read was also fixed to *save through*
+   on a server hit — without it the page re-queried the server on every visit
+   and the DR-114 mirror was never filled by this path.
+
+Also as built: `DatabaseService` is not object-safe (generic methods), so the
+drain takes `Arc<RusqliteService>` like the rest of the storage code, and
+`get_items`' endpoint construction was extracted to `build_get_items_endpoint`
+so the `favorites_only` filter could be asserted without an HTTP server.
+
+**Not built:** the full-player heart. ux-flows §3.2 lists one among the full
+player's secondary controls and it remains unbuilt — recorded as a known
+deviation in ux-flows §5C.5 rather than silently dropped.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before "repairing" unexpected changes.
+- Do **not** try to reuse `get_items` with an empty `ParentId` for cross-library favourites; that endpoint is built as `?ParentId={}` ([online.rs:731](../../src-tauri/src/repository/online.rs#L731)) and an empty value is not a reliable "all libraries" request. Use `get_favorites`.
+- `SearchScope` is reused rather than a new `FavoritesScope` so there is one taxonomy expansion in the codebase, not two that can drift. If the name grates once favourites ship, rename the type across search + favourites in one commit — don't fork it.
+- `SearchScope::All` returns `None` from `item_types()` **on purpose**; callers must omit `IncludeItemTypes` entirely rather than sending a union (see the doc comment at [types.rs:316](../../src-tauri/src/repository/types.rs#L316)).
+- Ship order that keeps each step demonstrable: §1+§2 (state becomes visible) → §5 hearts (marking becomes possible) → §3+§5 browse surfaces (finding becomes possible) → §4 drain.
+- Regenerate `bindings.ts` after the Rust types change; never hand-edit it.

docs/specs/frontend-domain-model.md

@@ -0,0 +1,309 @@
+# Spec: Remove Jellyfin-specific models from the frontend
+
+> **Implementation status (branch `frontend-domain-model`, worktree
+> `../JellyTau-domain-model`):** Catalog surface **done**. The frontend's *item
+> classification* and *time units* no longer speak Jellyfin:
+> - `domain/` module is the single source of truth; `MediaKind` enum + isolated
+>   `from_jellyfin` mapping. The model gained real distinctions the flat
+>   `item_type` had hidden: `LiveChannel` / `ChannelItem` / `Channel`.
+> - Every catalog `item.type === "..."` → `item.kind` (0 remaining in `src/`).
+> - Catalog ticks → milliseconds (`durationMs`, `playbackPositionMs`);
+>   `formatDuration` takes ms; progress bars are unit-consistent.
+> - User-facing type badge → `kindLabel()`.
+> - Old Jellyfin-named fields remain **dual-carried** on the wire so nothing broke.
+>
+> **Deferred (tracked, not done):**
+> - `primaryImageTag` → `imageId` rename (naming-only; ~40 sites across catalog +
+>   `PlayerMediaItem`/`MergedMediaItem`, the latter needing a Rust `image_id`
+>   round-trip). Catalog `MediaItem` already has `imageId`.
+> - Player/session/reporting tick math (`Queue`, `SessionCard`, `RemoteControls`,
+>   `playbackReporting`, `playerEvents`) — crosses storage/Jellyfin *command
+>   signatures* in ticks; needs those commands to accept ms (phase 4).
+> - `stream.type` (`mediaStreams[].type`) — Jellyfin stream vocabulary (phase 4).
+> - Delete `playbackUnits.ts` / `jellyfinFieldMapping.ts` once their last
+>   consumers migrate; drop the dual-carried fields once nothing reads them.
+
+**Status:** Partially implemented (catalog surface); see banner.
+**Requirements:** Architectural (boundary integrity — CLAUDE.md core principles).
+Allocate new DRs on acceptance; suggested: DR for the domain `MediaItem`/`MediaKind`
+type, DR for tick/image-tag hoisting, DR for the phased frontend migration
+(see [requirements.md](../requirements.md)). Relates to UR-007, UR-008, UR-034.
+**UX spec:** n/a — zero user-visible behaviour change. This is a pure
+architecture/boundary migration.
+**Supersedes / revises:** none. Extends the boundary work started in
+[scoped-search-boundary.md](scoped-search-boundary.md) from *taxonomy* to the
+*whole media model*.
+
+## Summary
+
+The frontend currently consumes Jellyfin's data model directly: `MediaItem` is a
+Jellyfin DTO (`runTimeTicks`, `primaryImageTag`, `parentIndexNumber`, a
+stringly-typed `type: string` carrying Jellyfin's item vocabulary), mirrored via
+specta into **36+ frontend files**, with **127 `item.type === "…"` string
+comparisons across 23 files** and two frontend utility modules
+(`playbackUnits.ts`, `jellyfinFieldMapping.ts`) doing Jellyfin-specific unit and
+field conversion in the presentation layer.
+
+This spec defines a **provider-neutral domain model**, owned by Rust, that the
+Jellyfin repository maps *into*. The frontend consumes only that model. When done,
+no Jellyfin vocabulary — item-type strings, ticks, image tags, Jellyfin field
+names — remains in `src/`.
+
+## Motivation
+
+Two concrete problems, one strategic:
+
+1. **Boundary violation at scale.** Per CLAUDE.md, the frontend is
+   presentation-only and Rust owns the domain. Today the *domain model itself* is
+   Jellyfin's wire shape, propagated unchanged across IPC. The frontend knows what
+   a "tick" is, what `primaryImageTag` means, and that `"Audio"` is a track. That
+   is domain knowledge in the wrong layer, 36 files deep.
+2. **Fragility.** `type: string` is unchecked: a typo (`"Epis0de"`) or a Jellyfin
+   rename fails silently at runtime with no compiler help, across 127 sites. Tick
+   math (`* 10_000_000`) duplicated frontend-side is a class of bug the backend
+   should have already resolved.
+3. **Strategic (the reason we chose the ambitious target):** a neutral domain
+   model is the precondition for **ever supporting a non-Jellyfin backend** (Plex,
+   local files, Subsonic). As long as the UI speaks Jellyfin, that door is welded
+   shut.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Definition of the media domain model (`MediaItem`, `MediaKind`) | **Rust** | The canonical shape the whole app reasons about; must not be a provider's wire format. |
+| Jellyfin DTO → domain mapping (ticks→ms, image tag→url/id, `"Audio"`→`Track`, `PremiereDate`→`releaseDate`) | **Rust**, in the Jellyfin repository | Provider-specific translation; changes if Jellyfin changes; is the definition of "how Jellyfin maps to our domain." |
+| Tick arithmetic (`playbackUnits.ts`) | **Rust** | A Jellyfin unit. The frontend should never see ticks; it receives `durationMs`/`positionMs`. |
+| Sort-field mapping (`jellyfinFieldMapping.ts`, `title→SortName`) | **Rust** | Maps neutral sort keys to Jellyfin query fields — provider vocabulary. Frontend sends a neutral `SortKey`. |
+| `MediaKind` classification (is this a track / album / episode?) | **Rust** | Derived from Jellyfin's `item_type`; the frontend receives the already-classified kind. |
+| Choosing which kind renders as a card vs a list row; grid/list toggle; group order | **Frontend** | Pure presentation over the neutral `kind`. Changes only if the UI is redesigned. |
+| Navigation decisions (`kind === Track && albumId` → go to album) | **Frontend** | Presentation/routing over neutral fields. |
+
+**Borderline calls, resolved:**
+
+- *`MergedMediaItem`* (the lightweight now-playing projection) is already
+  half-neutral (`title`, `artist`, `duration`) — it becomes a straightforward
+  subset of the new domain model, not a special case.
+- *Context discriminators* `"album"`, `"playlist"`, `"remote"` (in `TrackList`,
+  playback context, sessions) are **already domain-neutral** — they are *our*
+  vocabulary, not Jellyfin's. They stay as-is; do not confuse them with
+  `item_type`. Only the Jellyfin item-type strings move.
+- *`mediaStreams[].type === "Audio"/"Subtitle"/"Video"`* (track selection in
+  VideoPlayer) is Jellyfin stream vocabulary too, but is lower-risk and
+  self-contained — deferred to a late phase, not phase 1.
+
+## Design
+
+### Single canonical model, one location, isolated mappings
+
+The domain model is defined **once**, in a dedicated top-level Rust module
+`src-tauri/src/domain/`, and is the single source of truth shared across the
+whole app:
+
+```
+src-tauri/src/domain/
+  media.rs         canonical MediaItem, MediaKind, and the other media types
+  from_jellyfin.rs Jellyfin DTO -> domain mapping, ISOLATED here
+  mod.rs           re-exports
+        |  tauri-specta (export_typescript_bindings test)
+        v
+  src/lib/api/bindings.ts   generated MediaItem/MediaKind — the frontend copy
+```
+
+- **One definition.** `domain::MediaItem` is *the* model. Rust (repositories,
+  player, downloads) uses it directly. The frontend uses the generated `bindings.ts`
+  projection of it. There is no second hand-written copy in either language, so it
+  cannot drift — "shared between frontend and backend" is realized by generation,
+  not duplication.
+- **Mappings live beside the model, never in consumers.** All provider translation
+  (`JellyfinItem` → `domain::MediaItem`, ticks→ms, image-tag→id, item-type→`MediaKind`)
+  lives in `domain/from_jellyfin.rs`. It is the *only* place Jellyfin vocabulary
+  touches the domain type. Adding a second provider later means a new
+  `from_<provider>.rs` beside it — the model and every consumer stay untouched.
+- **`domain` is a top-level module** (not under `repository/`) because `MediaItem`
+  is used by `player/`, `download/`, and `playback_mode/` too — it is not
+  repository-specific.
+- The existing `JellyfinItem` DTO + `to_media_item()` in
+  [online.rs](../../src-tauri/src/repository/online.rs) is the seam that already
+  exists; it **moves** into `domain/from_jellyfin.rs` and is enriched to do real
+  translation instead of copying `item_type` through.
+
+### The domain model (Rust)
+
+```rust
+// src-tauri/src/domain/media.rs — provider-neutral. NO Jellyfin vocabulary.
+#[derive(specta::Type, Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub enum MediaKind {
+    Track, Album, Artist, Playlist,          // music
+    Movie, Series, Season, Episode,          // video
+    Person,                                  // cast/crew
+    Channel, Folder,                         // containers/live
+}
+
+#[derive(specta::Type, Serialize, Deserialize, Clone, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct MediaItem {
+    pub id: String,
+    pub name: String,
+    pub kind: MediaKind,          // was: type: String
+    pub is_folder: bool,
+    pub server_id: String,
+
+    // Times in milliseconds — NEVER ticks.
+    pub duration_ms: Option<i64>,        // was: run_time_ticks
+
+    // Image as a resolved identifier the frontend turns into a URL via the
+    // existing image command — no raw Jellyfin tag semantics leak.
+    pub image_id: Option<String>,        // was: primary_image_tag
+    pub backdrop_image_ids: Option<Vec<String>>,
+
+    pub overview: Option<String>,
+    pub genres: Option<Vec<String>>,
+    pub production_year: Option<i32>,
+    pub release_date: Option<String>,    // was: premiere_date (ISO-8601)
+    pub community_rating: Option<f64>,
+    pub official_rating: Option<String>,
+
+    // Relationships — already neutral, kept.
+    pub album_id: Option<String>, pub album_name: Option<String>,
+    pub album_artist: Option<String>, pub artists: Option<Vec<String>>,
+    pub artist_items: Option<Vec<ArtistItem>>,
+    pub series_id: Option<String>, pub series_name: Option<String>,
+    pub season_id: Option<String>, pub season_name: Option<String>,
+
+    // Ordinal position — rename off Jellyfin's index vocabulary.
+    pub track_number: Option<i32>,       // was: index_number
+    pub disc_number: Option<i32>,        // was: parent_index_number
+
+    pub user_data: Option<UserData>,
+    pub media_streams: Option<Vec<MediaStream>>,
+    pub media_sources: Option<Vec<MediaSource>>,
+    pub people: Option<Vec<Person>>,
+}
+```
+
+The existing `JellyfinItem` DTO (already defined in `online.rs`, deserialized
+from the Jellyfin JSON) **moves into `domain/from_jellyfin.rs`** and stays
+private to that module. Its `to_media_item()` — today a near-passthrough that
+copies `item_type` straight across — is enriched into the single, tested place
+that:
+
+- classifies `item_type: String` → `MediaKind` (including the edge cases found in
+  the audit: `"ChannelFolderItem"` → `Channel`/`Folder` by `is_folder`,
+  `"TvChannel"` → `Channel`, `"Composer"/"Director"/"Writer"` → `Person`,
+  `"Video"` → `Movie` or a video leaf). Unknown strings map to `Folder` or a new
+  `Other` variant — **decide at implementation; must not panic.**
+- converts `run_time_ticks` → `duration_ms` (`ticks / 10_000`).
+- maps `PremiereDate` → `release_date`, image tags → image ids.
+
+`SortKey` enum + its Jellyfin field mapping (`jellyfinFieldMapping.ts` contents)
+moves into the Jellyfin repository; the command takes a neutral `SortKey`.
+
+### 🔴 The `search-event` / dual-payload rule applies again
+
+Every path that returns `MediaItem` — command returns **and** the `search-event`
+and any other event payloads — emits the new domain shape. Both sides of a
+twice-delivered result must match (same rule as
+[scoped-search-boundary.md](scoped-search-boundary.md)). Grep for `MediaItem` in
+event definitions before declaring a phase done.
+
+### Frontend after
+
+- `MediaItem`/`MediaKind` come from generated `bindings.ts`.
+- `item.type === "Audio"` → `item.kind === "track"` (127 sites, mechanical).
+- `runTimeTicks` usages → `durationMs`; **delete `playbackUnits.ts`** (ticks no
+  longer cross the boundary; keep only any purely-display seconds↔clock helpers if
+  they exist, which are not Jellyfin-specific).
+- `primaryImageTag` → `imageId` through the existing image-URL command.
+- **Delete `jellyfinFieldMapping.ts`**; sort options send a neutral `SortKey`.
+- Assert with the boundary tripwire + a new grep (see acceptance).
+
+## Phased migration
+
+This is too large and too collision-prone for one change. Phases are independently
+shippable, each keeps all tests green, and each is a reviewable PR:
+
+1. **Establish the `domain/` module + enriched mapping, tests — no frontend
+   change yet.** Create `src-tauri/src/domain/{media,from_jellyfin,mod}.rs`. Move
+   `JellyfinItem`/`to_media_item` in. Add `MediaKind` and the neutral fields to
+   `domain::MediaItem` as *additive, defaulted* fields, and populate them in the
+   mapping, while **keeping the old Jellyfin-named fields too** (dual-carry). The
+   wire shape is a superset of today's, so the frontend still compiles and
+   behaves identically. Lands the authority + full mapping unit coverage first,
+   with zero blast radius on the 52 construction sites (they set the old fields;
+   new ones default).
+2. **Flip the wire shape.** Commands + events emit the new `MediaItem`.
+   Regenerate `bindings.ts`. Frontend breaks to compile errors — fix them
+   mechanically (`type`→`kind`, values `"Audio"`→`"track"`, `runTimeTicks`→
+   `durationMs`, `primaryImageTag`→`imageId`). This is the big mechanical PR;
+   `bun run check` is the driver.
+3. **Delete the frontend conversion helpers** (`playbackUnits.ts` ticks,
+   `jellyfinFieldMapping.ts`) and route sorting through the neutral `SortKey`.
+4. **Stream vocabulary** (`mediaStreams[].type`) and any remaining stragglers;
+   tighten the boundary check to forbid Jellyfin item-type strings in `src/`
+   outside tests.
+
+Ship 1 → 2 → 3 → 4 as separate PRs. Do **not** attempt all four at once.
+
+## Out of scope
+
+- Actually adding a second backend (Plex/Subsonic). This spec only *unblocks* it.
+- Changing any user-visible behaviour, layout, or copy.
+- The player-internal `PlayerMediaItem` / `MediaSessionType` shapes, except where
+  they carry the fields being renamed — align them in phase 2 only if the compiler
+  demands it.
+- Context discriminators (`"album"`, `"playlist"`, `"remote"`) — already neutral.
+
+## Acceptance criteria
+
+- [ ] No Jellyfin item-type string (`"Audio"`, `"MusicAlbum"`, `"Series"`, …) is
+      compared against `.type`/`.kind` anywhere in `src/` (outside tests). Verify:
+      `grep -rIn '\.kind === "\(Audio\|MusicAlbum\|MusicArtist\|Series\|Episode\|Movie\|Playlist\)"' src/` returns nothing.
+- [ ] No `Ticks`, `runTimeTicks`, `primaryImageTag`, `PremiereDate`, or Jellyfin
+      sort-field name (`SortName`, `RunTimeTicks`, …) appears in `src/` outside
+      tests. `playbackUnits.ts` (ticks) and `jellyfinFieldMapping.ts` are deleted.
+- [ ] `MediaItem`/`MediaKind`/`SortKey` in the frontend come from `bindings.ts`.
+- [ ] The `From<JellyfinMediaDto>` mapping is total and never panics on an unknown
+      item type (Rust test with a garbage type string).
+- [ ] Behaviour is identical: same library/search/home rendering, same sorting,
+      same navigation, offline included.
+- [ ] Both command returns and event payloads carry the new shape (no flicker).
+- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass;
+      `cargo fmt`/`cargo clippy`/`bun run test:rust` pass; `bindings.ts` regenerated.
+
+## Testing
+
+**Rust** (`cargo test`): the `From<JellyfinMediaDto> for MediaItem` mapping is the
+critical surface —
+- every known `item_type` → correct `MediaKind` (table test over all 20 values
+  found in the audit, incl. `ChannelFolderItem`, `TvChannel`, `Composer`);
+- unknown type string → safe fallback, no panic;
+- `run_time_ticks` → `duration_ms` (10_000 divisor), boundary/None cases;
+- `SortKey` → Jellyfin field mapping (port `jellyfinFieldMapping.ts`'s cases).
+
+**Frontend** (vitest): update the many tests asserting `.type`/`runTimeTicks`;
+they become `.kind`/`durationMs`. `jellyfinFieldMapping`/`playbackUnits` tests are
+deleted with their modules. Add a compose/render test proving `kind`-based
+branching matches the old `type`-based branching for a representative mix.
+
+## TRACES
+
+Per [CLAUDE.md](../../CLAUDE.md): the domain type + mapping
+`UR-007, UR-008 | <new DR>`; the tick/field hoist `<new DR>`; frontend migration
+phases share the DRs of the capability each touches (don't invent per-file DRs).
+
+## Notes for the implementer
+
+- **This is the highest-collision change in the repo's history** — it touches 36+
+  frontend files and the core Rust types. A parallel Claude session in any media
+  file will conflict. Strongly prefer a dedicated worktree per phase, and
+  `git diff` before repairing anything (CLAUDE.md gotchas / project memory).
+- Phase 1 deliberately maps *back* to the old shape so it can land safely ahead of
+  the disruptive flip. Resist the urge to skip it.
+- IPC camelCase rules apply to the new enums/structs
+  ([04-type-sync-and-threading.md](../architecture/04-type-sync-and-threading.md)):
+  `#[serde(rename_all = "camelCase")]`; tagged-enum tag convention; regenerate
+  `bindings.ts`, never hand-edit.
+- Reviewed against [SPEC-REVIEW-CHECKLIST.md](SPEC-REVIEW-CHECKLIST.md) — the
+  Layer assignment table above is the load-bearing section.

docs/specs/libmpv2-migration.md

@@ -0,0 +1,169 @@
+# Spec: Migrate to libmpv2 and declare the project licence
+
+**Status:** Proposed
+**Requirements:** UR-003 → IR-003 (revises the MPV integration); no new user-facing behaviour
+**UX spec:** n/a
+**Supersedes / revises:** dependency and licensing housekeeping identified in [playback-backend-unification.md](playback-backend-unification.md)
+
+## Summary
+
+Two related pieces of housekeeping that block or complicate later work:
+
+1. Replace the abandoned `libmpv` crate (pinned to a git branch) with the
+   maintained `libmpv2`.
+2. Add a `LICENSE` file. The project has none, which leaves its legal status
+   undefined while it links GPL-licensed libmpv.
+
+Neither changes user-visible behaviour. Both are prerequisites for
+[windows-native-audio-backend.md](windows-native-audio-backend.md).
+
+## Motivation
+
+### The dependency is dead
+
+```toml
+# src-tauri/Cargo.toml
+libmpv = { git = "https://github.com/ParadoxSpiral/libmpv-rs.git", branch = "master" }
+```
+
+- crates.io `libmpv` 2.0.1 was published **2020-09-29**.
+- The upstream repo's last commit was **2023-01-08**; nothing since was released.
+- We pin a git *branch*, so builds are not reproducible — the same lockfile-less
+  checkout can resolve differently over time, and CI has no protection if the
+  branch moves or the repo disappears.
+
+`libmpv2` (kohsine/libmpv2-rs) is a maintained fork of exactly this crate:
+6.0.0 released **2026-05-12**, ~23.5k recent downloads against the original's
+~1.1k, releases roughly quarterly since 2024.
+
+### The project has no licence
+
+There is no `LICENSE`/`COPYING` file and `src-tauri/Cargo.toml` has no `license`
+field. The project is open source and will never be commercial, so this is purely
+an omission — but it matters because we link libmpv, and "no licence" defaults to
+*all rights reserved*, which is incompatible with distributing a GPL-derived
+work.
+
+## Design
+
+### Part 1 — licence
+
+**Use GPLv3.** This is forced, not chosen:
+
+- mpv's default build is **GPLv2-or-later**, so the combined work must be
+  GPL-compatible.
+- Apache-2.0 is **GPLv2-incompatible** (patent-termination and indemnification
+  clauses) but GPLv3-compatible.
+- A scan of the dependency tree found Apache-2.0-**only** crates with no
+  alternative arm — most importantly **`tao`** (Tauri's own windowing crate),
+  plus `sync_wrapper`, `gethostname`, and `ring` (Apache-2.0 AND ISC).
+
+`tao` is unavoidable in a Tauri app, so GPLv2 is unavailable. Exercising mpv's
+"or later" option puts the combination at **GPLv3**.
+
+Actions:
+- Add `LICENSE` containing the GPLv3 text.
+- Add `license = "GPL-3.0-or-later"` to `src-tauri/Cargo.toml` and `license` to
+  `package.json`.
+- Note in the README that the binary links libmpv (GPLv2+) and FFmpeg.
+
+Because the project is open source, we use mpv's **default GPL build** — no
+`-Dgpl=false`, no LGPL FFmpeg build, and none of the LGPL §6 relinking analysis
+that a proprietary app would need. We keep VAAPI/VDPAU/X11 and every GPL FFmpeg
+filter.
+
+🔴 Never build FFmpeg with `--enable-nonfree` — that produces a binary that is
+**unredistributable under any licence**, open source or not.
+
+### Part 2 — libmpv → libmpv2
+
+```toml
+# Linux (and later Windows, per the Windows audio spec)
+libmpv2 = "=6.0.0"
+```
+
+Pin exactly: `libmpv2` has broken its API in **every** major release.
+
+Breaking changes to expect, from the changelog:
+
+| Version | Change | Impact here |
+|---|---|---|
+| 4.0.0 | Removed command helper methods — call `mpv.command(...)` directly | Low; we already use `command`/`set_property` |
+| 5.0.0 | Removed `mpv_node` support entirely (properties return strings; parse JSON yourself); `EventContext` folded into `Mpv`; `ProtocolContext` → `Protocol` | **Medium** — `start_event_loop` uses `create_event_context()`; check whether that call still exists |
+| 6.0.0 | `RenderContext::new()` → `Mpv::create_render_context()`; `'static` bound on `OpenGLInitParams`; render context now borrows `Mpv` (fixes a use-after-free) | **None** — we do not use the render API |
+
+The last row matters: we run mpv audio-only (`video = no`), so the entire render
+surface is irrelevant to us. Consider disabling the default `render` feature to
+reduce build surface.
+
+The main porting work is the event loop in `mpv_backend.rs` — `wait_event`,
+`disable_deprecated_events`, and the `FileLoaded` / `PlaybackRestart` /
+`PropertyChange` / `EndFile` handling, given 5.0.0 folded `EventContext` into
+`Mpv`.
+
+Everything else — `set_property` calls, the `af` filter graph, the 250ms position
+thread, the seek-suppression window — should port unchanged.
+
+## Layer assignment
+
+No logic moves. This is a dependency swap plus a licence file; the
+`PlayerBackend` trait boundary is untouched.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| mpv event → `PlayerStatusEvent` mapping | Rust (unchanged) | Already correct; only the binding API beneath it changes. |
+
+## Out of scope
+
+- Any behaviour change. If playback behaves differently after this, that is a bug.
+- Windows support — separate spec, but this must land first.
+- Adopting the render API. We are audio-only on mpv.
+- Re-licensing decisions beyond adding the file the project already implies.
+
+## Acceptance criteria
+
+- [ ] `LICENSE` (GPLv3) present; `license` field set in `Cargo.toml` and `package.json`.
+- [ ] A full dependency-licence audit has been run (`cargo install cargo-license && cargo license`) and confirms no GPLv3-incompatible dependency. *(The scan behind this spec resolved 441 of 575 crates from the local registry cache; the remaining 134 are unverified.)*
+- [ ] `libmpv` git dependency removed; `libmpv2` pinned to an exact version.
+- [ ] Linux audio playback works identically: play/pause/seek/volume, queue advance, gapless, EQ, normalization, sleep timer.
+- [ ] Position updates still arrive at 250ms; the 150ms post-seek suppression still prevents the jump-to-zero glitch.
+- [ ] `EndFile` still emits `PlaybackEnded` only for EOF (not STOP/QUIT/ERROR) — autoplay depends on this.
+- [ ] Builder image updated if the libmpv dev package requirement changed; **no toolchain install added to any CI step**.
+- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+
+## Testing
+
+The existing `mpv_backend_test.rs` plus the `build_af_filter`,
+`eq_filter_entries`, and `normalize_filter_entry` tests are the regression net —
+they must pass unchanged, since none of them touch the binding API.
+
+The event loop has no unit tests and is where the risk concentrates. Verify
+manually on Linux:
+
+1. Play → pause → play; confirm position does not flash to 0:00 (the known
+   playing-event regression).
+2. Seek mid-track; confirm no jump-to-zero within 150ms.
+3. Let a track end naturally; confirm autoplay advances (exercises `EndFile` EOF).
+4. Press stop; confirm autoplay does **not** advance.
+5. Sleep-timer expiry; confirm it stops without triggering autoplay.
+
+Cases 3–5 are the ones most likely to break silently, and each corresponds to a
+bug already fixed once in this codebase.
+
+## TRACES
+
+- `MpvBackend` construction / event loop → existing `// TRACES: UR-003 | IR-003`, unchanged
+- No new requirement IDs; this is a dependency migration.
+
+## Notes for the implementer
+
+- Do this **before** the Windows audio backend.
+- Read the 4.0/5.0/6.0 changelogs before writing code — the crate has broken API
+  in every major release, most recently two months before this spec.
+- The crates.io `repository` field for `libmpv2` points at `kohsine/libmpv-rs`,
+  but the repo was renamed to **`libmpv2-rs`**; the old raw URLs 404.
+- `libmpv2-sys` ships pregenerated bindings and vendored headers, so no libclang
+  is needed at build time — relevant to keeping the builder image thin.
+- A parallel Claude session may be active — `git diff` before "repairing"
+  unexpected changes.

docs/specs/library-mosaic.md

@@ -0,0 +1,125 @@
+# Spec: Library mosaic (library overview + home shortcuts)
+
+**Status:** Implemented
+**Requirements:** UR-075 → DR-174, DR-175 (with UR-067 → DR-117 extended)
+**UX spec:** [ux-flows.md](../ux-flows.md) §5C.2 (Favourites)
+
+## Summary
+
+The library overview and the home "Your Libraries" strip stop being fixed-shape
+grids and become a **mosaic**: rows share one height, and each tile is as wide as
+its own artwork is. A square music cover, a 16:9 library backdrop and a 2:3
+poster sit in the same row at their own proportions instead of all three being
+cropped into whichever box the grid picked. Favourites gain a tile per category,
+placed beside the library that category belongs to, alongside the existing
+cross-library entry.
+
+## Motivation
+
+Every surface here shows artwork of more than one shape. The grid resolved that
+by choosing one shape and cropping to it — and the home strip said so out loud:
+
+> Uniform 16:9 artwork so music (square) and video libraries line up at the same
+> height in this mixed row.
+
+Lining them up is right; cropping the covers to do it is not. Holding the
+**height** fixed and letting the **width** vary achieves the same alignment with
+no crop at all, which is the whole idea of a justified layout.
+
+Favourites had one entry for everything. With per-category tiles, "my favourite
+albums" is one tap from the library page rather than a tap plus a tab.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Collection type → favourites category (`movies` → Movies, `livetv` → none) | **Rust** | Jellyfin vocabulary. It changes when Jellyfin renames a collection type, never when this page is redesigned — the same test that put `SearchScope::item_types` in Rust. Shipping it in Svelte would have re-created the leak [scoped-search-boundary.md](scoped-search-boundary.md) exists to document. |
+| Which scopes exist at all (`SearchScope`) | **Rust** | Already there; unchanged. |
+| Row packing: heights, widths, justification, clamping | Frontend | Geometry of a rendered page. It changes when the layout is redesigned and never when the API does. |
+| Assumed artwork shape before the image loads (music = square, else wide) | Frontend | The shape of a *picture*, not a taxonomy — and it is only a starting guess, overruled by the decoded image. |
+| Tile labels, order, and showing a category's tile once | Frontend | Pure presentation: wording and placement. |
+
+Borderline row: the "assumed artwork shape" is a per-collection-type default, and
+any per-collection-type table deserves suspicion. The tie-breaker: it does not
+decide *what a category means* or what is fetched — it seeds a pixel dimension
+that the loaded bitmap immediately corrects. Getting it wrong costs one re-pack,
+not a wrong result. The scope mapping, which does decide what is fetched, went to
+Rust.
+
+## Design
+
+### Wire
+
+`Library` gains one optional field, derived at construction:
+
+```rust
+pub struct Library {
+    pub id: String,
+    pub name: String,
+    pub collection_type: String,
+    pub image_tag: Option<String>,
+    pub favorites_scope: Option<SearchScope>,   // ← new
+}
+
+impl SearchScope {
+    pub fn for_collection_type(collection_type: &str) -> Option<SearchScope>;
+}
+```
+
+```ts
+type Library = { …; favoritesScope?: SearchScope | null }
+```
+
+`Library::new` derives it, so the four construction sites (online views, two
+offline cache reads, tests) cannot forget it. `None` is *omitted* from the JSON,
+not sent as null. No new command, no new event.
+
+### Layout
+
+`src/lib/components/library/mosaic.ts` — pure, no DOM:
+
+- `layoutMosaic(items, { containerWidth, targetHeight, gap })` → rows of tiles
+  with pixel boxes. Tiles join a row until the height needed to fill the width
+  drops to the target; the row closes there and is justified to the container
+  width, the rounding remainder absorbed by its widest tile. The **last row is
+  not justified** (one leftover tile would inflate into a banner) — it sits at
+  the target height, left-aligned.
+- `layoutMosaicStrip(items, height)` → the same rule as one fixed-height row, for
+  a horizontally scrolling shelf.
+- `mosaicTargetHeight(containerWidth)` → the row height chosen when the caller
+  doesn't pick one. Bounded so a phone still fits two tiles across and a desktop
+  doesn't turn each library into a billboard.
+- Ratios are clamped to a band (0.5–2.5) so one panorama can't own a row.
+
+`MosaicGrid.svelte` supplies the two things only the DOM knows — the measured
+container width (`bind:clientWidth`) and the artwork's decoded ratio — and
+renders the caller's `tile` snippet. `CachedImage` gained an `onNaturalSize`
+callback for the second. Measured ratios are committed in one debounced batch
+(120 ms): artwork arrives over several hundred milliseconds and re-packing per
+image would shuffle the grid under the pointer.
+
+`MosaicTile.svelte` draws one tile at an exact pixel box, with its label written
+**over** the bottom of the artwork. A caption below the box would add height the
+layout didn't compute, and a caption that wrapped to two lines would break the
+row alignment the mosaic exists to provide.
+
+### Composition
+
+`libraryMosaic.ts` (pure, tested) builds the tile list: the cross-library
+favourites entry first, then each library followed by its own category tile. A
+category appears **once** — two movie libraries share one favourites list, so a
+tile each would be two tiles to the same place. A library whose `favoritesScope`
+is absent (Live TV, channels, books) gets no tile rather than one opening an
+unfiltered list.
+
+Home uses the same tiles in `layout="strip"` but **without** the favourites tiles:
+home already carries Favourite Movies / Shows / Music rows of its own, and a
+second entry point in the strip above them would be redundant.
+
+## Out of scope
+
+- The item grids inside a library (`/library/movies`, `/library/music/albums`, …).
+  Those show one item type each, so a uniform grid crops nothing; the mosaic buys
+  them nothing but reflow.
+- Backdrop/collage artwork for libraries with no image of their own.
+- Reordering or pinning libraries.

docs/specs/offline-downloaded-only-filter.md

@@ -0,0 +1,235 @@
+# Spec: Offline "downloaded only" filtering (issue #10)
+
+**Status:** Implemented
+**Scope:** Frontend (connectivity store) + Rust (hybrid repository). No new
+commands, no schema changes, no UI additions.
+**Requirements:** UR-052 → DR-078, DR-079, DR-080
+(see [requirements.md](../requirements.md)).
+**Tracking:** issue #10 — *"when offline the filter to show only downloaded
+media does not work."*
+
+## Summary
+
+Offline, a library page is supposed to show **only media on the device**, with a
+"Show all server media" toggle that additionally reveals the cached server
+catalog greyed out (queueable for download on reconnect). In practice the toggle
+does not gate the listing — every server item still appears. This spec fixes
+that with two independent changes; either one alone leaves the bug visible.
+
+## Background: what already exists
+
+Verified in code. **The feature is built and mostly correct — this is a
+two-point repair, not new infrastructure.** Do not rebuild the toggle, the
+command, or the SQL gate.
+
+1. **The SQL gate works and is unit-tested.**
+   [offline.rs](../../src-tauri/src/repository/offline.rs) — `get_items` appends
+   the synced-catalog `UNION` branch only when `include_catalog_browse()` is
+   true; with it false, only downloaded/local rows return. Guarded by
+   `test_get_items_toggle_gates_synced_catalog` (UT-067). **Do not touch the
+   query.**
+
+2. **The toggle → backend path is wired.** The `showServerCatalog` store and the
+   `set_show_server_catalog` command
+   ([catalog.rs](../../src-tauri/src/commands/catalog.rs)) drive the process-wide
+   `INCLUDE_CATALOG_BROWSE` flag. `pushCatalogVisibility` in
+   [offlineCatalog.ts](../../src/lib/services/offlineCatalog.ts) computes
+   `include = connected || showCatalog` and pushes it on every change.
+
+3. **Home-screen queries are already downloads-only.** `get_latest_items`,
+   `get_resume_items`, `get_recently_played_audio`, `get_resume_movies` all
+   `INNER JOIN downloads ... status = 'completed'`. They are unaffected — leave
+   them.
+
+4. **`MediaCard` already greys and queues.**
+   [MediaCard.svelte](../../src/lib/components/library/MediaCard.svelte) —
+   `isServerOnly` renders the greyed, inert card with a queue button; the queued
+   row heals its `stream_url` on reconnect via the offlineCatalog service. Leave
+   it.
+
+## The two defects
+
+### Defect A — offline is never actually entered (DR-079)
+
+`pushCatalogVisibility` keys off `isConnected`, but
+[connectivity.ts](../../src/lib/stores/connectivity.ts) derives:
+
+```ts
+isConnected = isOnline && isServerReachable   // isOnline = navigator.onLine
+```
+
+`navigator.onLine` is documented in that same file as **advisory only** — the
+Rust `ConnectivityMonitor` is the source of truth (principle: *reachability from
+real traffic*, DR-055). When the server is unreachable but the device link is
+up (server down, wrong LAN, VPN dropped), `isOnline` stays true, so `isConnected`
+stays true, so `include` stays true, so the backend keeps returning the full
+catalog. The user is "offline" in every meaningful sense but the toggle never
+gets a chance to gate anything.
+
+This is the primary cause: it explains why the filter looks dead rather than
+merely inverted — the gate never closes.
+
+### Defect B — an intentionally empty result falls through to the server (DR-080)
+
+With the gate off and nothing downloaded in a library, offline `get_items`
+correctly returns few or zero rows. But
+[hybrid.rs](../../src-tauri/src/repository/hybrid.rs) treats a cache result as a
+hit only `if data.has_content()`. An empty offline result is indistinguishable
+from a cache miss, so `HybridRepository::get_items` (and `parallel_race`, used by
+~10 other reads) falls through to the server and returns the full server list —
+re-defeating the filter even after Defect A is fixed.
+
+## Design
+
+### Fix A: `isConnected` follows backend reachability alone (DR-079)
+
+In [connectivity.ts](../../src/lib/stores/connectivity.ts), redefine the derived
+store:
+
+```ts
+export const isConnected = derived(
+  connectivity,
+  ($c) => $c.isServerReachable
+);
+```
+
+`navigator.onLine` stays wired to what it is good for — a *trigger* for an
+immediate recheck (`online`/`offline` listeners already call
+`checkServerReachable()`); it must no longer be a *term* in the offline decision.
+Leave `isOnline` on the state object and the listeners intact.
+
+Consider whether the optimistic `isServerReachable: true` startup default
+([connectivity.ts](../../src/lib/stores/connectivity.ts)) should hold until the
+first real check resolves. Keep it — flipping the app to "offline" on launch is a
+worse regression than a brief full-catalog flash before the first probe. Note the
+choice in a comment.
+
+**Blast radius — this is the reason this is a spec, not a patch.** `isConnected`
+is consumed beyond this feature (banners, `MediaCard`, mini-player gating,
+anything importing it). Enumerate consumers first:
+
+```
+grep -rn "isConnected" src/ | grep -v node_modules
+```
+
+For each, confirm "server unreachable" (not "device link down") is the correct
+trigger. It almost always is — that is the whole point of the reachability model
+— but verify rather than assume, and call out anything that genuinely wanted the
+device link in the PR description.
+
+### Fix B: an empty offline result is authoritative when the gate is off (DR-080)
+
+The backend must distinguish "cache is cold, go ask the server" from "user asked
+for downloads only and there are none here." The gate flag already encodes intent
+— reuse it.
+
+Add a getter beside the existing setter in
+[offline.rs](../../src-tauri/src/repository/offline.rs):
+
+```rust
+pub fn include_catalog_browse() -> bool { /* pub, already exists privately */ }
+```
+
+In [hybrid.rs](../../src-tauri/src/repository/hybrid.rs) `get_items`: when
+`!include_catalog_browse()`, treat the offline result as authoritative and return
+it **as-is even when empty** — do not spawn/await the server fallback for this
+call. When the flag is on (online fast-path, or offline with the toggle on),
+behaviour is unchanged: empty cache still falls through to the server.
+
+Keep it surgical:
+
+- Scope the change to `get_items`. The gate is a `get_items` concept; do not
+  thread it into `parallel_race` or the other readers, which have no catalog
+  gate and legitimately want the server on an empty cache.
+- Preserve the online path exactly: with the flag on (its default, and always so
+  while reachable) the method behaves as it does today, including the background
+  cache refresh on a hit.
+- The flag is process-global `Relaxed`; it is set from the frontend before the
+  query. That ordering already holds for the SQL gate — no new synchronization.
+
+### Why both
+
+Fix A closes the gate; Fix B stops the hybrid from re-opening it. A alone: with
+downloads present the list still gets padded by the server fallback whenever a
+library's cache is thin. B alone: the gate never closes because `isConnected`
+never goes false on a live link. Ship them together.
+
+## Out of scope
+
+- The SQL gate, the toggle, the command, `INCLUDE_CATALOG_BROWSE` — all correct.
+- `MediaCard` greying / queue-on-reconnect — correct.
+- Home-screen and resume queries — already downloads-only.
+- The Rust `ConnectivityMonitor` reachability logic itself — unchanged; this
+  spec only stops the *frontend* from diluting its verdict with `navigator.onLine`.
+- Any new IPC command, DB column, or settings entry.
+- Making the "Show all server media" toggle reachable from Settings (that is a
+  UX-placement question, tracked separately under UR-051's toggle note).
+
+## Acceptance criteria
+
+- [~] With the server unreachable on a live device link, a library page lists
+      only downloaded media when the toggle is off (IT-016 — pending e2e; unit
+      coverage via UT-069 + gate tests).
+- [x] Turning the toggle on reveals the greyed-out cached catalog; turning it off
+      hides it again — without leaving/re-entering the page (SQL gate + toggle
+      wiring unchanged; UT-068 confirms the flag is pushed on toggle change).
+- [x] A library with downloads and a thin cache does not get padded with
+      non-downloaded server items when offline with the toggle off (Defect B —
+      UT-070: gate off + empty offline result returned as-is, server not queried).
+- [x] `isConnected` is false whenever the server is unreachable, regardless of
+      `navigator.onLine`; true for a reachable server even if the browser reports
+      offline (UT-069).
+- [x] Every existing `isConnected` consumer still behaves correctly (banner in
+      `+layout.svelte`, `MediaCard`, `favorites.ts` server-write skip — all want
+      "server unreachable", which is the new semantics; `CastButton`'s local
+      `isConnected` is unrelated). Full frontend suite (616 tests) green.
+- [x] Online behaviour is unchanged: with the flag on (its default, always so
+      while reachable) `get_items` keeps the offline fast-path and background
+      refresh (UT-067 + gate-on fall-through test).
+- [~] A download queued from a greyed offline card resolves and starts on
+      reconnect (IT-017 — regression check, no code change; offlineCatalog
+      resume path untouched).
+- [x] `bun run check`, `bun run test`, and `bun run test:rust` pass;
+      `cd src-tauri && cargo fmt && cargo clippy` clean (no new warnings in the
+      touched files).
+
+## Testing
+
+Rust ([offline.rs](../../src-tauri/src/repository/offline.rs) /
+[hybrid.rs](../../src-tauri/src/repository/hybrid.rs) test modules):
+
+- **UT-070** — hybrid `get_items` with the gate off returns an empty offline
+  result as-is and does **not** query the server. Assert via a mock online repo
+  whose `get_items` bumps a call counter that must stay at zero.
+- Gate on + empty cache still falls through to the server (guard the online path).
+- UT-067 (`test_get_items_toggle_gates_synced_catalog`) must still pass untouched.
+
+Frontend (vitest, `src/lib/**/*.test.ts`):
+
+- **UT-069** — `isConnected` follows `isServerReachable` alone: false when
+  unreachable with `navigator.onLine === true`; true when reachable with
+  `navigator.onLine === false`.
+- **UT-068** — `pushCatalogVisibility` resolves `serverReachable || showCatalog`
+  and pushes to the backend on a change of either input (extend the existing
+  offlineCatalog tests).
+
+Integration (IT-016, IT-017) are documented as pending in
+[requirements.md](../requirements.md); wire them if the e2e harness can simulate
+an unreachable-server-on-live-link state, otherwise leave them pending with a note.
+
+New/changed requirement code keeps its `TRACES:` comments — see
+[CLAUDE.md](../../CLAUDE.md). The affected files already carry tags:
+`connectivity.ts` (`… | DR-079`), `hybrid.rs` (`… | DR-080`), `offline.rs`
+(`… | DR-078`). Update the getter's tag when you expose it.
+
+## Notes for the implementer
+
+- Read [docs/architecture/07-connectivity.md](../architecture/07-connectivity.md)
+  before Fix A — it is the canonical statement of the reachability model this fix
+  restores fidelity to.
+- Fix B relies on the frontend having pushed the flag before the query runs; that
+  ordering already holds for the SQL gate today. No new locking.
+- Another session is active in this repo (WiFi-only downloads, account menu
+  landed alongside this work). Check `git diff` before "repairing" unexpected
+  changes, and expect requirement IDs around UR-052 / DR-078 to be adjacent to
+  other new rows.

docs/specs/playback-backend-unification.md

@@ -0,0 +1,226 @@
+# Spec: Playback backend unification — findings and strategy
+
+**Status:** Accepted (analysis; no code changes)
+**Requirements:** IR-004, UR-031, UR-032, UR-033 — revises the "Platform Playback Backend Parity" issue in requirements.md
+**UX spec:** n/a
+**Supersedes / revises:** informs [android-native-video-spike.md](android-native-video-spike.md), [android-audio-settings-parity.md](android-audio-settings-parity.md), [windows-native-audio-backend.md](windows-native-audio-backend.md)
+
+## Summary
+
+This spec records the outcome of an investigation into unifying JellyTau's
+playback backends (Linux/MPV, Android/ExoPlayer, Windows/webview) onto a single
+engine with hardware acceleration everywhere. **The conclusion is that video
+cannot be unified onto a native engine, and should not be attempted.** Audio
+*can* be, and that is where the remaining specs direct effort.
+
+No code changes follow from this spec directly. It exists so the decision is
+written down with its evidence, and so a future session does not re-run the same
+investigation.
+
+## Motivation
+
+The requirements doc carries a "Platform Playback Backend Parity" issue noting
+that audio settings work on Linux but not Android, and proposing eventual
+convergence. The natural next question — "should we just run one engine
+everywhere?" — needed answering before spending effort on per-backend patches.
+
+The investigation also surfaced that several statements in requirements.md and in
+code comments are factually wrong. Those corrections are part of the deliverable.
+
+## Findings
+
+### 1. The current architecture is not what the docs describe
+
+| Platform | Audio | Video |
+|----------|-------|-------|
+| Linux | MPV (native, **audio-only**) | webview `<video>` + hls.js |
+| Android | ExoPlayer (native) | **webview `<video>` + hls.js** |
+| Windows | webview `<audio>` | webview `<video>` + hls.js |
+
+Two surprises:
+
+- **MPV never decodes video.** `mpv_backend.rs` sets `video = no` and
+  `audio-display = no` at construction. Linux video has always been the webview.
+  Correspondingly, `player_play_item` deliberately does *not* load into MPV on
+  Linux (it calls `set_current_item`, which only updates the queue).
+- **Android video is also the webview.** `createAdapter()` in
+  `src/lib/player/adapters/index.ts` hardcodes `const effectiveKind = "html5"`
+  and does `void backendKind`, discarding the `use_html5_element` signal that
+  `get_player_status` computes in Rust. `NativePlayerAdapter` is dead code, and
+  ExoPlayer's `SurfaceView` path in `JellyTauPlayer.kt` is unreachable.
+
+So video is *already* unified — on HTML5, everywhere, by accident of that
+hardcode — and on the path without hardware decoding on Android.
+
+### 2. Native video cannot be composited with a Tauri webview
+
+This is the load-bearing finding. It is **not** an mpv limitation; it defeats
+every candidate engine identically:
+
+- **mpv**: `tauri-plugin-libmpv`'s own platform table reads Linux ⚠️
+  *"Experimental. Window embedding is not working."*
+- **GStreamer** (wry discussion #284, 2024): *"Gstreamer was rendering above the
+  surface and covering all html elements."*
+- **libVLC** (tauri discussion #6343, 2024): *"I had to render the webview in a
+  child window though because vlc kept rendering on top of it."*
+
+Root cause, from Tauri maintainer amrbashir (tauri#9220, 2024-03-30):
+
+> "we are limited to using Webkit2GTK on Linux and that requires a GTK window.
+> While possible to add a GTK widget as a child X11 window inside raw X11 window,
+> this is however a bit hacky and **it is not possible on Wayland at all**."
+
+WebKitGTK, WebView2, and Android WebView each draw into their own compositor
+surface. A native video surface is either entirely above or entirely below the
+webview; it cannot interleave with HTML. Every working example in the ecosystem
+is the same hack — a separate child window position-synced to a
+`getBoundingClientRect()` div — which breaks on resize, scroll, and any UI drawn
+over the video. For JellyTau that means the controls, subtitle overlay, and
+mini-player.
+
+The most recent comment on tauri#6343 (2026-05-23) confirms it is still unsolved:
+
+> "I'm faking it and the window is not truly embedded, basically when the parent
+> moves or resizes I reset the position and size of the libmpv window to align it
+> with an HTML div."
+
+**The principle to carry forward: audio can unify on a native engine; video
+cannot, because video needs a surface and the webview owns the surface.**
+
+### 3. mpv would regress streaming quality
+
+mpv has **no adaptive bitrate**. It delegates HLS to FFmpeg's demuxer, which
+selects one variant at open time and never adapts; mpv#3548 (2016) requested ABR
+and it never landed. `--hls-bitrate` is a static picker defaulting to `max`.
+
+The webview path already has real ABR via hls.js. Moving video to mpv would be a
+**downgrade** on every platform — no graceful degradation on weak networks, and
+quality changes requiring teardown and reload.
+
+### 4. Crossfade is architecturally blocked on mpv
+
+mpv's audio chain is single-stream. FFmpeg's `acrossfade` is an `N→A` filter
+requiring two input streams, so there is no second input to feed it. Real
+crossfade needs **two libmpv instances** with manually ramped volumes. Upstream
+maintainer response (mpv#4512, closed three minutes after opening):
+
+> "No. I also find crossfading stupid and complex, so the likeliness of that
+> happening is low."
+
+GStreamer *could* do it via `audiomixer`. mpv cannot, at any reasonable cost.
+
+### 5. Engine comparison summary
+
+| Criterion | mpv | GStreamer | libVLC |
+|-----------|-----|-----------|--------|
+| Webview compositing | ❌ Linux broken | ❌ same wall | ❌ same wall |
+| Adaptive bitrate HLS | ❌ none | ✅ adaptivedemux2 | ✅ adaptive module |
+| Rust bindings | ⚠️ `libmpv2` active; our pin is dead | ✅ `gstreamer-rs` excellent | ❌ `vlc-rs` abandoned (2018) |
+| Windows cross-MSVC | ⚠️ prebuilt DLL | ❌ pkg-config vs cargo-xwin | ❌ no better |
+| Android packaging | ✅ Maven AAR (used by Findroid) | ⚠️ Cerbero/NDK, painful | ✅ mature AAR |
+| ASS/SSA subtitles | ✅ libass built in | ✅ libass | ✅ libass |
+| Crossfade | ❌ impossible | ✅ `audiomixer` | ⚠️ unclear |
+
+Every candidate fails the first row, which is the disqualifying one.
+
+### 6. Two further options ruled out
+
+**Webview `<audio>`/`<video>` everywhere** (i.e. delete the native audio backends
+too) is dead on Android: `navigator.mediaSession` is *deliberately compiled out*
+of Android WebView (Chromium CL 2613133003), so lockscreen/media-notification
+control would be impossible. Chromium has also never shipped `audioTracks`. It
+remains fine for Windows *video*, which is what we already do.
+
+**FFmpeg-direct / Rust-native** (`ffmpeg-next`, `rsmpeg`, Symphonia) is not
+close: the safe bindings do not expose hardware decode at all, `ffmpeg-next` is
+self-declared maintenance-only, and Symphonia lacks HE-AAC and gapless AAC. This
+is a multi-person-year path to reach parity with what we already have.
+
+### 7. If libmpv is ever revisited on Android
+
+Recorded so the next investigation starts from evidence rather than repeating the
+search. The `dev.jdtech.mpv:libmpv` AAR — maintained by Findroid's author, i.e.
+another Jellyfin Android client — was inspected directly:
+
+- `libmpv.so` exports the full 54-function `mpv_*` C API with **zero `Java_`
+  symbols**; JNI is a separate optional ~19 KB `libplayer.so`. So it is drivable
+  from Rust without a Java shim. (This is precisely what disqualifies libVLC,
+  whose Android video path hard-requires a Java `AWindow` jobject.)
+- ~23 MB/ABI, versus libVLC's ~46 MB/ABI.
+- 🔴 **The published AAR is built `--enable-gpl --enable-version3` — it is
+  GPLv3**, not LGPL. Fine for us (see [libmpv2-migration.md](libmpv2-migration.md)),
+  but it would be a hard constraint for anyone shipping closed source, and an
+  LGPL rebuild would be your own build to own.
+- Top unverified risk if anyone tries this: whether `libmpv2-sys` can
+  cross-compile for `aarch64-linux-android` against that prebuilt `.so`. No
+  working example of `libmpv2` on Android was found.
+
+None of this changes the verdict — the cost is the MediaSession/foreground-service
+rewrite, not the bindings.
+
+## Decision
+
+1. **Do not unify video onto a native engine.** Video stays in the webview with
+   hls.js on all platforms. This is not a compromise — it is the configuration
+   that falls out of the compositing constraint, and it is the only one that
+   gives us ABR for free.
+2. **Android native video is worth a bounded spike anyway** — not for
+   unification, but because ExoPlayer's `SurfaceView` path already exists and
+   would restore hardware decode plus ASS/SSA subtitles. See
+   [android-native-video-spike.md](android-native-video-spike.md).
+3. **Audio parity is the real gap** and is achievable without touching any of the
+   above. See [android-audio-settings-parity.md](android-audio-settings-parity.md)
+   and [windows-native-audio-backend.md](windows-native-audio-backend.md).
+4. **Migrate the dead libmpv pin** regardless of any of this. See
+   [libmpv2-migration.md](libmpv2-migration.md).
+
+## Corrections to existing docs
+
+These are factual errors found during the investigation. Fixing them is in scope
+for this spec.
+
+| Location | Says | Actually |
+|----------|------|----------|
+| `requirements.md` UR-031 (line ~44) | "Done (Linux only)" | Not implemented on any platform. |
+| `requirements.md` DR-034 (line ~196) | "Done (Linux only)" | Not implemented anywhere — `mpv_backend.rs` has a bare `// TODO: Implement crossfade via MPV audio filters if needed`. Architecturally blocked on mpv (finding 4). |
+| `requirements.md` parity matrix | Crossfade ✅ Linux / ❌ Android | ❌ / ❌ |
+| `requirements.md` parity matrix | (no EQ row) | EQ is also Linux-only — `build_af_filter`/`eq_filter_entries` exist only in `mpv_backend.rs`. Same root cause, same fix. |
+| `nativeAdapter.ts:11-14` | Native Android video "blocked upstream by tauri#10152" | tauri#10152 is a stale *feature request*, dead since 2024-07-01. The capability shipped in tauri commit `27d01834` (2024-09-02). Not a blocker. |
+
+## Layer assignment
+
+No new logic. The one boundary observation worth recording:
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Which video backend a platform uses (`use_html5_element`) | Rust | Already correctly computed in `get_player_status`. The frontend currently *discards* it — that is the bug, not the design. Restoring it means the frontend consumes a backend decision rather than making its own. |
+
+## Out of scope
+
+- Any code change. This spec is analysis; the sibling specs carry the work.
+- iOS/macOS. Not current targets.
+- Replacing hls.js.
+
+## Acceptance criteria
+
+- [ ] `requirements.md` DR-034 status corrected; parity matrix updated (crossfade ❌/❌, EQ row added).
+- [ ] Stale tauri#10152 comment in `nativeAdapter.ts` corrected.
+- [ ] The four sibling specs exist and are linked from here.
+
+## Testing
+
+n/a — documentation only.
+
+## TRACES
+
+No new code. Requirement text changes only; DR-034's status line is the one
+substantive edit.
+
+## Notes for the implementer
+
+- The evidence above was gathered in July 2026. The compositing constraint has
+  been stable since 2021 (wry#284) and is maintainer-declared unfixable, so it is
+  unlikely to change soon — but if someone revisits this, tauri#6343 and wry#284
+  are the threads to re-read first.
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes.

docs/specs/playback-docs-corrections.md

@@ -0,0 +1,198 @@
+# Spec: Playback documentation corrections
+
+**Status:** Proposed
+**Requirements:** revises the status of DR-034; corrects the parity matrix in [requirements.md](../requirements.md)
+**UX spec:** n/a
+**Supersedes / revises:** implements the "Corrections to existing docs" section of [playback-backend-unification.md](playback-backend-unification.md)
+
+## Summary
+
+Fix four factual errors in the requirements doc and the player source comments,
+all found while investigating backend unification. Each claims something the code
+does not do. Small change, but they are actively misleading: two of them assert a
+feature is implemented when it is implemented nowhere, and one cites an upstream
+blocker that no longer exists.
+
+Documentation and comments only — no behaviour change.
+
+## Motivation
+
+These errors compound. DR-034 reads "Done (Linux only)", so a future session
+planning Android parity would reasonably assume crossfade exists on Linux and
+only needs porting — when in fact it is unimplemented everywhere *and*
+architecturally blocked on the engine it supposedly runs on. Likewise the
+tauri#10152 comment has been discouraging work on Android native video since the
+upstream capability shipped in September 2024.
+
+## The corrections
+
+### 1. DR-034 status is wrong
+
+`requirements.md` line ~196:
+
+```
+| DR-034 | Crossfade engine with configurable duration (0-12s) | Player | UR-031 | Done (Linux only) |
+```
+
+The code:
+
+```rust
+// src-tauri/src/player/mpv_backend.rs, in set_audio_settings
+// TODO: Implement crossfade via MPV audio filters if needed
+```
+
+That is the entire crossfade implementation. `crossfade_duration` is plumbed
+through `AudioSettings` and clamped to 0–12s, but no backend ever acts on it.
+
+**Change to:** `Not implemented (blocked on MPV — see playback-backend-unification.md)`
+
+Worth stating *why* in the requirements entry, because it is not a scheduling
+gap: mpv's audio chain is single-stream, and FFmpeg's `acrossfade` is an `N→A`
+filter needing two inputs. Real crossfade requires two libmpv instances with
+manually ramped volumes. Upstream declined the feature (mpv#4512).
+
+### 1b. UR-031 status is wrong for the same reason
+
+`requirements.md` line ~44:
+
+```
+| UR-031 | Crossfade between audio tracks | Low | Done (Linux only) |
+```
+
+Same error one level up: the *user* requirement is also marked done. Since no
+backend implements crossfade, UR-031 is not satisfied on any platform.
+
+**Change to:** `Not implemented (blocked — see DR-034)`
+
+Note line ~517 of the same file (`UR-031 (Crossfade), UR-032 (Gapless),
+UR-033 (Normalization) only work on Linux`) inherits the error — crossfade works
+nowhere, so it should read UR-032/UR-033 only.
+
+### 2. Parity matrix crossfade row is wrong
+
+```
+| Crossfade | ✅ | ❌ | Gap |
+```
+
+**Change to** `| Crossfade | ❌ | ❌ | Not implemented |` — it is not a
+platform-parity gap, it is an unbuilt feature.
+
+### 3. Parity matrix is missing the equalizer
+
+The matrix lists crossfade, gapless, and normalization but omits the EQ, which
+has the same Linux-only shape and the same root cause (`ExoPlayerBackend` not
+overriding `set_audio_settings`). `build_af_filter` and `eq_filter_entries` exist
+only in `mpv_backend.rs`; there is no equalizer code in the Android tree.
+
+**Add:** `| Equalizer (10-band) | ✅ | ❌ | Gap |`
+
+### 4. `nativeAdapter.ts` cites a stale blocker
+
+`src/lib/player/adapters/nativeAdapter.ts:11-14` states native Android video is
+blocked upstream by tauri#10152 (transparent webview / SurfaceView compositing).
+
+tauri#10152 is open but **dead since 2024-07-01**, and it is a *feature request*
+that `WebviewWindowBuilder::transparent` was desktop-only — not a report that
+compositing is broken. The capability shipped in tauri commit `27d01834`
+(2024-09-02), which moved `transparent()` into the cross-platform impl block with
+only the tao call `#[cfg(desktop)]`-fenced. It landed as a clippy cleanup, so the
+issue was never closed. Separately, the black/white-screen bug (tauri#8381,
+tauri#9408) was a broken JNI signature for `setBackgroundColor`, fixed in wry
+0.39.4; we ship wry 0.55.x.
+
+**Change to:** a comment stating the adapter is currently unreachable because
+`createAdapter` hardcodes the HTML5 kind, that transparency is no longer an
+upstream blocker, and that
+[android-native-video-spike.md](android-native-video-spike.md) tracks whether
+SurfaceView compositing actually works. Be explicit that *nobody has
+demonstrated* SurfaceView-behind-WebView on Tauri Android — nothing upstream
+blocks it, and nothing upstream proves it.
+
+### 5. Platform capability is signalled three incompatible ways
+
+Not a doc error — a real inconsistency found during the same investigation, worth
+recording here even though fixing it needs its own change.
+
+Which backend a platform uses is currently expressed three ways:
+
+1. Rust `#[cfg]` gates in `player/mod.rs` and `create_player_backend` — the truth.
+2. The `useHtml5Element` / `VideoBackend` value from `get_player_status` — which
+   the frontend discards (see the spike spec).
+3. **Frontend user-agent sniffing** in `src/lib/services/webviewAudio.ts:30-41`:
+
+```ts
+const ua = navigator.userAgent.toLowerCase();
+const isAndroid = ua.includes("android");
+const isLinux = ua.includes("linux") && !isAndroid;
+return !isAndroid && !isLinux;
+```
+
+The comment says it is "matching the Rust cfg gate" — i.e. the frontend
+re-derives a backend decision from the user-agent string and hopes it stays in
+sync. That is the frontend deciding *which backend exists*, which is domain
+knowledge, not presentation. It also breaks silently the moment a new target is
+added or a webview's UA changes.
+
+**This is a boundary leak of the same family the spec-review checklist exists to
+catch**, even though `check:boundary`'s tripwire (item-type arrays) does not
+match it. Rust already computes the answer; the frontend should consume it.
+
+Not fixed by this spec — it is behavioural, not documentation. It should be
+folded into the spike spec's factory rework, where the same
+"consume Rust's decision instead of re-deriving it" change is already in scope.
+
+### Also worth fixing while here
+
+`requirements.md` IR-004 reads "In Progress (basic playback works, audio settings
+missing)". That stays accurate until
+[android-audio-settings-parity.md](android-audio-settings-parity.md) lands, but
+the "Future Fix" list in the parity issue proposes
+`ConcatenatingMediaSource` for crossfade — **deprecated in current Media3**. Drop
+that suggestion; the modern approach is a custom `AudioProcessor`.
+
+## Layer assignment
+
+No logic. Documentation and comments only.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| — | — | No logic introduced or moved by this spec. |
+
+## Out of scope
+
+- Implementing crossfade. This spec only stops claiming it exists.
+- Implementing Android audio settings — see the parity spec.
+- Running the Android video spike — see that spec.
+- Rewriting the architecture docs. `docs/architecture/05-platform-backends.md`
+  should be re-read for the same class of error, but that is a larger pass.
+
+## Acceptance criteria
+
+- [ ] DR-034 status corrected, with the blocking reason stated.
+- [ ] UR-031 status corrected (line ~44), and the "only work on Linux" line (~517) no longer lists crossfade.
+- [ ] Parity matrix: crossfade ❌/❌; equalizer row added.
+- [ ] `ConcatenatingMediaSource` suggestion removed from the "Future Fix" list.
+- [ ] `nativeAdapter.ts` comment corrected and pointing at the spike spec.
+- [ ] `bun run check` and `bun run test` pass (a comment change still touches TS).
+- [ ] `bun run traces:markdown` re-run if requirement text changed.
+
+No Rust changes, so the `cargo` gates do not apply.
+
+## Testing
+
+None beyond the standard gates — no behaviour changes. Confirm
+`bun run traces:markdown` regenerates cleanly, since DR-034's row is referenced
+by the traceability matrix.
+
+## TRACES
+
+No code implementing requirements changes; no TRACES comments to add or update.
+The DR-034 row in `docs/traceability.md` will regenerate with the corrected text.
+
+## Notes for the implementer
+
+- Do **not** silently delete DR-034. The requirement (UR-031 crossfade) is still
+  wanted; it is the *status* that is wrong. Keeping the row with an honest status
+  and a reason is the point.
+- A parallel Claude session may be active — `git diff` before "repairing"
+  unexpected changes.

docs/specs/player-facade-enforcement.md

@@ -0,0 +1,258 @@
+# Spec: Enforce the unified player boundary
+
+**Status:** Proposed
+**Requirements:** DR-095 (new); relates to UR-005 and the unified-player-boundary
+principle in CLAUDE.md and [02-svelte-frontend.md](../architecture/02-svelte-frontend.md)
+**UX spec:** n/a — refactor, no user-visible change.
+**Supersedes / revises:** n/a
+
+## Summary
+
+The stated principle is that UI controls playback **only** through
+`playerController` ([src/lib/player/index.ts](../../src/lib/player/index.ts)),
+never by calling `commands.player*` directly. There are **52 direct call sites
+outside** that facade. This spec routes the genuine playback-control calls
+through the facade, narrows the principle's wording so it stops forbidding
+things it never meant to forbid, and adds the lint rule that keeps it true —
+because this rule is the one design principle in the audit with **no automated
+check at all**, and it is also the one that drifted furthest.
+
+## Motivation
+
+Direct `commands.player*` usage outside `src/lib/player/`, by file:
+
+| File | Sites |
+|---|---|
+| [queue.ts](../../src/lib/stores/queue.ts) | 10 |
+| [player/[id]/+page.svelte](../../src/routes/player/[id]/+page.svelte) | 9 |
+| [VideoPlayer.svelte](../../src/lib/components/player/VideoPlayer.svelte) | 8 |
+| [settings/+page.svelte](../../src/routes/settings/+page.svelte) | 5 |
+| [sleepTimer.ts](../../src/lib/stores/sleepTimer.ts) / [auth.ts](../../src/lib/stores/auth.ts) / [autoplay.ts](../../src/lib/api/autoplay.ts) | 4 each |
+| [preload.ts](../../src/lib/services/preload.ts) | 3 |
+| [library/[id]](../../src/routes/library/[id]/+page.svelte), [playerEvents.ts](../../src/lib/services/playerEvents.ts), [playbackMode.ts](../../src/lib/stores/playbackMode.ts) | 1–2 each |
+
+These are **not** equivalent violations, and treating them as one number is why
+the rule has been easy to ignore. Three distinct groups:
+
+**(a) Genuine violations — playback control with a facade method that already
+exists.** `playerStop` ×6, `playerPlayTracks` ×4, `playerSeek` ×2,
+`playerPlayAlbumTrack` ×2, `playerNext`, `playerPrevious`, `playerSkipTo`,
+`playerToggleShuffle`, `playerCycleRepeat`, `playerRemoveFromQueue`,
+`playerMoveInQueue`, `playerAddTrackById`, `playerAddTracksByIds`,
+`playerSetSubtitleTrack`, `playerPlayItem`. The facade exposes `stop()`,
+`seek()`, `next()`, `previous()`, `skipTo()`, `toggleShuffle()`,
+`cycleRepeat()`, `removeFromQueue()`, `moveInQueue()`, `addTrackById()`,
+`addTracksByIds()`, `setSubtitleTrack()`, `playTracks()`, `playAlbumTrack()`,
+`playItem()` — every one of these has a facade equivalent that is simply not
+being called. `queue.ts` is the starkest case: it imports `commands` directly
+and re-implements ten methods the facade already provides.
+
+**(b) Playback control with no facade method.** `playerPlayQueue`,
+`playerGetQueue`, `playerGetStatus`, `playerEnterBackgroundAudio`,
+`playerExitBackgroundAudio`, `playerSetSleepTimer`, `playerCancelSleepTimer`,
+`playerPlayNextEpisode`, `playerCancelAutoplayCountdown`. In scope for the
+principle, but currently *impossible* to comply with — the facade has no surface
+for them. A rule that cannot be followed is not being broken so much as it is
+unfinished.
+
+**(c) Not playback control.** `playerConfigureJellyfin` ×3,
+`playerDisableJellyfin`, `playerGet/SetAudioSettings`,
+`playerGet/SetVideoSettings`, `playerGetEqPresets`,
+`playerGet/SetAutoplaySettings`, `playerGet/SetCacheConfig`,
+`playerPreloadUpcoming`. These are configuration and lifecycle calls that happen
+to live under the `player_` command prefix. The principle is about *who is
+authoritative for playback state* — settings CRUD isn't that.
+
+The audit's read: the rule as written is violated 52 times, which makes real
+drift indistinguishable from acceptable usage, and that ambiguity is what lets
+group (a) persist. Note also that the principle **is** well-honoured where it
+matters most — the read side is clean, with UI reading state exclusively from
+the facade's re-exported stores. The write side is what drifted.
+
+## Layer assignment
+
+Frontend-internal refactor. No domain logic moves and nothing new crosses IPC —
+the same Rust commands are called, through one module instead of many.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Playback command dispatch (adapter routing: native vs HTML5) | Frontend — `src/lib/player/` **only** | Presentation-layer plumbing, but must be centralised: the facade picks between the native backend and the HTML5 `<video>` adapter. A caller bypassing it silently skips that routing. |
+| Playback *authority* (position, pause, rate, track changes) | **Rust / the player** | Unchanged. The player is authoritative; UI is a consumer. This spec does not touch that direction. |
+| Queue mutation commands | Frontend facade → Rust | Rust owns queue state; the facade is the single call path to it. |
+| Player settings CRUD (EQ, video, autoplay, cache) | Frontend, **outside** the facade | Configuration, not playback control — read/written on a settings page with no adapter routing. Explicitly carved out below. |
+| Backend→frontend event handling | `playerEvents.ts` | Already correct. It is the facade's own plumbing, not a bypassing consumer. |
+
+No Jellyfin taxonomy is involved, so no boundary-leak risk.
+
+## Design
+
+### 1. Narrow the principle to what it actually means
+
+Amend CLAUDE.md and [02-svelte-frontend.md](../architecture/02-svelte-frontend.md):
+
+> **Unified player boundary.** UI controls **playback** — transport, queue
+> mutation, track selection, playback initiation — *only* through
+> `playerController`. Player **configuration** commands (`player_*_settings`,
+> `player_configure_jellyfin`, `player_*_cache_config`, `player_preload_upcoming`)
+> are ordinary IPC and may be called directly from settings surfaces.
+
+This is a clarification, not a relaxation: it makes group (c) explicitly fine so
+that a violation count means something. A rule with 52 nominal violations, most
+of them acceptable, provides no signal.
+
+### 2. Fill the facade gaps (group b)
+
+Add to `playerController`, each a thin pass-through preserving current
+behaviour:
+
+```ts
+playQueue, getQueue, getStatus,
+enterBackgroundAudio, exitBackgroundAudio,
+setSleepTimer, cancelSleepTimer,
+playNextEpisode, cancelAutoplayCountdown,
+```
+
+Do this **first** — group (a) cannot be fully migrated while callers still need
+a direct import for a neighbouring call, and a file that imports `commands` for
+one reason will keep using it for others.
+
+### 3. Migrate group (a)
+
+Mechanical: replace `commands.playerX(...)` with `playerController.x(...)`.
+Highest-value first: `queue.ts` (10 sites, all direct facade equivalents), then
+`player/[id]/+page.svelte`, `VideoPlayer.svelte`, `sleepTimer.ts`,
+`playbackMode.ts`, `library/[id]/+page.svelte`.
+
+Two sites need care rather than substitution:
+
+- **`playerEvents.ts`** (`playerOnPlaybackEnded`, `playerStop` in the error
+  path). This module *is* the facade's event plumbing — the counterpart to
+  `index.ts`, inside the boundary conceptually though not by directory. Treat
+  `src/lib/services/playerEvents.ts` as **inside** the boundary and exempt it,
+  rather than making it call the facade that calls back into it. Record this in
+  the lint config with the reason.
+- **`VideoPlayer.svelte`** — registers its own adapter via `setActiveAdapter`.
+  Its `playerStop`/`playerPlayItem` calls interact with adapter lifecycle, and
+  CLAUDE.md's gotcha ("no lifecycle calls after an `await` in `onMount`") applies.
+  Migrate this file **last and on its own**, so an Android seek regression is
+  bisectable to one commit.
+
+### 4. Add the lint rule (the part that makes it stick)
+
+The audit's finding was that principles with working checks held up and
+principles without them drifted. This principle has no check. Add
+`scripts/check-player-boundary.sh`, wired as `bun run check:player-boundary` and
+into `test-all.sh`:
+
+```sh
+# Playback-control commands that MUST go through the facade.
+CONTROL='player(Play|Pause|Toggle|Stop|Seek|Next|Previous|SkipTo|ToggleShuffle|CycleRepeat|RemoveFromQueue|MoveInQueue|SetVolume|ToggleMute|SetSubtitleTrack|SeekVideo|SwitchAudioTrack|PlayTracks|PlayAlbumTrack|PlayItem|PlayQueue|AddTrackById|AddTracksByIds|GetQueue|GetStatus|EnterBackgroundAudio|ExitBackgroundAudio|SetSleepTimer|CancelSleepTimer|PlayNextEpisode|CancelAutoplayCountdown|OnPlaybackEnded)'
+
+# Inside the boundary: the facade and its event plumbing.
+EXEMPT='^src/lib/player/|^src/lib/services/playerEvents\.ts$'
+```
+
+Flag `commands.$CONTROL` in non-test `src/` files outside `EXEMPT`. Config
+commands are deliberately absent from the list, matching §1 — so the check
+encodes the narrowed rule rather than the aspirational one.
+
+An ESLint `no-restricted-syntax` rule would give better editor feedback, but the
+project has no ESLint config; a shell check matches the existing
+`check:boundary` precedent and adds no dependency.
+
+## Out of scope
+
+- Changing playback *behaviour* — pure refactor.
+- The one-directional state principle (audited clean; UI reads from facade
+  stores only).
+- Moving settings CRUD behind the facade (§1 explicitly carves it out).
+- Introducing ESLint.
+- Refactoring `VideoPlayer.svelte`'s 2079 lines generally, beyond its facade
+  call sites.
+- The `commands.player*` calls **inside** `src/lib/player/` — that is the
+  facade doing its job.
+
+## Acceptance criteria
+
+- [ ] `playerController` exposes the group-(b) methods listed in §2.
+- [ ] `grep -rn "commands\.player" src/ --include='*.ts' --include='*.svelte' | grep -v '^src/lib/player/' | grep -v 'playerEvents\.ts' | grep -v '\.test\.' | grep -v bindings.ts`
+      returns **only** configuration commands per §1 — no transport, queue, or
+      playback-initiation call.
+- [ ] `queue.ts` no longer imports `commands` from bindings.
+- [ ] `bun run check:player-boundary` exists, is wired into `test-all.sh`, and
+      passes.
+- [ ] The check **fails** when a `commands.playerStop()` is added to a non-exempt
+      file — verify explicitly, as with the other gates in this batch.
+- [ ] The check does **not** fail on `commands.playerSetAudioSettings()` in
+      `settings/+page.svelte` (the §1 carve-out works).
+- [ ] CLAUDE.md and `02-svelte-frontend.md` carry the narrowed wording, including
+      the config carve-out and the `playerEvents.ts` exemption with its reason.
+- [ ] **No behavioural change**: audio and video playback, queue reorder,
+      shuffle/repeat, sleep timer, background audio, and autoplay all behave as
+      before on **both Linux and Android**.
+- [ ] Android seek and `onMount` lifecycle still correct after the
+      `VideoPlayer.svelte` migration (the known-fragile path).
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+- [ ] Changed code carries `// TRACES:` comments.
+- [ ] No Rust change, so no `bindings.ts` regeneration.
+
+## Testing
+
+**Frontend** (`bun run test`):
+- Extend the existing facade tests to cover each new group-(b) method: it
+  forwards to the right command with the right arguments, and routes to the
+  active adapter where applicable.
+- `queue.ts` tests: assert calls land on `playerController`, not `commands`. Mock
+  the facade — a test that mocks `commands` would pass either way and guard
+  nothing.
+- Keep `tauriIntegration.test.ts` and the other IPC param-naming tests green;
+  they cover the camelCase rule this refactor must not disturb.
+
+**Manual** (no automated coverage for these paths):
+- Linux: play/pause/seek/next/prev, queue reorder, shuffle, repeat, sleep timer,
+  transcoded video (HLS), background audio enter/exit.
+- Android: the same, plus lockscreen/MediaSession controls, and **seek after
+  entering the player** — the specific regression CLAUDE.md warns about.
+
+Because this is a pure refactor, the strongest signal is that no test *changes
+expectation*. A test needing its assertions rewritten means behaviour moved —
+investigate rather than update it.
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-095** — "UI playback control is routed exclusively through the
+  `playerController` facade (`src/lib/player/`), with `playerEvents.ts` inside
+  the boundary as its event plumbing and player *configuration* commands
+  explicitly outside it; enforced by `scripts/check-player-boundary.sh`."
+  Category: Player. Traces to UR-005. Status: Done on merge.
+
+```typescript
+// src/lib/player/index.ts
+// TRACES: UR-005 | DR-095
+```
+
+New facade tests take `@req-test: UT-089` onward (next free UT is **UT-089**;
+coordinate if landing alongside the sibling specs, which draw from the same
+pool).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Order matters**: §2 (fill gaps) → §3 (migrate, `VideoPlayer.svelte` last and
+  alone) → §4 (add the check). Adding the check first turns `master` red.
+- 🔴 **`VideoPlayer.svelte`**: no lifecycle calls after an `await` in `onMount` —
+  it flips to HTML5 mode and breaks Android seek. Do not let a mechanical
+  substitution introduce an `await` before a lifecycle call.
+- The facade's `requireHandle()` may throw where a raw `commands` call did not.
+  Check each migrated call site's error handling rather than assuming the
+  try/catch still covers the same cases.
+- `playbackMode.ts` interacts with remote-mode routing (`play_on_session` vs
+  local MPV). Verify remote casting still works after migrating its
+  `playerPlayTracks` call.
+- This spec is deliberately the *lowest* priority of the audit batch: it is the
+  largest diff and the only one carrying real regression risk, while the
+  traceability gate is a few lines and restores a dead safety net.

docs/specs/read-through-media-cache.md

@@ -0,0 +1,219 @@
+# Spec: Two-path media — selectable playback bitrate, independent whole-file download
+
+**Status:** Proposed
+**Requirements:** UR-070, UR-071 → DR-121, DR-122, DR-123, DR-124, DR-125; IR-032
+**UX spec:** player quality selector — needs a `ux-flows.md` section before build
+**Related:** [catalog-index-search.md](catalog-index-search.md),
+[downloads-as-offline-library.md](downloads-as-offline-library.md)
+
+## Summary
+
+Two things that are today tangled become explicitly separate:
+
+- **The playback path** streams at a bitrate the viewer can change from the
+  player. It is ephemeral and its rendition is volatile.
+- **The download path** fetches the whole file at one canonical quality, in the
+  background, independently of whatever playback is doing.
+
+Bytes fetched for playback are kept **only** when the playback rendition happens
+to be the same artifact the download path would produce — i.e. direct play.
+Otherwise playback bytes are discarded and the download path does its own fetch.
+
+## Motivation
+
+The appealing version of this — "stream and download at once, switch when enough
+has arrived" — breaks the moment the viewer can change bitrate. A capture taken
+while the rendition changes underneath it is a splice of two encodings: not a
+playable file, and not something that can be honestly recorded as a download.
+Once bitrate is selectable, one stream cannot serve both jobs.
+
+Separating the paths also removes the thing that made the original idea
+expensive: there is no mid-playback source swap to engineer, because the download
+never has to take over the live session. It lands on disk and is used at the next
+natural boundary — next episode, or next time the item is played.
+
+What exists already and is *not* this: `SmartCache` predictively downloads *other*
+items, `player_preload_upcoming` warms the next one, and
+`refresh_queue_local_sources` swaps queue entries to local at boundaries. All of
+it concerns items you are not currently playing.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Available bitrate options for an item | **Rust** | Derived from Jellyfin's media sources and playback-info negotiation; changes with the API. |
+| Mapping a chosen bitrate to transcode parameters | **Rust** | Domain vocabulary. `get_video_download_url` already owns the quality→params mapping; playback must reuse it, not restate it. |
+| Deciding whether playback bytes are keepable (direct play vs transcode) | **Rust** | Depends on the negotiated session. |
+| Canonical download quality | **Rust** | Policy over domain data. |
+| Cache eviction, storage budget, sparse-range bookkeeping | **Rust** | Storage policy. |
+| Promotion to a `downloads` row, and what invalidates a cache entry | **Rust** | Domain state. |
+| Rendering the quality selector; remembering the last choice | **Frontend** | Presentation and a view preference. The *list* comes from Rust. |
+| WiFi-only / opt-in toggles | **Frontend collects, Rust enforces** | The control is UI; the gate must hold even if the UI never calls. |
+
+Borderline, recorded: the **default** playback bitrate could look like a user
+preference (frontend). It goes to Rust because it must be reconcilable with what
+the server can actually produce for a given media source — a preference the
+backend has to validate is not a preference the frontend can own alone. The
+frontend stores the user's *choice*; Rust decides what that choice resolves to.
+
+## Design
+
+### DR-121 — Bitrate selection in the player
+
+The player exposes the qualities Rust reports for the current item. Changing it
+re-negotiates the stream URL at the new quality and resumes at the current
+position. This is a deliberate, user-initiated interruption — a brief rebuffer is
+expected and acceptable, unlike the involuntary swap the earlier design would
+have needed.
+
+Constraints that must not be broken:
+
+- On Linux, video playback must keep using the HLS `master.m3u8` URL. CLAUDE.md
+  records that returning `stream.mp4` means transcoded playback never starts.
+  A quality change re-negotiates *within* HLS.
+- The quality→transcode-parameter mapping already exists in
+  `get_video_download_url` ([online.rs:1702-1717](../../src-tauri/src/repository/online.rs#L1702-L1717)).
+  Playback must call into the same mapping. Two copies of that table will drift.
+- Track selection (audio/subtitle) already survives a stream re-negotiation
+  elsewhere in the player; a quality change must preserve it too.
+
+### DR-122 — The playback path is ephemeral
+
+Playback bytes are not persisted unless DR-124 says they are keepable. No partial
+capture is ever retained across a quality change: on change, any in-flight capture
+for that session is abandoned and its partial file deleted.
+
+### DR-123 — The download path is independent
+
+Downloading the whole file is a separate operation through the existing download
+manager, at one canonical quality (default `original`, the direct static copy),
+using `/Videos/{id}/stream.mp4` — progressive and Range-capable, which is what
+the resumable download worker relies on. It is unaffected by what playback is
+doing, and playback is unaffected by it.
+
+Once complete it becomes an ordinary download row, so everything already built on
+top of downloads — offline browsing, `refresh_queue_local_sources`, the Downloads
+page — picks it up with no further work.
+
+**Prerequisite:** downloaded *video* is currently never played locally.
+`repository_get_video_stream_url` goes straight to the online repo and
+[player/[id]/+page.svelte:316](../../src/routes/player/[id]/+page.svelte#L316)
+calls it with no local check — so a completed video download is still streamed.
+This must be fixed or the whole feature is invisible for video.
+
+### DR-124 — Keep playback bytes only when they *are* the download
+
+Capture is enabled only where the played bytes and the canonical download artifact
+are the same thing — a **direct-play** session. Then:
+
+| Path | Mechanism |
+|---|---|
+| Android / ExoPlayer | `SimpleCache` + `CacheDataSource`, keyed by item id **and** media-source id so renditions never collide. LRU evictor sharing the existing smart-cache budget — not a second budget over the same disk. |
+| Linux audio / MPV | `stream-record`, set through the existing `set_property` plumbing. |
+| Linux video (HLS transcode) | **Not captured.** Segments are not a file; assembling one needs ffmpeg, which is not a dependency and which CI is forbidden from installing at job time. The download path (DR-123) covers this case instead. |
+
+Two abandonment rules, both of which must delete the partial rather than promote
+it:
+
+- **Seek during an mpv capture.** `stream-record` is documented as intended for
+  linear streams; seeking breaks the recording. Straight-through listening
+  captures, scrubbing does not.
+- **Any quality change** (DR-122).
+
+### DR-125 — Promotion, rendition, and invalidation
+
+A capture is promoted to a `downloads` row (`status = 'completed'`) only when it
+covers the whole resource. Partial captures stay cache and remain evictable.
+
+A new `downloads.source_rendition` column records the negotiated
+quality/container/codec of whatever produced the bytes; `NULL` for rows fetched by
+the existing paths, which are always `original`. This is what makes an "upgrade to
+original" action possible later, and what stops a 720p capture and a 4K download
+being indistinguishable rows.
+
+**Invalidation.** A quality change never touches a file that already exists —
+neither a permanent download nor a completed temporary one. Both remain valid
+copies of the rendition they hold, and deleting either would throw away bytes
+already paid for.
+
+What a quality change *does* invalidate is an **in-flight** capture or background
+download of cached media: it is abandoned and restarted at the newly chosen
+quality, because a capture spanning a rendition change is a splice of two
+encodings rather than a playable file (DR-122).
+
+So the rule is about *ongoing* work, not stored files. Nothing in this spec
+deletes user data.
+
+### Gating
+
+Capture and background download obey the existing WiFi-only gate and storage
+budget, and are off unless opted in. Enforcement is in Rust.
+
+## Out of scope
+
+- **Mid-playback switch onto a completing download.** Two independent paths make
+  it unnecessary; the download is used from the next boundary.
+- **Backfilling the unplayed remainder of a capture.** Watch 40 minutes and you
+  have 40 minutes; completing it needs sparse-range bookkeeping and a resumable
+  tail fetch. The DR-123 download path already produces a complete file, which is
+  the reason this can wait.
+- **Bundling ffmpeg** to make transcoded video capturable. Real option, large
+  packaging decision, its own proposal.
+- **Routing Linux video playback through `stream.mp4`.** Regresses a documented,
+  hard-won fix.
+
+## Acceptance criteria
+
+- [ ] The player offers the qualities Rust reports, and changing one resumes at
+      the same position with audio/subtitle selection preserved.
+- [ ] A quality change abandons any in-flight capture and leaves no partial file.
+- [ ] A quality change never deletes a `downloads` row.
+- [ ] A completed background download of a video is *played from disk* on the next
+      play (the DR-123 prerequisite).
+- [ ] A direct-play session played start-to-finish leaves a complete local file
+      with no second fetch; replaying it fetches no media bytes.
+- [ ] Seeking during an mpv capture abandons it; no truncated file is promoted.
+- [ ] A transcoded Linux video session is never captured, and never partially
+      promoted.
+- [ ] Promoted rows record their rendition; existing paths still record
+      `NULL`/`original`.
+- [ ] Gates hold with the setting off *and* with the frontend never sending it.
+- [ ] Eviction cannot delete bytes backing a promoted download row.
+- [ ] `bun run check`, `bun run test`, `cargo fmt`, `cargo clippy`,
+      `bun run test:rust`, `bun run check:boundary` pass; `bindings.ts`
+      regenerated if Rust types changed.
+
+## Testing
+
+Rust, table-driven and pure where possible: quality→params resolution shared with
+the download path; keepability (direct play vs transcode vs gate off); promotion
+(complete → promoted, partial → not, seek-abandoned → not, quality-changed → not);
+invalidation (evicts cache, never a download row); rendition round-trip.
+
+Android: instrumented — a played direct-play item yields cache entries, and a
+replay issues no media network request.
+
+Frontend: the quality list renders from backend data with no item-type or
+codec taxonomy in `src/`; the selector's remembered choice is a view preference.
+
+## TRACES
+
+| Piece | Tag |
+|---|---|
+| Quality selector + re-negotiation | `// TRACES: UR-070 \| DR-121` |
+| Ephemeral playback / capture abandonment | `// TRACES: UR-070 \| DR-122` |
+| Independent whole-file download + local video playback fix | `// TRACES: UR-071 \| DR-123, IR-032` |
+| ExoPlayer cache / mpv stream-record / keepability | `// TRACES: UR-071 \| DR-124` |
+| Promotion, `source_rendition`, invalidation | `// TRACES: UR-071 \| DR-125` |
+
+## Notes for the implementer
+
+- **A parallel Claude session is active in this repo.** `git diff` before
+  "repairing" anything you did not write.
+- Do not duplicate the quality→transcode-parameter table. Call the existing one.
+- Reuse the smart-cache storage budget; two budgets over one disk is how devices
+  fill up.
+- The `downloads` FK to `items` is relaxed (migration 005) — exercise promotion
+  for an item that was never cached.
+- Build DR-123's local-playback fix first. Without it nothing in this spec is
+  observable for video.

docs/specs/req-coverage-script-removal.md

@@ -0,0 +1,161 @@
+# Spec: Remove the broken `check-req-coverage.sh`
+
+**Status:** Implemented
+**Requirements:** supports DR-093 (see [traceability-gate-repair.md](traceability-gate-repair.md))
+**UX spec:** n/a — developer tooling.
+**Supersedes / revises:** n/a
+
+## Summary
+
+`scripts/check-req-coverage.sh` is broken, orphaned, and actively misleading: it
+reports `Total Requirements: 1`, zeros in every category, and then prints
+**"✨ All requirements have implementations!"**. Nothing references it — not CI,
+not `package.json`, not the docs. This spec deletes it, with a narrowly-scoped
+alternative (repair it) documented and rejected below.
+
+## Motivation
+
+Running it today produces:
+
+```
+Category Breakdown:
+UR:    0 requirements
+IR:    0 requirements
+DR:    0 requirements
+JA:    0 requirements
+
+Summary:
+Total Requirements:       1
+✅ Fully Implemented:     0 (0%)
+
+✨ All requirements have implementations!
+```
+
+Every number is wrong (the real totals are UR 61, IR 29, DR 89, JA 32), and the
+concluding message is the *opposite* of a warning — a developer running this to
+sanity-check coverage is told everything is fine.
+
+This is worse than having no script. It is a trap, and it sits in `scripts/`
+next to tools that do work, with nothing marking it as dead.
+
+Verification that it is genuinely orphaned:
+
+```console
+$ grep -rn "check-req-coverage" . --include='*.yml' --include='*.json' \
+      --include='*.sh' --include='*.md' | grep -v node_modules
+(no output)
+```
+
+## Layer assignment
+
+Developer tooling only; no application logic and nothing crosses the IPC
+boundary.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Requirement-coverage reporting | Build tooling — `extract-traces.ts` | One tool should own coverage analysis. A second, divergent implementation is how the two answers ("1 requirement" vs "211") came to disagree unnoticed. |
+
+## Design
+
+**Delete `scripts/check-req-coverage.sh`.**
+
+Coverage reporting is owned by [scripts/extract-traces.ts](../../scripts/extract-traces.ts),
+which is correct, is what CI runs, and gains a first-class local coverage mode
+in [traceability-gate-repair.md](traceability-gate-repair.md):
+
+```bash
+bun run traces:coverage   # the supported way to check coverage locally
+```
+
+Then check the sibling scripts for the same rot. `scripts/` also contains
+`check-test-coverage.sh` and `find-req-implementations.sh`, neither of which is
+referenced from `package.json`. An unreferenced script is never run and so rots
+silently — that is the actual failure mode being fixed here, and fixing only the
+one instance found by audit leaves the others to be rediscovered later.
+
+### Findings (investigation, 2026-07)
+
+All three scripts turned out to share a **single root cause**, and all three are
+deleted:
+
+| Script | Defect |
+|---|---|
+| `check-req-coverage.sh` | Reads `README.md`, which has held **zero** requirement rows since they moved to `docs/requirements.md` → `total_reqs=1`, every category 0, "✨ All requirements have implementations!" Also greps `src-tauri/` unscoped. |
+| `check-test-coverage.sh` | Greps `src-tauri/` unscoped — including **40 GB** of `target/` build artifacts. Hangs indefinitely; produces no output at all. |
+| `find-req-implementations.sh` | Same unscoped `src-tauri/` grep. Same hang. |
+
+So none of them were subtly wrong — two could never terminate, and the third
+inverted its own conclusion.
+
+They were nonetheless *salvageable*: scoping the greps to `src-tauri/src` and
+repointing at `docs/requirements.md` would be a few lines, and the `@req:` /
+`@req-test:` tags they read are still present in the tree (**146** and **76**
+occurrences).
+
+**Decision: delete all three anyway.** The tags are an undocumented parallel
+convention — `@req:` appears in no doc, and CLAUDE.md describes only `TRACES:`.
+Repairing the scripts would re-establish a second traceability system to keep in
+sync with the first, which is the same two-sources-of-truth condition that let
+"1 requirement" and "211 requirements" coexist unnoticed. `TRACES:` plus the
+repaired coverage engine ([traceability-gate-repair.md](traceability-gate-repair.md))
+already cover this ground.
+
+The existing `@req:` / `@req-test:` comments are left in place: they are
+harmless as prose, several encode genuinely useful test intent, and stripping
+222 comments across the tree is a large diff with no functional gain. They are
+simply no longer read by any tool.
+
+### Alternative considered: repair rather than delete
+
+Rejected. The script's output format duplicates what `traces:markdown` already
+generates, it has no tests, no caller, and no documented purpose distinct from
+`extract-traces.ts`. Repairing it recreates the two-sources-of-truth condition
+that produced the contradiction. If a shell-based coverage check is ever wanted,
+it should shell out to `traces:json` and `jq` rather than re-parse
+`requirements.md` independently.
+
+## Out of scope
+
+- The CI workflow denominators — [traceability-gate-repair.md](traceability-gate-repair.md).
+- Any change to `extract-traces.ts`'s output (that spec owns it).
+- Auditing scripts that *are* referenced from `package.json` — they run
+  regularly and would fail visibly.
+
+## Acceptance criteria
+
+- [ ] `scripts/check-req-coverage.sh` no longer exists.
+- [ ] `grep -rn "check-req-coverage" .` (excluding `node_modules` and this spec)
+      returns nothing — no dangling reference in CI, docs, or `package.json`.
+- [ ] `scripts/check-test-coverage.sh` and `find-req-implementations.sh` have each
+      been run and either wired into `package.json` or deleted; the decision and
+      reason are recorded in `scripts/README.md`. **Outcome: all three deleted —
+      see Findings.**
+- [ ] `scripts/README.md` documents `bun run traces:coverage` as the supported
+      way to check requirement coverage locally.
+- [ ] `bun run test:all` passes (confirms nothing invoked the deleted script).
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+
+## Testing
+
+No unit tests — this is a deletion. Verification is the grep in the acceptance
+criteria plus a green `bun run test:all`, which exercises the script paths that
+actually run.
+
+## TRACES
+
+No new requirement. The deletion is covered by **DR-093**
+([traceability-gate-repair.md](traceability-gate-repair.md)), which establishes
+`extract-traces.ts` as the single owner of coverage reporting. Note the removal
+in that DR's text when both land.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- Land this **after** or alongside [traceability-gate-repair.md](traceability-gate-repair.md),
+  so `bun run traces:coverage` exists before the broken script is removed and
+  developers are never left without a coverage command.
+- Check `docs/traceability-ci.md` and `docs/traces-quick-ref.md` for prose
+  references to the deleted script; the grep above covers `.md`, but read the
+  surrounding sentence rather than deleting the line mechanically.

docs/specs/scoped-search-boundary-implementation.md

@@ -0,0 +1,254 @@
+# Spec: Land the scoped-search boundary fix (implementation)
+
+**Status:** Stage 1 Implemented — Stage 2 (result-side grouping) outstanding
+**Requirements:** UR-049, UR-050 | DR-063, DR-066, DR-067 (existing — no new IDs)
+**UX spec:** n/a — zero user-visible change is the point (see Acceptance criteria).
+**Supersedes / revises:** implements [scoped-search-boundary.md](scoped-search-boundary.md),
+which specified this fix but was never built. That spec remains the **design
+authority**; this one is the delivery plan and status correction.
+
+## Summary
+
+[scoped-search-boundary.md](scoped-search-boundary.md) diagnosed a domain-taxonomy
+leak, specified the fix in full detail, and became the justification for the
+project's boundary rule in CLAUDE.md, the `check:boundary` tripwire, and the
+spec-review checklist. **The fix was never implemented.** The leak it describes
+is still live in `main`. This spec exists to close that gap and to correct the
+record — the codebase currently enforces a rule against a violation it still
+contains.
+
+## Motivation
+
+The mapping the rule forbids is present and in use:
+
+```ts
+// src/lib/utils/searchScope.ts:29-32
+const SCOPE_ITEM_TYPES: Record<Exclude<SearchScope, "all">, string[]> = {
+  music: ["MusicAlbum", "MusicArtist", "Audio", "Playlist"],
+  movies: ["Movie"],
+  tv: ["Series", "Episode"],
+};
+```
+
+This is not dead code. [library.ts:262](../../src/lib/stores/library.ts#L262)
+calls `scopeItemTypes(scope)` and puts the result straight into
+`options.includeItemTypes`. Meanwhile there is **no `SearchScope` anywhere in
+`src-tauri/`**:
+
+```console
+$ grep -rn "SearchScope" src-tauri/src --include='*.rs'
+(no output)
+```
+
+Three things make this the highest-value item found in the design-principles
+audit:
+
+1. **The rule's own founding incident is unremediated.** CLAUDE.md cites this
+   spec as "the incident this rule came from." A rule whose originating
+   violation is still shipping is not credible.
+2. **The tripwire cannot see it.** `bun run check:boundary` passes — it greps for
+   a multi-type array literal *at the query site*, and this one is assigned to a
+   named const and dereferenced elsewhere. Broadening the tripwire is specified
+   separately in [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md);
+   note that hardening it **without** landing this fix would turn `master` red.
+3. **The spec's own acceptance criterion fails today.** "Adding a hypothetical
+   new type to a scope requires editing only Rust" — adding a type to the Music
+   scope right now requires editing `searchScope.ts`.
+
+## Layer assignment
+
+Unchanged from [scoped-search-boundary.md](scoped-search-boundary.md) §Design;
+restated so this spec is reviewable on its own.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Scope → Jellyfin item types (`music` → `MusicAlbum`, `MusicArtist`, `Audio`, `Playlist`) | **Rust** | Domain vocabulary. Changes if Jellyfin adds/renames an item type — the litmus test's "yes" case. This is the leak being fixed. |
+| Result item → search group bucketing | **Rust** | Same taxonomy, result side. Classifying a `MediaItem` as a Song vs Album is Jellyfin vocabulary, not layout. |
+| `All` sends no filter at all (≠ union of enumerated types) | **Rust** | A query-shaping rule with a correctness consequence (Person/folder results would be silently dropped). Belongs with the expansion it qualifies. |
+| Group display order, labels, reordering, persistence | Frontend | Pure presentation — changes only if the UI is redesigned. Explicitly retained frontend-side. |
+| `resolveSearchScope(pathname)` — route → initial scope | Frontend | Routing/navigation, no Jellyfin vocabulary. Stays exactly as-is. |
+| Chip labels (`SCOPE_LABELS`), scope order (`SEARCH_SCOPES`) | Frontend | Display strings over an opaque enum. |
+| `GROUP_SCOPE` (which group belongs to which scope) | **Delete** | Borderline taxonomy, made redundant: once Rust filters by scope, out-of-scope groups arrive empty and drop via the empty-omit rule. Borderline defaults to Rust; here it defaults to *gone*. |
+
+The `SearchScope` and `SearchGroupId` **types** come to the frontend from
+generated `bindings.ts`. Naming an opaque enum variant is not taxonomy; knowing
+what item types it expands to is.
+
+## Design
+
+**Follow [scoped-search-boundary.md](scoped-search-boundary.md) §Design as
+written** — `SearchScope` enum + `item_types()` in `repository/types.rs`,
+`SearchOptions.scope`, `SearchGroupId`/`SearchGroup`/`GroupedSearchResult`,
+scope-wins precedence, `All` → `None` → no filter. It is not restated here;
+duplicating it would create two drifting copies of the same design.
+
+This spec adds only the delivery sequencing that the original left implicit.
+
+### Staging: land it in two reviewable pieces
+
+The original bundles the query side and the result side into one change. That is
+a large diff touching Rust types, `bindings.ts`, the store, and a component, with
+the `search-event` dual-payload hazard in the middle. Split it:
+
+**Stage 1 — query side (closes the leak).**
+`SearchScope` enum, `SearchOptions.scope`, command resolves scope →
+`include_item_types` in Rust, `library.ts` sends `{ scope }`, delete
+`SCOPE_ITEM_TYPES` and `scopeItemTypes()`. Result grouping stays as it is.
+
+After Stage 1 the actual boundary violation is gone and
+[boundary-tripwire-hardening.md](boundary-tripwire-hardening.md) can land safely.
+
+**Stage 2 — result side.** `SearchGroupId`/`SearchGroup`/`GroupedSearchResult`,
+Rust bucketing, both payloads converted, `composeSearchGroups()` shrunk,
+`GROUP_ITEM_TYPES`/`groupItemTypes()`/`GROUP_SCOPE` deleted.
+
+Both stages are required for the original spec's acceptance criteria to pass;
+Stage 1 alone leaves `GROUP_ITEM_TYPES` in the frontend. **Stage 1 is not a
+stopping point** — it is a review boundary. Do not mark the parent spec
+Implemented until Stage 2 lands.
+
+### Stage 1 — delivered (July 2026)
+
+- `SearchScope` enum + `item_types()` in [repository/types.rs](../../src-tauri/src/repository/types.rs);
+  `All` → `None` → no filter.
+- `SearchOptions.scope` with `resolve_scope()`; scope wins over
+  `include_item_types`, which stays for the non-search `get_items` callers.
+- `repository_search` resolves the scope **once, before** the cache/server split,
+  so both phases filter identically.
+- `SCOPE_ITEM_TYPES` and `scopeItemTypes()` deleted; `searchScope.ts` now
+  re-exports `SearchScope` from the generated bindings instead of a hand-written
+  union.
+- [library.ts](../../src/lib/stores/library.ts) sends `{ scope }`.
+- 8 Rust tests (`search_scope_tests`); the frontend suite now asserts the
+  *opaque scope* is sent rather than an item-type list.
+
+Verified: adding `"AudioBook"` to the Music scope changed **zero** files under
+`src/` — the criterion that failed before this work.
+
+**Stage 2 remains open**: `GROUP_ITEM_TYPES` / `groupItemTypes()` (result-side
+bucketing, single-type-per-group) are still in `searchScope.ts`, and both search
+payloads still carry a flat `MediaItem[]` rather than `GroupedSearchResult`.
+
+### 🔴 The `search-event` dual payload (Stage 2)
+
+The original flags this as "the single largest part of the change and the
+easiest to half-do." Restating because it is the one thing that silently breaks:
+search resolves **twice** — the command returns instant cache results, then the
+merged cache+server union arrives via `search-event`. Both payloads must carry
+`GroupedSearchResult`. Convert one and the UI flickers between shapes as server
+results land.
+
+Write the failing test for the *event* payload first — the command return is the
+obvious half, the event is the half that gets forgotten.
+
+### Note on `SearchOptions.scope` and specta
+
+`SearchOptions` is already `#[serde(rename_all = "camelCase")]` with
+`skip_serializing_if = "Option::is_none"`. Add `scope: Option<SearchScope>`
+following that pattern so `All`/absent omits the key. Regenerate `bindings.ts`
+— `SearchOptions` there is currently
+`{ limit?, includeItemTypes?, searchTerm? }` and must gain `scope?`. Never
+hand-edit it.
+
+## Out of scope
+
+- Redesigning anything in [scoped-search-boundary.md](scoped-search-boundary.md).
+  If implementation shows the design wrong, revise **that** spec, don't fork it.
+- Online/offline `include_item_types` **filtering** — already correct; only the
+  source of the type list moves.
+- Ranking within or across groups (DR-090 territory).
+- Chip UX, scope persistence, group-order persistence — unchanged.
+- The two lesser type-set sites in `DownloadedBrowse.svelte` and
+  `GenericMediaListPage.svelte`, handled in
+  [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md).
+- Broadening the tripwire itself — same sibling spec.
+
+## Acceptance criteria
+
+Inherits every criterion from [scoped-search-boundary.md](scoped-search-boundary.md)
+§Acceptance criteria. Additionally:
+
+- [ ] `grep -rn "SearchScope" src-tauri/src --include='*.rs'` returns matches —
+      the enum exists in Rust (it does not today).
+- [ ] `grep -n "SCOPE_ITEM_TYPES\|scopeItemTypes\|GROUP_ITEM_TYPES\|groupItemTypes" src/lib/utils/searchScope.ts`
+      returns nothing.
+- [ ] `grep -rn "scopeItemTypes" src/` returns nothing — including the
+      `library.ts` import and call site.
+- [ ] `SearchOptions` in `bindings.ts` includes `scope`; regenerated, not
+      hand-edited.
+- [ ] **Behaviour is byte-identical for the user**: same scoping, same groups,
+      same order, same empty-group omission, offline included. This spec is a
+      pure refactor — any visible change is a defect.
+- [ ] `All` scope sends no `includeItemTypes` (asserted in a Rust test, not by
+      inspection).
+- [ ] Adding a type to the Music scope requires editing **only** Rust —
+      demonstrate by making the edit and confirming no `src/` file changes.
+- [ ] `scoped-search-boundary.md` status flips to **Implemented**, and
+      `scoped-search.md`'s "frontend only, no Rust changes" framing gets a
+      banner pointing at the corrected design.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes.
+- [ ] Changed code carries `// TRACES:` comments (IDs below).
+
+## Testing
+
+Follow [scoped-search-boundary.md](scoped-search-boundary.md) §Testing. Emphases:
+
+**Rust** (`cargo test`):
+- `SearchScope::item_types()` per scope; `All` → `None`.
+- Scope resolution happens **before** the online/offline split, so both paths
+  get the same filter — a regression here is invisible until someone searches
+  offline.
+- `scope` set + `include_item_types` set → scope wins (the documented
+  precedence; assert it rather than trusting the doc).
+- Stage 2: mixed `Vec<MediaItem>` buckets correctly; unknown types dropped;
+  canonical group order; **the `search-event` payload is the grouped shape**.
+
+**Frontend** (`bun run test`):
+- `resolveSearchScope()` tests in `searchScope.test.ts` must pass **unchanged** —
+  they cover the part that is not moving, and are the regression net proving the
+  refactor didn't disturb routing.
+- `library.ts` sends `{ scope }` and never `includeItemTypes` for search.
+- `composeSearchGroups()` over fixture `SearchGroup[]` with no `.type`
+  inspection in the implementation.
+
+**Offline parity:** run a scoped search with the server unreachable and confirm
+identical grouping. The offline repository path honours `include_item_types`
+independently, and this is the case most likely to be missed.
+
+## TRACES
+
+No new requirement IDs — this implements existing ones. Retag as the code moves:
+
+```rust
+// src-tauri/src/repository/types.rs
+/// TRACES: UR-049 | DR-063
+pub enum SearchScope { … }
+```
+
+```typescript
+// src/lib/utils/searchScope.ts — keep the file header; it retains
+// resolveSearchScope + group-order presentation logic.
+// TRACES: UR-049, UR-050 | DR-063, DR-066, DR-067
+```
+
+Update DR-063's text in `requirements.md` to state that scope expansion is owned
+by Rust, so the requirement stops describing the leaked design. New Rust tests
+take `@req-test: UT-089` onward (next free UT is **UT-089**).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Read [scoped-search-boundary.md](scoped-search-boundary.md) first.** This
+  spec is deliberately thin on design; that one is the authority.
+- Sequence with the sibling specs: **Stage 1 here → then
+  [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md)**. Hardening
+  the tripwire first turns `master` red on a known-unfixed violation.
+- `git log --oneline -- docs/specs/scoped-search-boundary.md` is worth a look
+  before starting — understanding why the fix stalled may surface a constraint
+  the spec didn't record.
+- The user-visible-change count for this spec is zero. If QA reports a
+  difference in search results, that is a bug in the refactor, not an
+  improvement.

docs/specs/scoped-search-boundary.md

@@ -0,0 +1,273 @@
+# Spec: Move search scope taxonomy behind the Rust boundary
+
+**Status:** Proposed
+**Scope:** Rust + Frontend. **Revises a decision in
+[scoped-search.md](scoped-search.md).**
+**Requirements:** UR-049, UR-050 (existing) → new DRs for the boundary move
+(allocate on implementation; suggested DR-063/DR-065/DR-067 revisions plus one
+new DR for the grouped result shape — see [requirements.md](../requirements.md)).
+**UX spec:** unchanged — [ux-flows.md §6](../ux-flows.md). This is a pure
+architecture/boundary change with **no user-visible behaviour difference**.
+
+## Why this spec exists
+
+[scoped-search.md](scoped-search.md) shipped scoped search as "frontend only, no
+Rust changes." That was the smallest wiring change, and it worked — but it left
+**Jellyfin's item-type taxonomy encoded in the presentation layer**, which
+violates the project's core boundary rule ("Svelte frontend — presentation
+only"; all business logic in Rust — see [CLAUDE.md](../../CLAUDE.md) and
+[architecture/02-svelte-frontend.md](../architecture/02-svelte-frontend.md)).
+
+The offending knowledge lives in
+[searchScope.ts](../../src/lib/utils/searchScope.ts):
+
+```ts
+const SCOPE_ITEM_TYPES = {
+  music:  ["MusicAlbum", "MusicArtist", "Audio", "Playlist"],
+  movies: ["Movie"],
+  tv:     ["Series", "Episode"],
+};
+const GROUP_ITEM_TYPES = {
+  songs: ["Audio"], albums: ["MusicAlbum"], artists: ["MusicArtist"],
+  movies: ["Movie"], tvShows: ["Series", "Episode"],
+};
+```
+
+This is a **domain definition** — "what the category *Music* means in Jellyfin's
+vocabulary" — expressed twice, in the wrong layer. The concrete failure it
+creates: the day the backend starts returning a type the frontend never
+enumerated (e.g. `MusicVideo`, or Jellyfin renaming a kind), search silently
+drops it from both the query filter and the result buckets, and nothing in the
+Rust layer — the actual authority on Jellyfin's API — can correct it. Two
+sources of truth that will drift.
+
+**This must be fixed while the feature is uncommitted**, before the leak ships
+baked into a released wire contract.
+
+### What is *not* a leak (leave it alone)
+
+Single concrete-type list pages are **not** business logic and stay as-is:
+
+- `music.ts` → `["MusicAlbum"]` / `["Playlist"]`, `movies.ts` → `["Movie"]`,
+  `tv.ts` → `["Series"]`
+- `GenericMediaListPage.svelte` → `[config.itemType]`
+- `ArtistDetailView`, `RelatedItemsSection`, `AddToPlaylistModal`,
+  `PersonDetailView`
+
+"This page shows albums" is a legitimate presentation choice expressed through a
+generic `getItems(parentId, { includeItemTypes })` API. Only the **search scope
+taxonomy** (a semantic category → many types, defined once and reused) crosses
+the line. Do **not** invent a backend enum for every list page — that is
+over-abstraction, not cleaner separation.
+
+## The boundary rule after this change
+
+> The frontend never names a Jellyfin item type **in connection with search.**
+> It sends an opaque `scope`, and receives results already sorted into labelled
+> groups. The frontend owns only **group order** (presentation) and
+> **rendering**.
+
+## Design
+
+### Rust owns scope → item-types (query side)
+
+Add an opaque enum that crosses IPC, and move the expansion table into Rust:
+
+```rust
+// repository/types.rs
+#[derive(specta::Type, Serialize, Deserialize, Clone, Copy, Debug)]
+#[serde(rename_all = "camelCase")]
+pub enum SearchScope { All, Music, Movies, Tv }
+
+impl SearchScope {
+    /// The Jellyfin item types this scope requests, or None for `All`
+    /// (which must send NO includeItemTypes — see below).
+    pub fn item_types(self) -> Option<Vec<String>> {
+        match self {
+            SearchScope::All    => None,
+            SearchScope::Music  => Some(vec!["MusicAlbum", "MusicArtist", "Audio", "Playlist"]
+                                        .into_iter().map(String::from).collect()),
+            SearchScope::Movies => Some(vec!["Movie".into()]),
+            SearchScope::Tv     => Some(vec!["Series".into(), "Episode".into()]),
+        }
+    }
+}
+```
+
+`SearchOptions` gains `scope` and the search command resolves it into the
+existing `include_item_types` filter **inside Rust**, before dispatching to the
+online/offline paths (which already honour `include_item_types` — do not touch
+their filtering, per [scoped-search.md](scoped-search.md) §Background 2).
+
+```rust
+pub struct SearchOptions {
+    pub limit: Option<usize>,
+    pub search_term: Option<String>,
+    pub scope: Option<SearchScope>,        // NEW
+    // include_item_types stays for the single-type list-page callers,
+    // but the SEARCH command derives it from `scope` when scope is set.
+}
+```
+
+**Precedence:** if `scope` is set it wins; `include_item_types` remains for the
+non-search `getItems` callers. Document this so a future reader does not send
+both.
+
+**`All` sends no filter.** Preserve the existing invariant: `All` must omit
+`includeItemTypes` entirely, not send the union of every enumerated type — types
+nobody listed (Person, folders) would otherwise be filtered out. This is why
+`item_types()` returns `Option`, and the command must skip the filter on `None`.
+
+### Rust owns result bucketing (result side)
+
+Results arrive **pre-grouped**. Rust classifies each returned `MediaItem` into a
+group by its type — the `GROUP_ITEM_TYPES` knowledge, moved to the authority:
+
+```rust
+#[derive(specta::Type, Serialize, Deserialize, Clone, Copy, Debug)]
+#[serde(rename_all = "camelCase")]
+pub enum SearchGroupId { Songs, Albums, Artists, Movies, TvShows }
+
+#[derive(specta::Type, Serialize, Deserialize, Clone, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchGroup { pub id: SearchGroupId, pub items: Vec<MediaItem> }
+
+#[derive(specta::Type, Serialize, Deserialize, Clone, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupedSearchResult { pub groups: Vec<SearchGroup> }
+```
+
+Rust emits **every** non-empty group it can classify, in a stable canonical
+order. It does **not** apply the user's ordering or drop out-of-scope groups —
+those are presentation and stay frontend-side (see below). Items whose type maps
+to no group are omitted from grouped output (same as today's frontend filter).
+
+### 🔴 The `search-event` wrinkle — both payloads must change
+
+Search returns results **twice**: the command resolves with instant local-cache
+results, then the merged cache+server union arrives later via the `search-event`
+listener (see [library.ts](../../src/lib/stores/library.ts) `search()` and
+[architecture/03-data-flow.md](../architecture/03-data-flow.md)). **Both** the
+command return value **and** the `search-event` payload must carry
+`GroupedSearchResult`. If only one is converted, the instant results group and
+the merged ones do not (or vice versa), and the UI flickers between shapes. This
+is the single largest part of the change and the easiest to half-do.
+
+### What the frontend keeps (all pure presentation)
+
+[searchScope.ts](../../src/lib/utils/searchScope.ts) **retains**:
+
+- `SearchScope` type — now sourced from the generated bindings, mirroring the
+  Rust enum (delete the hand-written union).
+- `SCOPE_LABELS`, `SEARCH_SCOPES` (chip labels / order).
+- `resolveSearchScope(pathname)` — route → initial scope. Pure, DOM-free,
+  unit-tested. **Stays exactly as-is.**
+- `SearchGroupId` (from bindings), `GROUP_LABELS`.
+- `normalizeGroupOrder`, `groupsForScope`, `moveGroup`, `reorderGroups`,
+  `DEFAULT_GROUP_ORDER` — group-order persistence and reordering, all
+  presentation.
+
+[searchScope.ts](../../src/lib/utils/searchScope.ts) **loses**:
+
+- `SCOPE_ITEM_TYPES`, `GROUP_ITEM_TYPES` (moved to Rust).
+- `scopeItemTypes()`, `groupItemTypes()`.
+- The `.type`-inspecting body of `composeSearchGroups()`.
+
+`composeSearchGroups()` shrinks to a **presentation composition over Rust's
+groups** — no `.type` inspection anywhere:
+
+```ts
+// Take Rust's pre-bucketed groups; drop out-of-scope, sort by saved order,
+// attach labels, omit empties. No Jellyfin type vocabulary.
+composeSearchGroups(groups: SearchGroup[], scope, order): DisplayGroup[]
+```
+
+`GROUP_SCOPE` (which group belongs to which scope) is a borderline case: it is
+"is Songs part of the Music scope," arguably taxonomy. But because Rust already
+filtered the query by scope, out-of-scope groups will simply be **empty** and
+drop out via the empty-omit rule — so the frontend does not strictly need
+`GROUP_SCOPE` for correctness once Rust filters. **Recommendation:** delete
+`GROUP_SCOPE` and rely on empty-omission; if kept for belt-and-suspenders, treat
+it as a display hint, not authority.
+
+### Frontend call-site changes
+
+- [library.ts](../../src/lib/stores/library.ts) `search(query, scope)` sends
+  `{ scope }` in `SearchOptions` instead of computing `includeItemTypes`.
+  Everything else (requestId bump, stale guard, 10s timeout, empty-query clear,
+  event merge) is preserved.
+- [SearchResults.svelte](../../src/lib/components/search/SearchResults.svelte)
+  consumes `SearchGroup[]` from the store instead of a flat `MediaItem[]` +
+  client-side `composeSearchGroups(results, …)`. The store now holds grouped
+  results.
+- [search/+page.svelte](../../src/routes/search/+page.svelte) is unchanged in
+  behaviour; only the type it passes to `SearchResults` changes.
+
+## Out of scope
+
+- Any change to online/offline `include_item_types` **filtering** — it already
+  works; only the *source* of the type list moves.
+- Single concrete-type list pages (see "What is not a leak").
+- Ranking within or across groups.
+- The UX / chip behaviour / persistence mechanism — all unchanged from
+  [scoped-search.md](scoped-search.md).
+
+## Acceptance criteria
+
+- [ ] No Jellyfin item-type string literal (`"MusicAlbum"`, `"Audio"`, …) remains
+      in `searchScope.ts` or any search call path. Verify:
+      `grep -rn '"MusicAlbum"\|"MusicArtist"\|"Audio"\|"Series"\|"Episode"\|"Movie"\|"Playlist"' src/lib/utils/searchScope.ts src/lib/stores/library.ts` returns nothing.
+- [ ] `SearchScope` and `SearchGroupId` in the frontend come from the generated
+      `bindings.ts`, not hand-written unions.
+- [ ] Search behaviour is **identical** to today for the user: same scoping, same
+      groups, same order, same empty/out-of-scope omission, offline included.
+- [ ] Both the command return and the `search-event` payload carry the grouped
+      shape; no shape flicker between instant and merged results.
+- [ ] `All` scope still sends no `includeItemTypes` (assert in a Rust test).
+- [ ] Adding a hypothetical new type to a scope requires editing **only** Rust.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check` and `bun run test` pass; `bindings.ts` regenerated and
+      committed.
+
+## Testing
+
+**Rust** (`src-tauri`, `cargo test`):
+- `SearchScope::item_types()`: each scope's list, and `All` → `None`.
+- Search command: `scope: Music` resolves to the four music types on the query;
+  `scope: All` sends no `include_item_types`.
+- Bucketing: a mixed `Vec<MediaItem>` classifies into the right `SearchGroupId`s;
+  unknown types are dropped; groups come out in canonical order.
+- The `search-event` payload is the grouped shape (guard the wrinkle).
+
+**Frontend** (vitest, `src/lib/**/*.test.ts`) — update existing tests:
+- `librarySearchScope.test.ts` currently asserts `includeItemTypes` on the
+  outgoing options — **rewrite** to assert `scope` is sent instead.
+- `searchScope.test.ts` — drop `scopeItemTypes`/`groupItemTypes` cases; keep and
+  extend `resolveSearchScope`, order normalize/move/reorder, and the new
+  compose-over-groups (order + empty-omit, no type inspection).
+- `searchGroupOrder.test.ts` — unchanged.
+
+## TRACES
+
+Per [CLAUDE.md](../../CLAUDE.md), tag requirement-implementing code:
+- `SearchScope` enum + `item_types()` + search command scope resolution:
+  `UR-049 | DR-063` (revised — resolution now Rust-side).
+- Grouped result shape + bucketing: `UR-050 | DR-067` (revised) + a new DR for
+  the wire shape.
+- `library.ts` store change: `UR-049 | DR-065` (revised — sends scope not types).
+
+## Notes for the implementer
+
+- This spec **revises** [scoped-search.md](scoped-search.md) §Background 2 and
+  §Design "Scope model / Threading scope through the store," which asserted no
+  Rust change. Update that spec's status to note the boundary was moved, or add a
+  banner pointing here — do not leave the two specs contradicting silently.
+- The IPC camelCase rule applies to the new enums and structs
+  ([CLAUDE.md](../../CLAUDE.md)): `#[serde(rename_all = "camelCase")]` on structs;
+  the tagged-enum tag convention if any enum becomes tagged. Add/extend a
+  `tauriIntegration`-style test if a new command is introduced.
+- Regenerate `bindings.ts` via the tauri-specta build step after changing Rust
+  types; do not hand-edit it.
+- **Another Claude session may be active in these same files** (per project
+  memory). `git diff` before repairing anything unexpected; these search files
+  are exactly the ones a parallel session touched.

docs/specs/scoped-search.md

@@ -0,0 +1,208 @@
+# Spec: Context-scoped search with filter chips and configurable group order
+
+> ⚠️ **Superseded in part by
+> [scoped-search-boundary.md](scoped-search-boundary.md).** The "frontend only,
+> no Rust changes" decision below (§Background 2, §Design "Scope model" and
+> "Threading scope through the store") left Jellyfin's item-type taxonomy in the
+> presentation layer, which violates the backend/frontend boundary. The taxonomy
+> is being moved into Rust. The **user-facing behaviour and UX in this spec are
+> unchanged**; only where the scope→item-type mapping and result bucketing live
+> changes. Read the boundary spec before touching search code.
+>
+> **Progress:** the scope→item-type mapping now lives in Rust
+> (`SearchScope::item_types()`); the frontend sends an opaque scope. Result-side
+> bucketing (`GROUP_ITEM_TYPES`) is still frontend-side — see
+> [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md)
+> §Stage 2.
+
+**Status:** Implemented (boundary revision: query side done, result side pending)
+**Scope:** Frontend only. No Rust changes required. *(Revised — see banner.)*
+**Requirements:** UR-049 → DR-063, DR-064, DR-065; UR-050 → DR-066, DR-067
+(see [requirements.md](../requirements.md)).
+**UX spec:** [ux-flows.md §6](../ux-flows.md) — §6.1 scope, §6.2 layout,
+§6.3 group order, §6.4 current deviations.
+
+## Summary
+
+Two related changes to search:
+
+1. **Scope** — a search started inside a library searches *that* library.
+   Started from Home, `/library`, or the search tab, it searches everything.
+   The active scope shows as a chip row under the search bar, preselected from
+   context and freely changeable without retyping.
+2. **Group order** — the order result groups appear in (Songs, Albums, Artists,
+   Movies, TV Shows) becomes a drag-and-drop setting instead of being hardcoded.
+
+## Motivation
+
+Searching "office" while browsing TV currently returns music albums, because
+both search entry points call the same unscoped query. The user has already
+told us what they're looking at; ignoring that makes search feel indiscriminate
+and pushes the relevant result below unrelated media.
+
+## Background: what already exists
+
+Verified in code — **most of the plumbing is already there.** This is
+substantially a wiring task, not new infrastructure.
+
+1. **`SearchOptions` already carries the filter.**
+   [bindings.ts](../../src/lib/api/bindings.ts) —
+   `SearchOptions = { limit?, includeItemTypes?, searchTerm? }`.
+
+2. **Rust already honours `include_item_types` on both paths** — online
+   ([online.rs](../../src-tauri/src/repository/online.rs), in the `get_items`
+   options mapping) and offline
+   ([offline.rs](../../src-tauri/src/repository/offline.rs), which builds a SQL
+   type filter from it). **Do not add Rust code for filtering.**
+
+3. **Per-page list search already does this correctly.**
+   [GenericMediaListPage.svelte](../../src/lib/components/library/GenericMediaListPage.svelte)
+   passes `includeItemTypes: [config.itemType]` to `repo.search(...)`. Use it as
+   the reference for the call shape, including the `requestId` handling.
+
+4. **The gap is exactly one function.**
+   [library.ts](../../src/lib/stores/library.ts) — `search(query)` takes only a
+   query and calls `repo.search(query, { limit: 10000 }, requestId)`, dropping
+   any scope. Both callers
+   ([search/+page.svelte](../../src/routes/search/+page.svelte) and
+   [library/+layout.svelte](../../src/routes/library/+layout.svelte)) go through
+   it.
+
+5. **Group order is hardcoded in markup.**
+   [SearchResults.svelte](../../src/lib/components/search/SearchResults.svelte)
+   categorizes into `music{tracks,albums,artists} / movies / tvShows` and
+   renders three fixed sections in source order.
+
+6. **Frontend preferences persist via `localStorage`**, per the existing
+   `viewMode` precedent in [library.ts](../../src/lib/stores/library.ts)
+   (`jellytau-view-mode`). Follow that pattern — **do not** add a Rust settings
+   command for this.
+
+## Design
+
+### Scope model
+
+One `SearchScope` type, defined once and shared:
+
+| Scope | `includeItemTypes` | Chip label |
+|-------|--------------------|------------|
+| `all` | *unset* | All |
+| `music` | `MusicAlbum`, `MusicArtist`, `Audio`, `Playlist` | Music |
+| `movies` | `Movie` | Movies |
+| `tv` | `Series`, `Episode` | TV |
+
+`all` must send **no** `includeItemTypes` key rather than a list of every type —
+the two are not equivalent for item types not enumerated here (Person, folders).
+
+### Route → scope resolution (DR-063)
+
+A pure function, unit-testable without a DOM:
+
+```ts
+resolveSearchScope(pathname: string): SearchScope
+```
+
+- `/library/music*` → `music`
+- `/library/movies*` → `movies`
+- `/library/tv*` → `tv`
+- `/`, `/library`, `/search`, anything else → `all`
+
+Note `/library/shows/genres` exists as a route; treat `shows` as `tv`. Check the
+current route list before finalising — do not assume this table is exhaustive.
+
+### Scope is a starting point, not a lock (DR-064)
+
+The resolved scope sets the **initial** chip only. Once the user taps a chip,
+their choice governs until they leave the search surface. Concretely: derive the
+initial value from the route, hold it in component state, and do not re-derive
+it on every navigation — otherwise a user who widens to All snaps back to TV.
+
+Changing a chip re-runs the current query at the new scope. Changing the query
+keeps the current scope.
+
+### Threading scope through the store (DR-065)
+
+Extend the store's search signature to accept an optional scope and pass
+`includeItemTypes` down to `repo.search`. Preserve the existing behaviour
+exactly: the `requestId` bump, the stale-response guard, the `search-event`
+listener merge, the 10s timeout, and the empty-query clear path. This is an
+additive parameter — no caller should break.
+
+### Group order (DR-066, DR-067)
+
+Persist an ordered array of group ids:
+
+```
+["songs", "albums", "artists", "movies", "tvShows"]   // shipped default
+```
+
+Rendering composes scope and order as **two independent axes**, in this order:
+
+1. drop groups outside the active scope,
+2. sort the remainder by the user's saved order,
+3. omit groups that came back empty.
+
+Scope never rewrites the saved order — narrowing to Music and back to All must
+restore the user's full arrangement. See [ux-flows.md §6.3](../ux-flows.md) for
+the worked example.
+
+Settings gets a reorderable list. **Dragging alone is not sufficient**: provide
+keyboard-operable move up/down controls with proper labels, or the setting is
+unusable with a screen reader and on any pointerless input.
+
+Unknown or missing ids in the stored array must not crash rendering — treat the
+stored order as a hint, append any group it doesn't mention, and ignore ids that
+no longer exist. A user upgrading from a build with fewer groups must not lose
+the new ones.
+
+## Out of scope
+
+- Ranking *within* a group. Order is presentation-only.
+- Server-side search ranking or the Jellyfin query itself.
+- Scope chips on the per-page list search in `GenericMediaListPage` — that page
+  is already implicitly scoped by its own `itemType`.
+- Any Rust change.
+
+## Acceptance criteria
+
+- [ ] Searching from inside Music returns no movies or TV; from inside TV, no music.
+- [ ] Searching from Home, `/library`, or the search tab returns all types.
+- [ ] The chip row renders under the search bar on both the search page and the
+      in-library header search, with the context-derived chip preselected.
+- [ ] Tapping a chip re-runs the search with the query preserved; editing the
+      query preserves the selected chip.
+- [ ] Tapping "All" from a context-scoped search widens results without retyping.
+- [ ] Result groups render in the user's configured order, with out-of-scope and
+      empty groups omitted and relative order preserved.
+- [ ] Group order is reorderable by drag **and** by keyboard, persists across
+      restarts, and ships with the documented default.
+- [ ] Offline search respects scope (the offline path already filters — verify,
+      don't reimplement).
+- [ ] `bun run check` and `bun run test` pass.
+
+## Testing
+
+Follow the existing frontend test conventions (vitest, `src/lib/**/*.test.ts`).
+
+- `resolveSearchScope` — pure unit tests over the route table, including the
+  `/library/shows/genres` case and unknown routes falling back to `all`.
+- Scope → `includeItemTypes` mapping, asserting `all` omits the key entirely.
+- The compose step: scope filter + user order + empty-group omission, including
+  the "narrow then widen restores order" case and a stored order containing an
+  unknown id.
+- Store-level: scoped search forwards `includeItemTypes` to the repository, and
+  the existing stale-`requestId` guard still discards superseded responses.
+
+New requirement-implementing code needs `TRACES:` comments — see
+[CLAUDE.md](../../CLAUDE.md). Suggested tags: the scope resolver and chip row
+`UR-049 | DR-063, DR-064`, the store change `UR-049 | DR-065`, the settings list
+and ordered rendering `UR-050 | DR-066, DR-067`.
+
+## Notes for the implementer
+
+- Read [ux-flows.md §6](../ux-flows.md) first — it is the behavioural spec; this
+  document is the implementation plan.
+- The IPC camelCase rule applies to anything new that crosses the boundary
+  ([CLAUDE.md](../../CLAUDE.md)) — though this change should not add commands.
+- Another session may be active in this repo. Check `git diff` before
+  "repairing" unexpected changes.

docs/specs/series-current-episode-navigation.md

@@ -0,0 +1,239 @@
+# Spec: series navigation lands on the current episode
+
+**Status:** Accepted
+**Requirements:** UR-062 → DR-101, DR-102, DR-103, DR-104, DR-107; UR-063 → DR-105; UR-064 → DR-106
+**UX spec:** [ux-flows.md §5B.1](../ux-flows.md), [§5B.2](../ux-flows.md), [§5B.4](../ux-flows.md), [§5B.5](../ux-flows.md)
+
+## Summary
+
+Opening a TV series lands you where you actually are in it: the seasons render
+as collapsible sections with **only the current season expanded**, the current
+episode highlighted and scrolled into view, and the hero button opens that
+episode's focus view (labelled `Resume S2E4` / `Play S1E1`) instead of the first
+season. A season stops being a destination of its own — every route that used to
+land on `/library/<seasonId>` now lands on the series with that season in view,
+so the full cross-season episode list is always reachable in one place. Watch
+history can be erased per series and per season. Separately, each video library
+collapses from three routes (landing, all-titles, genres) to one route with
+in-page tabs.
+
+## Motivation
+
+Two problems, reported together.
+
+**1. Series navigation dead-ends at season 1.** The series detail page's Play
+button resolved its target as `$libraryItems[0]` — the first *season* child,
+ordered by `SortName` — and navigated to `/player/<seasonId>`. The player route
+classifies `season` as a container kind and bounces it back to
+`/library/<seasonId>`. So Play on a series played nothing; it navigated you to
+the season-1 page. Opening a series without pressing Play rendered every season
+stacked but scrolled to the top, so a viewer 4 seasons deep had to scroll past
+everything they had already watched.
+
+The backend has been able to answer "where is this viewer in this show" the
+whole time: `repository_get_next_up_episodes(handle, series_id, limit)` is wired
+end-to-end to `/Shows/NextUp?SeriesId=`. **Both frontend call sites pass
+`undefined` for `series_id`** — the per-series capability existed and was never
+used.
+
+**2. Seasons are an accidental page.** There is no season route. `/library/
+<seasonId>` falls through the detail page's `kind` chain into the generic
+"Contents" poster grid, which contradicts ux-flows §5A.2 (episodes in a season
+must render as a row list). Worse, clicking an episode from that grid opens a
+*bare* Episode page, which §5B.1 explicitly forbids. Four call sites fed it: the
+episode breadcrumb, `handleItemClick case "season"`, the TV landing page, and
+the broken Play button above.
+
+**3. Too many video library routes.** Seven routes serve two media types, and the
+naming does not even agree with itself: `/library/tv` + `/library/tv/shows` +
+`/library/shows/genres` versus `/library/movies` + `/library/movies/all` +
+`/library/movies/genres`. The genre routes do not share a prefix, which
+`searchScope.ts:45` carries an apologetic comment about. The two "all" pages are
+27-line config wrappers over the same `GenericMediaListPage`.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Which episode is "current" for a series (resume → next-up → first unwatched → first) | **Rust** | Domain policy over Jellyfin user-data semantics. It changes if Jellyfin changes what `UserData.is_played` means, if Next Up's rules change, or if we decide a 98%-watched episode counts as finished. It does not change if the UI is redesigned. |
+| Gathering a series' episodes across all seasons in broadcast order | **Rust** | Jellyfin's shape (episodes hang off season folders, except when a series is flat and they hang off the series) is provider vocabulary. The frontend already reimplemented this fan-out *and* its flat-series fallback; that is domain knowledge that leaked. |
+| Ordering rule for "series order" (season index, then episode index, specials last) | **Rust** | Season 0 = specials is a Jellyfin convention, not a layout choice. |
+| Scrolling the current episode into view; the highlight ring and `Up next` badge | Frontend | Pure presentation. Changes only if the page is redesigned. |
+| Which seasons start expanded | Frontend | Consumes the backend's answer (`currentEpisode`) to decide layout. The *decision* about where the viewer is stays in Rust; only "and therefore this section opens" is here. |
+| What "erase watch history" means (played flag + resume position, recursive over a container) | **Rust** | Jellyfin user-data semantics. Changes if the server's mark-unplayed behaviour changes; unaffected by any UI redesign. |
+| Refusing to clear history while offline | **Rust** | A data-integrity rule, not a disabled button: history cleared only locally would be undone by the next sync. The UI disabling the button is a courtesy on top. |
+| Play button *label* (`Resume S2E4` vs `Play S1E1`) | Frontend | Rendering a decision the backend already made (the returned episode plus its resume position). |
+| Which route Play navigates to | Frontend | Navigation is presentation. |
+| Redirecting `/library/<seasonId>` to the series anchor | Frontend | Route topology. |
+| Episode-strip window size (3 before / 6 after) | Frontend | A layout constant; §5B.2 owns it. |
+| Library page tabs and the `?view=` param | Frontend | View preference and route topology. |
+
+Borderline row — **the strip's cross-season *ordering*** is Rust (it is series
+order, above), but the *window* taken from that ordered list is frontend. The
+tie-breaker: the list handed to the frontend is already correct and complete;
+choosing how much of it fits on screen is layout.
+
+## Design
+
+### Rust: the current-episode policy
+
+Two new pieces, split so the policy is unit-testable without a repository.
+
+**Pure policy** — `src-tauri/src/repository/series_progress.rs`:
+
+```rust
+/// Series order: season index asc, then episode index asc. Specials (season 0)
+/// sort after every numbered season rather than before season 1.
+pub fn sort_series_order(episodes: &mut [MediaItem]);
+
+/// The episode a viewer should land on, given everything already fetched.
+/// Order: in-progress episode → Next Up → first unwatched → first episode.
+pub fn pick_current_episode(
+    episodes: &[MediaItem],   // series order
+    next_up: &[MediaItem],
+    resume: &[MediaItem],
+) -> Option<MediaItem>;
+```
+
+Why that order:
+
+- **In-progress wins** because a partially-watched episode is literally where
+  the viewer stopped; Next Up would skip past it. Ties break toward the earliest
+  in series order, so a viewer who dipped into a later episode still resumes the
+  one they are actually working through.
+- **Next Up second** because it is the server's own answer, and it accounts for
+  history we do not cache.
+- **First unwatched third** — the offline repository returns an empty vec for
+  Next Up (`offline.rs:1247`), so without this fallback the whole feature would
+  be online-only. This is the offline path, not dead code.
+- **First episode last** so a never-watched series lands on S1E1 rather than
+  nothing.
+
+A `resume`/`next_up` entry that is not among `episodes` is still honoured — it
+comes from the same server and may carry an id the season fan-out missed — but
+it must belong to this series.
+
+**Fetch + command** — `src-tauri/src/commands/repository.rs`:
+
+```rust
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_series_episodes(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    series_id: String,
+) -> Result<Vec<MediaItem>, String>
+
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_series_current_episode(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    series_id: String,
+) -> Result<Option<MediaItem>, String>
+```
+
+Frontend params are camelCase (`{ handle, seriesId }`) per the Tauri v2 rule.
+
+`repository_get_series_episodes` performs the fan-out the frontend used to do:
+`get_items(series_id)` → seasons → `get_items(season_id)` per season, plus the
+flat-series fallback (a series whose children are episodes, not seasons), then
+`sort_series_order`. `repository_get_series_current_episode` calls it, adds
+`get_next_up_episodes(Some(series_id), Some(1))` and
+`get_resume_items(Some(series_id), Some(10))`, and applies `pick_current_episode`.
+Both tolerate a failing Next Up (offline) by treating it as empty rather than
+failing the whole call.
+
+### Frontend: series page
+
+- `loadItem()` calls `repositoryGetSeriesEpisodes` once instead of fanning out
+  over seasons itself, and `repositoryGetSeriesCurrentEpisode` for the anchor.
+  Season *headers* still come from `get_items(seriesId)`; the page groups the
+  returned episodes under them by `parentIndexNumber`.
+- No `?episode=` param → series view, `SeasonSection` receives
+  `currentEpisodeId`, `EpisodeRow` renders the highlight and scrolls itself into
+  view (`scrollIntoView({ block: "center" })`, the existing `focused` mechanism,
+  now distinguishing *focused* from *current*).
+- Seasons are collapsible and **only the current season is expanded**
+  (`initialExpandedSeasons`). Without this a ten-season show renders every
+  episode of every season at once and buries the one the viewer came for. A
+  collapsed season still shows its episode count and watched count, so progress
+  is legible without expanding. Toggle state is local and not persisted — it is
+  a reading position, not a preference.
+- Hero Play → `goto(/library/<seriesId>?episode=<currentId>)`, i.e. the Episode
+  Focus View, where an explicit Play/Resume starts playback. This follows
+  ux-flows §5B.5's "tap opens, never commits" rule: Play on a *container* is
+  navigation; Play on a *leaf* (the focus view, a movie) commits.
+- Clicking an episode in a season section → `?episode=` swap, not
+  `/player/<id>`. §5B.1.
+
+### Frontend: seasons are not a destination
+
+`/library/<seasonId>` resolves the season's `seriesId` and redirects to
+`/library/<seriesId>#season-<indexNumber>`; `SeasonSection` renders that anchor
+id. A season with no `seriesId` (deep link into a stale cache) keeps the old
+generic rendering as a fallback so the user is never stranded. Inbound links
+updated: episode breadcrumb, `handleItemClick case "season"`, the TV landing
+page's `case "Season"`, and `DownloadedBrowse`.
+
+### Erasing watch history
+
+```rust
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_clear_watch_history(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    item_id: String,
+) -> Result<(), String>
+```
+
+`OnlineRepository` maps it to `DELETE /Users/{userId}/PlayedItems/{itemId}` —
+Jellyfin's mark-unplayed, which clears the played flag *and* zeroes the resume
+position, and which the server applies recursively to a folder. One call
+therefore handles a whole series or a single season; no per-episode fan-out.
+`OfflineRepository` returns `RepoError::Offline` rather than clearing locally,
+because divergent local history is undone by the next sync.
+
+`ClearHistoryButton` is shared by the series hero (`scope="series"`) and each
+`SeasonSection` header (`scope="season"`). It confirms first — there is no undo —
+disables itself while the server is unreachable, and reloads the page on success
+so the recomputed current episode is what the viewer sees. Clearing a whole
+series therefore returns it to S1E1, which is the same path a never-watched
+series takes through `pick_current_episode`.
+
+### Frontend: one route per video library
+
+`/library/tv` and `/library/movies` each gain `?view=browse|all|genres` tabs,
+rendering the existing `GenericMediaListPage` / `GenericGenreBrowser` components
+inline. `?view=` is omitted for `browse` (the default) to keep URLs clean —
+the same convention `searchRouteUrl` uses for the `all` scope.
+
+The four legacy routes become redirect-only `+page.ts` loads:
+
+| Legacy | Redirects to |
+|--------|--------------|
+| `/library/tv/shows` | `/library/tv?view=all` |
+| `/library/shows/genres` | `/library/tv?view=genres` |
+| `/library/movies/all` | `/library/movies?view=all` |
+| `/library/movies/genres` | `/library/movies?view=genres` |
+
+They are kept (rather than deleted) because `GenreTags` builds links to them and
+users may have them in history. `resolveSearchScope` keeps its `/library/shows`
+branch for the same reason.
+
+The "Browse" tile grid at the bottom of both landing pages is removed — the tabs
+replace it, and the tiles were a second navigation affordance to the same two
+destinations the carousels' "Show all" links already reach.
+
+## Out of scope
+
+- **Cross-season autoplay.** `player/mod.rs:fetch_next_episode_for_item` is
+  still season-bounded, so autoplay stops at a season boundary. Fixing it should
+  reuse `repository_get_series_episodes`, but it touches the playback state
+  machine and the Android JNI advance path (see the `AutoplayDecision` deadlock
+  note in CLAUDE.md) and belongs in its own change.
+- **Music library routes.** `/library/music/*` has five sub-routes with the same
+  shape; the same consolidation applies but is not done here.
+- **Marking a series' progress** (mark-watched / mark-unwatched from the series
+  page).

docs/specs/streaming-bitrate-cap.md

@@ -0,0 +1,146 @@
+# Spec: streaming bitrate cap
+
+**Status:** Implemented
+**Requirements:** UR-074 → DR-162 (partially serves UR-070)
+**UX spec:** n/a — the controls reuse existing patterns (Settings → Video Playback, and the player's track menus).
+
+## Summary
+
+The viewer picks a bandwidth ceiling for video — from `Original` (no client
+limit) down to 720 kbps — and every video the app opens is fetched within it,
+live TV included. The choice is made once in Settings and persists across
+restarts; a single video can be moved to another ceiling from the player, which
+re-opens the stream and resumes where it was without changing the saved default.
+
+## Motivation
+
+Every video URL the app built carried a fixed allowance —
+`MaxStreamingBitrate=20000000`, `VideoBitrate=18000000` — the `PlaybackInfo`
+negotiation asked for 20 Mbps, and the device profile advertised
+`999999999`, which invites the server to direct-play a source of any size. On a
+metered or slow connection there was no lever at all short of not watching.
+
+The related UR-070 asks for something adjacent but different: a list of the
+renditions *the server can produce for this item*. That needs per-item
+`MediaSources` negotiation and is still proposed. What was missing first is
+cruder and more valuable: a device-wide budget that holds regardless of what is
+playing.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| What a quality step *is* — total ceiling, audio share, resolution cap | Rust | Jellyfin encoding vocabulary. It changes if Jellyfin's transcoder or parameter binding changes, not if the UI is redesigned. Exactly the shape of `EqPreset::gains()`. |
+| Splitting the ceiling between video and audio | Rust | A domain rule about what the server is being asked to produce; getting it wrong overshoots the user's cap. |
+| Choosing `MaxHeight` for a bitrate | Rust | An encoding judgement (how many pixels a budget can carry), not a display preference. |
+| Where the cap is applied (URL builders, `PlaybackInfo`, live TV, audio handoff) | Rust | All four are backend concerns, and the frontend must not have to know that a cap has more than one enforcement point. |
+| Whether a mid-playback change needs a stream reload, and performing it | Rust | Same decision the audio-track switch already delegates: the backend knows the playback mode and owns the queue. |
+| Persisting the default | Rust | Application state in `app_settings`, alongside every other durable setting. |
+| Rendering the picker, menu placement, which control is highlighted | Frontend | Pure presentation. |
+
+The frontend holds one string — the serde token for the chosen variant — and
+labels/details it received from Rust. It never encodes a bitrate, a resolution
+or a parameter name.
+
+## Design
+
+`StreamingQuality` (`src-tauri/src/settings.rs`) is the ladder: `Original`,
+`Mbps20`, `Mbps10`, `Mbps8`, `Mbps4`, `Mbps2`, `Mbps1`, `Kbps720`, serialised
+camelCase (`"mbps10"`). Each step answers `max_bitrate()`, `audio_bitrate()`,
+`video_bitrate()` (= total − audio), `max_height()`, `label()`, `detail()`.
+
+The active ceiling is a process-wide `RwLock<StreamingQuality>` in
+`repository/online.rs`, read by every builder. Process-wide rather than a field
+on `OnlineRepository` because it is a preference about *this device's
+connection*: it must survive a repository rebuilt on re-login, and the URL
+builders and the negotiation have to agree on it or the cap leaks. This mirrors
+`offline::INCLUDE_CATALOG_BROWSE`.
+
+Enforcement points — all four are required:
+
+| Point | What the cap sets |
+|-------|-------------------|
+| `get_video_stream_url` (HLS transcode) | `MaxStreamingBitrate`, `VideoBitrate`, `AudioBitrate`, `MaxHeight` |
+| `get_playback_info` | request `MaxStreamingBitrate`, and the device profile's `MaxStreamingBitrate`/`MaxStaticBitrate` |
+| `open_live_stream` | `MaxStreamingBitrate` |
+| `build_audio_only_stream_url_for_video` | `min(cap audio, 384 kbps)` |
+
+The negotiation is the one that matters most. `MaxStaticBitrate` is what makes
+the server refuse to *direct play* a source fatter than the ceiling; without it
+a 30 Mbps remux is served untouched and no URL parameter downstream can reduce
+it.
+
+IPC:
+
+```rust
+player_get_streaming_qualities() -> Vec<(StreamingQuality, String, String)>  // variant, label, detail
+player_set_stream_quality(repository_handle, quality, use_html5,
+                          current_position, media_source_id, audio_stream_index)
+    -> StreamQualityResponse           // #[serde(tag = "strategy")]: native | reloadStream
+```
+
+`VideoSettings` gains `streaming_quality` (`#[serde(default)]`, so settings
+persisted before the field existed load as uncapped).
+`player_set_video_settings` applies it and writes it to `app_settings`;
+`restore_streaming_quality` reads it back in the Tauri `setup` hook via
+`tauri::async_runtime::spawn`, defaulting to uncapped if anything fails.
+
+`StreamQualityResponse` keeps its Rust field names on the wire (`new_url`) —
+tauri-specta only camelCases the `strategy` tag. The facade
+(`playerController.setStreamQuality`) dispatches `reloadSource` for
+`reloadStream` and does nothing for `native`, because the backend has already
+reloaded itself.
+
+Mid-playback the change applies to the current video **and** becomes the process
+ceiling for what follows, but it is not persisted: the in-player menu is a "this
+film, this connection" control and Settings owns the durable default.
+
+## Out of scope
+
+- Per-item rendition lists from the server's `MediaSources` (UR-070's other half).
+- Connection-aware caps (separate WiFi/cellular ceilings). One cap, all connections.
+- Adaptive/automatic selection from measured throughput.
+- Download quality, which already has its own preset vocabulary (UR-071/DR-123).
+
+## Acceptance criteria
+
+- [x] `bun run check` passes.
+- [x] `cargo fmt` clean, `cargo clippy` clean, Rust tests pass.
+- [x] `bun run test` passes.
+- [x] `bun run check:boundary` passes — no bitrate/resolution numbers in `src/`.
+- [x] New code carries `// TRACES:` comments.
+- [x] `bindings.ts` regenerated from Rust.
+- [x] A capped step changes what the URL asks for; the uncapped default is byte-identical to the previous behaviour.
+
+## Testing
+
+Rust (`cargo test`):
+
+- `test_video_stream_url_applies_bitrate_cap` — all four parameters at `Mbps2`.
+- `test_video_stream_url_uncapped_keeps_legacy_allowance` — `Original` is unchanged and adds no `MaxHeight`.
+- `test_audio_only_stream_url_takes_the_lower_of_cap_and_default`.
+- `test_streaming_quality_budget_is_internally_consistent`, `..._ladder_descends`, `..._round_trips_through_json`.
+
+The ceiling is process-wide, so tests that depend on it serialise on a guard
+(`QualityFixture`) that restores `Original` on drop — including the two
+pre-existing stream-URL tests, which would otherwise see another test's cap.
+
+`get_playback_info` and `open_live_stream` need a live server and are not unit
+tested; their behaviour is the enum's `max_bitrate()`, which is.
+
+## TRACES
+
+- `StreamingQuality`, `VideoSettings.streaming_quality` — `UR-074 | DR-162`
+- URL builders / negotiation / live TV — `UR-004, UR-074 | DR-140, DR-162`
+- Audio-only handoff — `UR-040, UR-074 | DR-162`
+- Commands, facade, Settings UI, player menu — `UR-074 | DR-162`
+- Tests — `UT-156`, `UT-157`
+
+## Notes for the implementer
+
+- `videoBitRate` with a capital R is the *download* endpoint's binding quirk
+  (DR-123). The streaming endpoint used here binds `VideoBitrate`/
+  `MaxStreamingBitrate` as spelled above — do not "correct" one to the other.
+- A parallel Claude session may be active in this repo; `git diff` before
+  repairing unexpected changes. DR-160/161 were claimed by such a session while
+  this feature was in flight, which is why it is DR-162.

docs/specs/traceability-gate-repair.md

@@ -0,0 +1,238 @@
+# Spec: Repair the traceability coverage gate
+
+**Status:** Implemented
+**Requirements:** DR-093 → supports the traceability practice described in CLAUDE.md
+**UX spec:** n/a — developer tooling, no user-facing surface.
+**Supersedes / revises:** n/a
+
+## Summary
+
+The CI traceability gate has been passing unconditionally for an unknown length
+of time because it divides traced-requirement counts by **hardcoded denominators
+that no longer match [requirements.md](../requirements.md)**. It currently
+reports **158% overall coverage** (and `JA 24 / 3 = 800%`), so the 50% threshold
+is mathematically unreachable and the job cannot fail. This spec makes the gate
+derive its denominators from `requirements.md` at run time, so it reports the
+real number (**85%** today) and can actually fail again.
+
+## Motivation
+
+`.gitea/workflows/traceability-check.yml` hardcodes `UR/39, IR/24, DR/48, JA/3`
+and `TOTAL_REQS=114`. The real counts are **UR 61, IR 29, DR 89, JA 32 — 211
+total**. Requirements were added over time; the divisors were never updated.
+
+The consequence is not a cosmetic reporting bug. The gate is the *only*
+automated defence for the traceability practice, and it is dead:
+
+```
+CI today:  181 / 114 = 158%  → threshold 50% can never trip
+Reality:   181 / 211 =  85%  → healthy, but unguarded
+```
+
+Coverage could collapse to 30% and CI would still print a green
+"✅ Coverage is acceptable". An audit of the design principles found that every
+principle with a *working* automated check is in good shape, and the ones that
+drifted are exactly the ones whose checks were broken or too narrow — this is
+the clearest instance.
+
+A second, related defect is handled in a sibling spec: `scripts/check-req-coverage.sh`
+is separately broken and orphaned (see
+[req-coverage-script-removal.md](req-coverage-script-removal.md)).
+
+## Layer assignment
+
+This spec touches only CI/build tooling — no application logic crosses the
+Rust/Svelte boundary. The table is filled in for completeness.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Counting requirement IDs defined in `requirements.md` | Build tooling (`scripts/`) | Neither runtime layer; it is repo metadata analysis. Belongs beside `extract-traces.ts`, not in the workflow YAML, so it is runnable and testable locally. |
+| Counting *traced* requirement IDs | Build tooling — existing `extract-traces.ts` | Already implemented and correct; this spec consumes it rather than duplicating it. |
+| Threshold policy (the 50% number) | CI workflow | Deployment policy, not analysis. Keeping it in YAML lets it be tuned without touching the script. |
+
+No frontend or Rust logic is added, so no taxonomy leak is possible.
+
+## Design
+
+### 1. Denominators come from `requirements.md`, not literals
+
+`requirements.md` defines requirements in markdown tables with a stable leading
+cell, e.g.:
+
+```
+| DR-001 | Player state machine (idle, loading, …) | Player | UR-005 | Done |
+| UR-002 | Access media when online or offline | High | Done |
+```
+
+Extend [scripts/extract-traces.ts](../../scripts/extract-traces.ts) to also emit
+the *defined* counts, so one tool owns both sides of the fraction and CI does no
+arithmetic on stale literals. Add a `defined` key to the JSON report:
+
+```jsonc
+{
+  "byType":   { "UR": [...], "IR": [...], "DR": [...], "JA": [...] },  // traced (existing)
+  "defined":  { "UR": 61, "IR": 29, "DR": 89, "JA": 32 },              // NEW
+  "coverage": { "covered": 181, "total": 211, "percent": 85 },         // NEW
+  "requirements": { ... },                                             // existing
+  "totalTraces": 318, "totalFiles": …, "timestamp": "…"                // existing
+}
+```
+
+Parsing rule for a *defined* requirement: a line in `docs/requirements.md`
+matching `^\|\s*(UR|IR|DR|JA)-\d{3}\s*\|` — the ID must be the table's first
+cell. This deliberately does **not** count IDs mentioned in the `Traces To`
+column or in prose, which is why a naive `grep -o` over the whole file
+overcounts.
+
+`defined` counts IDs that exist in the spec; `byType` counts IDs that appear in
+a `TRACES:` comment somewhere in the source. Coverage is
+`|byType ∩ defined| / |defined|`.
+
+> **Intersection, not raw length.** A `TRACES:` comment naming an ID that
+> `requirements.md` does not define (a typo, or a requirement later deleted)
+> must **not** inflate the numerator — that is how a ratio exceeds 100% in the
+> first place. Such IDs are reported separately as `orphaned` so they get fixed
+> rather than silently counted or silently dropped.
+
+```jsonc
+"orphaned": ["DR-097"]   // traced in code but not defined in requirements.md
+```
+
+### 2. The workflow consumes the computed number
+
+Replace the arithmetic in `.gitea/workflows/traceability-check.yml` (lines
+46–76) with reads of the precomputed fields:
+
+```sh
+COVERAGE=$(jq '.coverage.percent' traces-report.json)
+COVERED=$(jq '.coverage.covered' traces-report.json)
+TOTAL_REQS=$(jq '.coverage.total'   traces-report.json)
+
+for T in UR IR DR JA; do
+  TRACED=$(jq --arg t "$T" '.byType[$t] | length' traces-report.json)
+  DEFINED=$(jq --arg t "$T" '.defined[$t]'        traces-report.json)
+  echo "   $T: $TRACED / $DEFINED"
+done
+
+MIN_THRESHOLD=50
+[ "$COVERAGE" -lt "$MIN_THRESHOLD" ] && { echo "❌ …"; exit 1; }
+```
+
+No hardcoded denominator survives anywhere in the workflow.
+
+### 3. A self-check so this cannot silently rot again
+
+The root cause was a number that drifted with nothing watching it. Add a
+guard that fails the job on an arithmetically impossible result:
+
+```sh
+if [ "$COVERAGE" -gt 100 ]; then
+  echo "❌ Coverage > 100% — the gate is miscomputing; orphaned IDs: $(jq -c '.orphaned' traces-report.json)"
+  exit 1
+fi
+```
+
+A >100% reading is now a hard failure rather than a green tick.
+
+### 4. Local parity
+
+Add a script so the gate is runnable outside CI:
+
+```jsonc
+"traces:coverage": "bun run scripts/extract-traces.ts --format coverage"
+```
+
+Prints the same table CI prints and exits non-zero below threshold.
+
+### Threshold
+
+Keep `MIN_THRESHOLD=50` in this spec. Real coverage is 85%, so raising the bar
+is tempting, but doing it in the same change that repairs the gate conflates
+"restore the safety net" with "tighten the policy" — if the build then fails, it
+is ambiguous which change caused it. Ratcheting is deliberately deferred to
+follow-up work once the honest number has been observed on `master` for a few
+builds.
+
+## Out of scope
+
+- Raising `MIN_THRESHOLD` above 50 (see above).
+- Fixing/removing `scripts/check-req-coverage.sh` — [req-coverage-script-removal.md](req-coverage-script-removal.md).
+- Adding TRACES comments to raise the actual coverage number.
+- Changing the `TRACES:` comment format or the extractor's parsing of it.
+- The PR "modified files missing TRACES" step (lines 78–126), which is advisory
+  by design and stays advisory.
+
+## Acceptance criteria
+
+- [ ] `bun run traces:json` emits `defined`, `coverage`, and `orphaned` keys.
+- [ ] `coverage.total` equals the count of requirement IDs defined in
+      `requirements.md` (**211** at time of writing), not a literal.
+- [ ] `coverage.percent` reports **85** (±1 for rounding) on the current tree —
+      i.e. the honest number, not 158.
+- [ ] No hardcoded requirement denominator (`39`, `24`, `48`, `3`, `114`) remains
+      in `.gitea/workflows/traceability-check.yml`. Verify:
+      `grep -nE '/ *(39|24|48|3|114)\b' .gitea/workflows/traceability-check.yml`
+      returns nothing.
+- [ ] Adding a new requirement row to `requirements.md` **lowers** reported
+      coverage until it is traced (proves the denominator is live).
+- [ ] A `TRACES:` comment naming an undefined ID appears in `orphaned` and does
+      **not** raise `coverage.percent`.
+- [ ] The job fails if coverage is forced below 50% (test by temporarily raising
+      `MIN_THRESHOLD` to 99 locally) — proving the gate can fail again.
+- [ ] The job fails if coverage computes >100%.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] No Rust types changed, so no `bindings.ts` regeneration needed.
+
+## Testing
+
+`extract-traces.ts` currently has no test coverage. Add
+`scripts/extract-traces.test.ts` (vitest) over fixture strings rather than the
+live `requirements.md`, so the tests do not change meaning as requirements are
+added:
+
+- **UT:** counts a well-formed table row as a defined requirement.
+- **UT:** does **not** count an ID appearing only in the `Traces To` column or
+  in prose — the specific overcounting bug this parse rule avoids.
+- **UT:** coverage is the intersection — a traced-but-undefined ID lands in
+  `orphaned` and does not inflate the numerator.
+- **UT:** coverage of an empty trace set is 0%, not a divide-by-zero.
+- **UT:** all-traced fixture reports exactly 100%, never above.
+
+CI behaviour is verified by the acceptance criteria above (the forced-failure
+check is the important one — a gate nobody has watched fail is not known to
+work).
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-093** — "Traceability coverage gate derives requirement denominators from
+  `requirements.md` at run time (not hardcoded literals), computes coverage as
+  the intersection of traced and defined IDs, reports IDs traced but undefined
+  as orphaned, and fails on an impossible >100% result." Category: Tooling.
+  Status: Done on merge.
+
+Tag:
+
+```typescript
+// scripts/extract-traces.ts
+// TRACES: | DR-093
+```
+
+Tests carry `@req-test: UT-089 …` onward (next free UT is **UT-089**).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — run `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Do not add tooling to the CI image for this.** `jq` and `bun` are already in
+  `jellytau-builder`; this spec needs nothing else. Installing a system package
+  in a workflow step violates the hard CI rule in CLAUDE.md.
+- Keep `traces:json`'s existing keys intact — `release-notes.ts` and
+  `traces:markdown` consume the same report, and the CI workflow uploads it as
+  an artifact. This is an additive change.
+- The `head -50 docs/traceability.md` and artifact-upload steps are unaffected.
+- Expect the first green build after this change to print a *lower* number than
+  before (85% vs 158%). That is the fix working, not a regression.

docs/specs/video-background-audio.md

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

docs/specs/windows-native-audio-backend.md

@@ -0,0 +1,209 @@
+# Spec: Windows native audio backend
+
+**Status:** Proposed
+**Requirements:** UR-003, UR-027, UR-032, UR-033 → DR-030, DR-035, DR-036; new IR-030
+**UX spec:** n/a — Settings › Audio already renders the controls
+**Supersedes / revises:** acts on the "audio can unify, video cannot" conclusion in [playback-backend-unification.md](playback-backend-unification.md)
+
+## Summary
+
+Give Windows a real native audio backend instead of the current webview
+`<audio>` shim. Windows is the only platform where audio playback has no decoder
+of its own: `WebviewAudioBackend` hands a URL to a frontend `<audio>` element and
+relays transport commands. It cannot set volume, cannot apply any audio setting,
+and reports state only via DOM events.
+
+Audio needs no rendering surface, so **none of the webview-compositing problems
+that block unified video apply here.** This is the cleanest available win.
+
+## Motivation
+
+`WebviewAudioBackend` was a deliberate stopgap ("audio-only playback for
+platforms without a native audio backend"), and it works — but it has a hard
+functional gap. From `webview_audio_backend.rs`:
+
+```rust
+fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError> {
+    // ...stores locally only; there is no ControlCommand action for volume
+}
+```
+
+So volume changes never reach the element; the frontend has to observe the player
+store and apply volume itself. `set_audio_settings` likewise stores values that
+nothing consumes — EQ, normalization, and gapless are all inert on Windows.
+
+Meanwhile the backend-unification investigation established that a native *audio*
+engine is unproblematic on Windows specifically: `tauri-plugin-libmpv` lists
+Windows as its **fully tested** platform (in contrast to Linux, where embedding
+is broken — but that is a *video surface* problem, which audio does not have).
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Decoding and playing the audio stream | Rust | Playback is domain logic; every other platform already decodes in Rust or a native player. The webview shim is the anomaly. |
+| Applying `AudioSettings` (EQ/normalize/gapless) | Rust | Same `AudioSettings` contract as MPV/ExoPlayer; band layout and presets stay canonical in `settings.rs`. |
+| Position/state reporting | Rust | Restores the project's core principle — the player is the authoritative source of state. Today Windows inverts this: the DOM element is authoritative and Rust mirrors it. |
+| Volume | Rust | Currently broken precisely because it is split across the boundary. |
+| Rendering the player UI | Frontend | Unchanged. |
+
+The strongest argument for this change is the third row. CLAUDE.md states
+playback state is one-directional with the player authoritative; on Windows that
+is currently false, and the `player_report_*` round-trip exists to paper over it.
+
+## Design
+
+### Engine choice
+
+Two viable options; **libmpv is recommended** for consistency with the Linux
+audio backend.
+
+| | libmpv | GStreamer |
+|---|---|---|
+| Windows status | ✅ `tauri-plugin-libmpv` reports fully tested | ✅ works, but… |
+| Rust bindings | `libmpv2` 6.0.0, active | `gstreamer-rs` 0.25.x, excellent |
+| Cross-MSVC from Linux | ⚠️ needs prebuilt DLL + import lib | ❌ `gstreamer-sys` uses pkg-config, fights `cargo-xwin` |
+| Code reuse | ✅ `MpvBackend` logic is directly reusable | ❌ a second engine to learn |
+| Crossfade capable | ❌ single-stream chain | ✅ `audiomixer` |
+
+libmpv wins on reuse: `MpvBackend`'s `set_audio_settings` — the `af` lavfi graph
+built by `build_af_filter`, `eq_filter_entries`, `normalize_filter_entry` — is
+platform-independent and would apply unchanged.
+
+The one reason to prefer GStreamer is crossfade (UR-031), which mpv structurally
+cannot do. If crossfade becomes a priority, revisit; it would then argue for
+GStreamer on *both* Linux and Windows, which is a much larger change.
+
+### Structure
+
+Rename the cfg gate so `MpvBackend` is no longer Linux-only:
+
+```rust
+// src-tauri/src/player/mod.rs
+#[cfg(any(target_os = "linux", target_os = "windows"))]
+pub mod mpv_backend;
+```
+
+`MpvBackend::new` needs one platform-specific branch: `detect_audio_system()`
+currently probes `pactl`/`pw-cli`/`/proc/asound/cards` to pick an `ao`. On
+Windows the equivalent is `wasapi` (mpv's default), so the detection is a
+`#[cfg]` returning `"wasapi"` — no probing needed.
+
+Everything else — the event loop, the 250ms position thread, the seek-suppression
+window, the `af` filter graph — is unchanged.
+
+`WebviewAudioBackend` stays for other targets (macOS and anything else hitting
+the `not(any(...))` arm) and as the fallback if libmpv fails to initialize. The
+existing `emit_backend_init_failed` path already handles that gracefully.
+
+### Build
+
+`libmpv2-sys` is well-suited to cross-compilation: no pkg-config, vendored
+headers, pregenerated bindings (no libclang). It emits `cargo:rustc-link-lib=mpv`
+unconditionally, so the build must supply a linkable import library for
+`x86_64-pc-windows-msvc`.
+
+Keep the `build_libmpv` feature **off** — its Unix path shells out to mpv-build
+and explicitly rejects cross-compilation.
+
+🔴 Per CLAUDE.md, the prebuilt libmpv **must be added to the builder image**
+(`Dockerfile.builder` → rebuild + push via `scripts/build-builder-image.sh`), not
+installed at CI job time. `libmpv-2.dll` must also be bundled into the NSIS
+installer via `tauri.conf.json`'s resources.
+
+### Verified build mechanics
+
+The cross-compile path was tested hands-on from Linux (July 2026), not inferred:
+
+- Neither shinchiro nor zhongfly ships an `mpv.def` or MSVC `mpv.lib` — only a
+  MinGW `libmpv.dll.a`. (Several online sources claim otherwise; they are wrong.)
+- An MSVC-style import lib can be generated locally with LLVM tools only:
+  `llvm-readobj --coff-exports libmpv-2.dll` → synthesize `mpv.def` →
+  `llvm-dlltool -m i386:x86-64 -d mpv.def -l mpv.lib`. `llvm-lib /def:` produces a
+  byte-identical result.
+- A real `lld-link` link against that import lib **succeeds**, and the resulting
+  import table resolves `mpv_client_api_version` from `libmpv-2.dll`. `lld-link`
+  is the linker `cargo-xwin` uses, so this is the load-bearing step.
+- Linking directly against the shipped MinGW `libmpv.dll.a` **also** succeeds, so
+  def-generation may be skippable — but that relies on lld's GNU-archive
+  tolerance rather than a documented contract. Keep `llvm-dlltool` as the
+  fallback.
+- MinGW origin is not an ABI problem: libmpv exports a pure C ABI, and the x86-64
+  Windows calling convention is platform-defined. The upstream note that MSVC
+  cannot *build* mpv is frequently misread as "MSVC cannot *link* libmpv" — that
+  is not what it says.
+- 🔴 Never free/realloc across the DLL boundary — use `mpv_free`.
+
+Build wiring is ordinary: `cargo:rustc-link-lib=dylib=mpv` plus
+`cargo:rustc-link-search`. Nothing about libmpv conflicts with `cargo-xwin`.
+
+### Size and shipping
+
+Measured uncompressed: **93 MiB** (zhongfly `mpv-dev-lgpl-x86_64`) vs **112 MiB**
+(shinchiro, full GPL build); ~26–30 MB compressed in the `.7z`.
+
+**Ship the zhongfly LGPL build** — smaller, and there is no reason to pull the
+GPL variant in for an audio-only use.
+
+Import-table inspection confirms **no companion DLLs are needed**: every
+dependency is a system DLL (`KERNEL32`, `USER32`, `d2d1`, `DWrite`, `OPENGL32`,
+`vulkan-1`, UCRT `api-ms-win-*`). One file to bundle.
+
+93 MiB is still substantial against a Tauri app's usual few MB. Since we use mpv
+audio-only, investigate whether a pruned build (no video decoders, no libplacebo)
+is worth producing for the builder image — but treat that as an optimization,
+not a blocker.
+
+## Out of scope
+
+- Windows *video*. Stays in WebView2 + hls.js — it works and has ABR.
+- Crossfade (UR-031/DR-034) — not implemented anywhere; needs its own spec.
+- Replacing `WebviewAudioBackend` for macOS.
+- MPRIS/SMTC media-key integration — worth a follow-up, not this spec.
+
+## Acceptance criteria
+
+- [ ] Windows build produces a `MpvBackend`-backed player; `backend-init-failed` is emitted (not a crash) if libmpv is unavailable.
+- [ ] Volume control works from the UI — the current hard gap.
+- [ ] EQ, normalization, and gapless audibly take effect on Windows.
+- [ ] Position/state originate in Rust; the `<audio>` element is no longer in the audio path.
+- [ ] Seek, next/previous, and queue advance work; sleep timer stops playback.
+- [ ] `libmpv-2.dll` ships in the NSIS installer and the app runs on a clean Windows VM with no mpv installed.
+- [ ] Builder image carries the Windows libmpv artefacts; **no toolchain install added to any CI step**.
+- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+
+## Testing
+
+**Rust**: the existing `mpv_backend_test.rs` and the `build_af_filter` /
+`normalize_filter_entry` / `eq_filter_entries` unit tests already cover the
+filter-graph logic and are platform-independent — they should pass unchanged
+under a Windows `cargo check`/test. Add a test asserting `detect_audio_system()`
+returns `wasapi` under `cfg(windows)`.
+
+**Manual, on Windows**: volume, EQ preset change, normalization toggle, gapless
+between two tracks, seek, queue advance, sleep timer. Then the packaging test —
+install the NSIS output on a clean VM and confirm it launches and plays.
+
+Per CLAUDE.md, the volume gap is a *bug fix*: write a failing test for
+"`set_volume` reaches the backend" before implementing.
+
+## TRACES
+
+- Windows `MpvBackend` construction in `create_player_backend` → `// TRACES: UR-003 | IR-030`
+- `detect_audio_system` Windows branch → `IR-030`
+- Existing `set_audio_settings` gains Windows coverage → `UR-027, UR-032, UR-033 | DR-030, DR-035, DR-036`
+- Allocate **IR-030** in `requirements.md` ("libmpv integration for Windows audio playback").
+
+## Notes for the implementer
+
+- Do this **after** [libmpv2-migration.md](libmpv2-migration.md) — porting the
+  current dead `libmpv` git pin to a second platform would double the migration
+  work.
+- `libmpv2` has broken its API in every major release (4.0 removed command
+  helpers, 5.0 removed `mpv_node`, 6.0 changed `RenderContext` ownership). Pin an
+  exact version.
+- Only the `render`-feature parts of `libmpv2` concern video; audio-only use does
+  not need it, and disabling the default `render` feature may shrink the build.
+- A parallel Claude session may be active — `git diff` first.

docs/traceability-ci.md

@@ -0,0 +1,302 @@
+# Requirement Traceability CI/CD Pipeline
+
+This document explains the automated requirement traceability validation system for JellyTau.
+
+## Overview
+
+The CI/CD pipeline automatically validates that code changes are properly traced to requirements. This ensures:
+- ✅ Requirements are implemented with clear traceability
+- ✅ No requirement coverage regressions
+- ✅ Code changes are linked to specific requirements
+- ✅ Quality metrics are tracked over time
+
+## Gitea Actions Workflows
+
+Traceability validation lives in `.gitea/workflows/traceability-check.yml`:
+
+- ✅ Automatic trace extraction
+- ✅ Coverage validation against minimum threshold (50%)
+- ✅ Modified file checking
+- ✅ Artifact preservation
+- ✅ Summary reports
+
+**Runs on:** Every push and pull request to `master`/`main`/`develop`
+
+A second workflow, `traceability.yml`, previously duplicated this one as a
+"GitHub-compatible alternative". It was removed: CI here is Gitea Actions, and
+its only unique step (PR comments via `actions/github-script`) depended on the
+GitHub REST client, which Gitea does not provide. To add PR comments, post to
+Gitea's `/api/v1/repos/{owner}/{repo}/issues/{index}/comments` from
+`traceability-check.yml` rather than reviving the old file.
+
+## What Gets Validated
+
+### 1. Trace Extraction
+```bash
+bun run traces:json > traces-report.json
+```
+Extracts all TRACES comments from:
+- TypeScript files (`src/**/*.ts`)
+- Svelte components (`src/**/*.svelte`)
+- Rust code (`src-tauri/src/**/*.rs`)
+- Test files
+
+### 2. Coverage Thresholds
+The workflow checks:
+- **Minimum overall coverage:** 50%
+
+Denominators are **derived from `docs/requirements.md` at run time** — they are
+never hardcoded here or in the workflow. Run `bun run traces:coverage` for the
+current per-type breakdown; any number written into this document is a snapshot
+that will drift.
+
+> **Why this matters.** The workflow used to divide by frozen literals
+> (UR/39, IR/24, DR/48, JA/3, total 114) while `requirements.md` had grown past
+> 200. It reported **158%** coverage, so the 50% threshold was unreachable and
+> the job could not fail regardless of how far coverage dropped. See
+> [specs/traceability-gate-repair.md](specs/traceability-gate-repair.md).
+
+Coverage is the *intersection* of traced and defined IDs: an ID that appears in
+a `TRACES:` comment but is not defined in `requirements.md` is reported as
+**orphaned** and does not count toward coverage. UT/IT test identifiers are a
+separate taxonomy and are excluded entirely.
+
+The workflow **fails** and blocks merge if coverage drops below 50% — or if it
+computes above 100%, which can only mean the gate is miscounting.
+
+### 3. Modified File Checking
+On pull requests, the workflow:
+1. Detects all changed TypeScript/Svelte/Rust files
+2. Warns if new/modified files lack TRACES comments
+3. Suggests the TRACES format for missing comments
+
+## How to Add Traces to New Code
+
+When you add new code or modify existing code, include TRACES comments:
+
+### TypeScript/Svelte Example
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+export function handlePlayback() {
+  // Implementation...
+}
+```
+
+### Rust Example
+```rust
+/// TRACES: UR-005 | DR-001
+pub fn player_state_changed(state: PlayerState) {
+    // Implementation...
+}
+```
+
+### Test Example
+```rust
+// TRACES: UR-005 | DR-001 | UT-026, UT-027
+#[cfg(test)]
+mod tests {
+    // Tests...
+}
+```
+
+## TRACES Format
+
+```
+TRACES: [UR-###, ...] | [IR-###, ...] | [DR-###, ...] | [JA-###, ...]
+```
+
+- `UR-###` - User Requirements (features users see)
+- `IR-###` - Integration Requirements (API/platform integration)
+- `DR-###` - Development Requirements (internal architecture)
+- `JA-###` - Jellyfin API Requirements (Jellyfin API usage)
+
+**Examples:**
+- `// TRACES: UR-005` - Single requirement
+- `// TRACES: UR-005, UR-026` - Multiple of same type
+- `// TRACES: UR-005 | DR-029` - Multiple types
+- `// TRACES: UR-005, UR-026 | DR-001, DR-029 | UT-001` - Complex
+
+## Workflow Behavior
+
+### On Push to Main Branch
+1. ✅ Extracts all traces from code
+2. ✅ Validates coverage is >= 50%
+3. ✅ Generates full traceability report
+4. ✅ Saves report as artifact
+
+### On Pull Request
+1. ✅ Extracts all traces
+2. ✅ Validates coverage >= 50%
+3. ✅ Checks modified files for TRACES
+4. ✅ Warns if new code lacks TRACES
+5. ✅ Suggests proper format
+6. ✅ Generates report artifact
+
+### Failure Scenarios
+The workflow **fails** (blocks merge) if:
+- Coverage drops below 50%
+- JSON extraction fails
+- Invalid trace format
+
+The workflow **warns** (but doesn't block) if:
+- New files lack TRACES comments
+- Coverage drops (but still above threshold)
+
+## Viewing Reports
+
+### In Gitea Actions UI
+1. Go to **Actions** tab
+2. Click the **Traceability Validation** workflow run
+3. Download **traceability-reports** artifact
+4. View:
+   - `traces-report.json` - Raw trace data
+   - `docs/traceability.md` - Formatted report
+
+### Locally
+```bash
+# Extract current traces
+bun run traces:json | jq '.byType'
+
+# Generate full report
+bun run traces:markdown
+cat docs/traceability.md
+```
+
+## Coverage Goals
+
+### Current Status
+
+Run `bun run traces:coverage` — it prints the live figure and exits non-zero
+below threshold. Numbers are deliberately not pinned here; the previous snapshot
+in this section (51%, 56/114) was stale by roughly 100 requirements and was what
+made the broken CI arithmetic look plausible for so long.
+
+As of July 2026 overall coverage is ~86% (182/212).
+
+### Targets
+- **Short term** (Sprint): Maintain ≥50% overall
+- **Medium term** (Month): Reach 70% overall coverage
+- **Long term** (Release): Reach 90% coverage with focus on:
+  - IR requirements (API clients)
+  - JA requirements (Jellyfin API endpoints)
+  - Remaining UR/DR requirements
+
+## Improving Coverage
+
+### For Missing User Requirements (UR)
+1. Review [README.md](../README.md) for unimplemented features
+2. Add TRACES to code that implements them
+3. Focus on high-priority features (High/Medium priority)
+
+### For Missing Integration Requirements (IR)
+1. Add TRACES to Jellyfin API client methods
+2. Add TRACES to platform-specific backends (Android/Linux)
+3. Link to corresponding Jellyfin API endpoints
+
+### For Missing Development Requirements (DR)
+1. Add TRACES to UI components in `src/lib/components/`
+2. Add TRACES to composables in `src/lib/composables/`
+3. Add TRACES to player backend in `src-tauri/src/player/`
+
+### For Jellyfin API Requirements (JA)
+1. Add TRACES to Jellyfin API wrapper methods
+2. Document which endpoints map to which requirements
+3. Link to Jellyfin API documentation
+
+## Example PR Checklist
+
+When submitting a pull request:
+
+- [ ] All new code has TRACES comments linking to requirements
+- [ ] TRACES format is correct: `// TRACES: UR-001 | DR-002`
+- [ ] Workflow passes (coverage ≥ 50%)
+- [ ] No coverage regressions
+- [ ] Artifact traceability report was generated
+
+## Troubleshooting
+
+### "Coverage below minimum threshold"
+**Problem:** Workflow fails with coverage < 50%
+
+**Solution:**
+1. Run `bun run traces:json` locally
+2. Check which requirements are traced
+3. Add TRACES to untraced code sections
+4. Re-run extraction to verify
+
+### "New files without TRACES"
+**Problem:** Workflow warns about new files lacking TRACES
+
+**Solution:**
+1. Add TRACES comments to all new code
+2. Format: `// TRACES: UR-001 | DR-002`
+3. Map code to specific requirements from README.md
+4. Re-push
+
+### "Invalid JSON format"
+**Problem:** Trace extraction produces invalid JSON
+
+**Solution:**
+1. Check for malformed TRACES comments
+2. Run locally: `bun run traces:json`
+3. Look for parsing errors
+4. Fix and retry
+
+## Integration with Development
+
+### Before Committing
+```bash
+# Check your traces
+bun run traces:json | jq '.byType'
+
+# Regenerate report
+bun run traces:markdown
+
+# Verify traces syntax
+grep "TRACES:" src/**/*.ts src/**/*.rs
+```
+
+### In Your IDE
+Add a file watcher to regenerate traces on save:
+```json
+{
+  "fileWatcher.watchPatterns": [
+    "src/**/*.ts",
+    "src/**/*.svelte",
+    "src-tauri/src/**/*.rs"
+  ],
+  "fileWatcher.command": "bun run traces:markdown"
+}
+```
+
+### Git Hooks
+Add a pre-push hook to validate traces:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+bun run traces:json > /dev/null
+if [ $? -ne 0 ]; then
+  echo "❌ Invalid TRACES format"
+  exit 1
+fi
+```
+
+## References
+
+- [Extract Traces Script](../scripts/README.md#extract-tracests)
+- [Requirements Specification](../README.md#requirements-specification)
+- [Traceability Matrix](./traceability.md)
+- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
+
+## Support
+
+For issues or questions:
+1. Check this document
+2. Review example traces in `src/lib/stores/`
+3. Check existing TRACES comments for format
+4. Review workflow logs in Gitea Actions
+
+---
+
+**Last Updated:** 2026-02-13

docs/traces-quick-ref.md

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

e2e/.env.example

@@ -0,0 +1,24 @@
+# E2E Test Configuration
+# Copy this file to .env and fill in your test credentials
+
+# Jellyfin Server Configuration
+TEST_SERVER_URL=https://demo.jellyfin.org/stable
+TEST_SERVER_NAME=Demo Server
+
+# Test User Credentials
+TEST_USERNAME=demo
+TEST_PASSWORD=
+
+# Optional: Specific test data IDs (for testing playback, etc.)
+# You can find these IDs in your Jellyfin server
+TEST_MUSIC_LIBRARY_ID=
+TEST_MOVIE_LIBRARY_ID=
+TEST_ARTIST_ID=
+TEST_ALBUM_ID=
+TEST_TRACK_ID=
+TEST_MOVIE_ID=
+TEST_EPISODE_ID=
+
+# Test Timeouts (milliseconds)
+TEST_TIMEOUT=60000
+TEST_WAIT_TIMEOUT=15000

e2e/README.md

@@ -0,0 +1,376 @@
+# E2E Testing with WebdriverIO
+
+End-to-end tests for JellyTau using WebdriverIO and tauri-driver. These tests run against a real Tauri app instance with an **isolated test database**.
+
+## Quick Start
+
+```bash
+# 1. Configure test credentials (first time only)
+cp e2e/.env.example e2e/.env
+# Edit e2e/.env with your Jellyfin server details
+
+# 2. Build the frontend
+bun run build
+
+# 3. Run E2E tests
+bun run test:e2e
+```
+
+## Configuration
+
+### Test Credentials
+
+E2E tests use credentials from `e2e/.env` (gitignored). Copy the example file to get started:
+
+```bash
+cp e2e/.env.example e2e/.env
+```
+
+**e2e/.env** (your private file):
+```bash
+# Your Jellyfin test server
+TEST_SERVER_URL=https://your-jellyfin.example.com
+TEST_SERVER_NAME=My Test Server
+
+# Test user credentials
+TEST_USERNAME=testuser
+TEST_PASSWORD=yourpassword
+
+# Optional: Specific test data IDs
+TEST_MUSIC_LIBRARY_ID=abc123
+TEST_ALBUM_ID=xyz789
+# ... etc
+```
+
+**Important:**
+- ✅ `.env` is gitignored - your credentials stay private
+- ✅ Tests fall back to Jellyfin demo server if `.env` doesn't exist
+- ✅ Share `.env.example` with your team so they can set up their own
+
+### Isolated Test Database
+
+**Your production data is safe!** E2E tests use a completely separate database:
+
+- **Production:** `~/.local/share/com.dtourolle.jellytau/` - Your real data ✅
+- **E2E Tests:** `/tmp/jellytau-test-data/` - Isolated test data ✅
+
+This is configured via the `JELLYTAU_DATA_DIR` environment variable in `wdio.conf.ts`.
+
+## Architecture
+
+### Test Structure
+
+```
+e2e/
+├── .env.example           # Template for test credentials
+├── .env                   # Your credentials (gitignored)
+├── specs/                 # Test specifications
+│   ├── app-launch.e2e.ts  # App initialization tests
+│   ├── auth.e2e.ts        # Authentication flow
+│   └── navigation.e2e.ts  # Navigation and routing
+├── pageobjects/           # Page Object Model (POM)
+│   ├── BasePage.ts        # Base class with common methods
+│   ├── LoginPage.ts       # Login page interactions
+│   └── HomePage.ts        # Home page interactions
+└── helpers/               # Test utilities
+    ├── testConfig.ts      # Load .env configuration
+    └── testSetup.ts       # Setup helpers
+```
+
+### Page Object Model
+
+Tests use the Page Object Model pattern for maintainability:
+
+```typescript
+// Good: Using page objects
+import LoginPage from "../pageobjects/LoginPage";
+
+await LoginPage.waitForLoginPage();
+await LoginPage.connectToServer(testConfig.serverUrl);
+await LoginPage.login(testConfig.username, testConfig.password);
+
+// Bad: Direct selectors in tests
+await $("#server-url").setValue("https://...");
+await $("button").click();
+```
+
+## Writing Tests
+
+### Using Test Configuration
+
+Always use `testConfig` for credentials and server details:
+
+```typescript
+import { testConfig } from "../helpers/testConfig";
+
+describe("My Feature", () => {
+  it("should test something", async () => {
+    // Use testConfig instead of hardcoded values
+    await LoginPage.connectToServer(testConfig.serverUrl);
+    await LoginPage.login(testConfig.username, testConfig.password);
+
+    // Access optional test data
+    if (testConfig.albumId) {
+      // Test with specific album
+    }
+  });
+});
+```
+
+### Test Data IDs
+
+For tests that need specific content (albums, tracks, etc.):
+
+1. Find the ID in your Jellyfin server (check the URL when viewing an item)
+2. Add it to your `e2e/.env`:
+   ```bash
+   TEST_ALBUM_ID=abc123def456
+   ```
+3. Use it in tests:
+   ```typescript
+   if (testConfig.albumId) {
+     await browser.url(`/album/${testConfig.albumId}`);
+   }
+   ```
+
+### Example Test
+
+```typescript
+import { expect } from "@wdio/globals";
+import LoginPage from "../pageobjects/LoginPage";
+import { testConfig } from "../helpers/testConfig";
+
+describe("Album Playback", () => {
+  beforeEach(async () => {
+    // Login before each test
+    await LoginPage.waitForLoginPage();
+    await LoginPage.fullLoginFlow(
+      testConfig.serverUrl,
+      testConfig.username,
+      testConfig.password
+    );
+  });
+
+  it("should play an album", async () => {
+    // Skip if no test album configured
+    if (!testConfig.albumId) {
+      console.log("Skipping - no TEST_ALBUM_ID configured");
+      return;
+    }
+
+    // Navigate to album
+    await browser.url(`/album/${testConfig.albumId}`);
+
+    // Click play
+    const playButton = await $('[aria-label="Play"]');
+    await playButton.click();
+
+    // Verify playback started
+    const miniPlayer = await $(".mini-player");
+    expect(await miniPlayer.isDisplayed()).toBe(true);
+  });
+});
+```
+
+## Running Tests
+
+### Commands
+
+```bash
+# Run all E2E tests
+bun run test:e2e
+
+# Run in watch mode (development)
+bun run test:e2e:dev
+
+# Run specific test file
+bun run test:e2e -- e2e/specs/auth.e2e.ts
+```
+
+### Before Running
+
+**Always build the frontend first:**
+
+```bash
+bun run build
+cd src-tauri && cargo build
+```
+
+The debug binary expects built frontend files in the `build/` directory.
+
+## Test Files
+
+### app-launch.e2e.ts
+Basic app initialization tests:
+- App launches successfully
+- UI renders correctly
+- Unauthenticated users redirect to login
+
+**Status:** ✅ Working (no credentials needed)
+
+### auth.e2e.ts
+Full authentication flow:
+- Server connection (2-step process)
+- Login form validation
+- Error handling
+- Complete auth flow
+
+**Status:** ✅ Working with any Jellyfin server
+
+### navigation.e2e.ts
+Routing and navigation:
+- Protected routes
+- Redirects
+- Navigation after login
+
+**Status:** ⚠️ Needs valid credentials (configure `.env`)
+
+## Configuration Reference
+
+### wdio.conf.ts
+
+Main WebdriverIO configuration:
+
+```typescript
+{
+  port: 4444,                    // tauri-driver port
+  maxInstances: 1,               // Run tests sequentially
+  logLevel: "warn",              // Reduce noise
+  framework: "mocha",
+  timeout: 60000,                // 60s test timeout
+
+  capabilities: [{
+    "tauri:options": {
+      application: "path/to/app",
+      env: {
+        JELLYTAU_DATA_DIR: "/tmp/jellytau-test-data"  // Isolated DB
+      }
+    }
+  }]
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TEST_SERVER_URL` | Jellyfin server URL | `https://demo.jellyfin.org/stable` |
+| `TEST_SERVER_NAME` | Server display name | `Demo Server` |
+| `TEST_USERNAME` | Test user username | `demo` |
+| `TEST_PASSWORD` | Test user password | `` (empty) |
+| `TEST_MUSIC_LIBRARY_ID` | Music library ID | undefined |
+| `TEST_ALBUM_ID` | Album ID for playback tests | undefined |
+| `TEST_TRACK_ID` | Track ID for tests | undefined |
+| `TEST_TIMEOUT` | Mocha test timeout (ms) | `60000` |
+| `TEST_WAIT_TIMEOUT` | Element wait timeout (ms) | `15000` |
+
+## Debugging
+
+### View Application During Tests
+
+Tests run with a visible window. To pause and inspect:
+
+```typescript
+it("debug test", async () => {
+  await LoginPage.waitForLoginPage();
+
+  // Pause for 10 seconds to inspect
+  await browser.pause(10000);
+
+  await LoginPage.enterServerUrl(testConfig.serverUrl);
+});
+```
+
+### Check Logs
+
+- **WebdriverIO logs:** Console output (set `logLevel: "info"` in config)
+- **tauri-driver logs:** Stdout/stderr from driver process
+- **App logs:** Check app console (if running with dev tools)
+
+### Common Issues
+
+**"Connection refused" in browser body**
+- Frontend not built: Run `bun run build`
+- Solution: Always build before testing
+
+**"Element not found" errors**
+- Selector might be wrong
+- Element not loaded yet - add wait: `await element.waitForDisplayed()`
+
+**"Invalid session id"**
+- Normal when app closes between tests
+- Each test file gets a fresh app instance
+
+**Tests fail with "no .env file"**
+- Copy `e2e/.env.example` to `e2e/.env`
+- Configure your Jellyfin server details
+
+**Database still using production data**
+- Check `wdio.conf.ts` has `JELLYTAU_DATA_DIR` env var
+- Rebuild app: `cd src-tauri && cargo build`
+
+## Platform Support
+
+### Supported
+
+- ✅ **Linux** - Primary development platform
+- ✅ **Windows** - Supported (paths auto-detected)
+- ✅ **macOS** - Supported (paths auto-detected)
+
+### Not Supported
+
+- ❌ **Android** - E2E testing requires Appium + emulators (out of scope)
+- Desktop tests cover 90% of app logic anyway
+
+## Team Collaboration
+
+### Sharing Test Configuration
+
+**DO:**
+- ✅ Commit `e2e/.env.example` with template values
+- ✅ Update README when adding new test data requirements
+- ✅ Use descriptive variable names in `.env.example`
+
+**DON'T:**
+- ❌ Commit `e2e/.env` with real credentials
+- ❌ Hardcode server URLs in test files
+- ❌ Skip authentication in tests (always test full flows)
+
+### Setting Up for a New Team Member
+
+1. **Clone repo**
+2. **Copy env template:** `cp e2e/.env.example e2e/.env`
+3. **Configure credentials:** Edit `e2e/.env` with your Jellyfin server
+4. **Build frontend:** `bun run build`
+5. **Run tests:** `bun run test:e2e`
+
+That's it! No shared credentials needed.
+
+## Best Practices
+
+1. **Use testConfig:** Never hardcode credentials
+2. **Use Page Objects:** Keep selectors out of test specs
+3. **Wait for Elements:** Always use `.waitForDisplayed()`
+4. **Independent Tests:** Each test should work standalone
+5. **Skip Gracefully:** Check for optional test data before using
+6. **Build First:** Always `bun run build` before running tests
+7. **Clear Names:** Use descriptive `describe` and `it` blocks
+
+## Future Enhancements
+
+- [ ] Add more page objects (Player, Library, Queue, Settings)
+- [ ] Create test data fixtures
+- [ ] Add visual regression testing
+- [ ] Mock Jellyfin API for faster, more reliable tests
+- [ ] CI/CD integration (GitHub Actions)
+- [ ] Test report generation
+- [ ] Screenshot capture on failure
+- [ ] Video recording of test runs
+
+## Resources
+
+- [WebdriverIO Documentation](https://webdriver.io/)
+- [Tauri Testing Guide](https://v2.tauri.app/develop/tests/webdriver/)
+- [tauri-driver GitHub](https://github.com/tauri-apps/tauri/tree/dev/tooling/webdriver)
+- [Mocha Documentation](https://mochajs.org/)
+- [Page Object Model Pattern](https://webdriver.io/docs/pageobjects/)

e2e/helpers/testConfig.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Test configuration loaded from .env file
+ */
+export interface TestConfig {
+  serverUrl: string;
+  serverName: string;
+  username: string;
+  password: string;
+  musicLibraryId?: string;
+  movieLibraryId?: string;
+  artistId?: string;
+  albumId?: string;
+  trackId?: string;
+  movieId?: string;
+  episodeId?: string;
+  timeout: number;
+  waitTimeout: number;
+}
+
+/**
+ * Load test configuration from .env file
+ * Falls back to demo server if .env doesn't exist
+ */
+export function loadTestConfig(): TestConfig {
+  const envPath = path.join(__dirname, "..", ".env");
+  const config: TestConfig = {
+    serverUrl: "https://demo.jellyfin.org/stable",
+    serverName: "Demo Server",
+    username: "demo",
+    password: "",
+    timeout: 60000,
+    waitTimeout: 15000,
+  };
+
+  // Try to load .env file
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, "utf-8");
+    const lines = envContent.split("\n");
+
+    for (const line of lines) {
+      // Skip comments and empty lines
+      if (line.trim().startsWith("#") || !line.trim()) continue;
+
+      const [key, ...valueParts] = line.split("=");
+      const value = valueParts.join("=").trim();
+
+      switch (key.trim()) {
+        case "TEST_SERVER_URL":
+          if (value) config.serverUrl = value;
+          break;
+        case "TEST_SERVER_NAME":
+          if (value) config.serverName = value;
+          break;
+        case "TEST_USERNAME":
+          if (value) config.username = value;
+          break;
+        case "TEST_PASSWORD":
+          config.password = value; // Can be empty
+          break;
+        case "TEST_MUSIC_LIBRARY_ID":
+          if (value) config.musicLibraryId = value;
+          break;
+        case "TEST_MOVIE_LIBRARY_ID":
+          if (value) config.movieLibraryId = value;
+          break;
+        case "TEST_ARTIST_ID":
+          if (value) config.artistId = value;
+          break;
+        case "TEST_ALBUM_ID":
+          if (value) config.albumId = value;
+          break;
+        case "TEST_TRACK_ID":
+          if (value) config.trackId = value;
+          break;
+        case "TEST_MOVIE_ID":
+          if (value) config.movieId = value;
+          break;
+        case "TEST_EPISODE_ID":
+          if (value) config.episodeId = value;
+          break;
+        case "TEST_TIMEOUT":
+          if (value) config.timeout = parseInt(value, 10);
+          break;
+        case "TEST_WAIT_TIMEOUT":
+          if (value) config.waitTimeout = parseInt(value, 10);
+          break;
+      }
+    }
+  } else {
+    console.warn(
+      "⚠️  No e2e/.env file found. Using demo server credentials."
+    );
+    console.warn(
+      "   Copy e2e/.env.example to e2e/.env and configure your test server."
+    );
+  }
+
+  return config;
+}
+
+// Export a singleton instance
+export const testConfig = loadTestConfig();

e2e/helpers/testSetup.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * Clears the JellyTau database and cache before tests
+ * This ensures each test run starts with a fresh state
+ */
+export function clearAppData() {
+  const appDataDir = path.join(
+    os.homedir(),
+    ".local/share/com.dtourolle.jellytau"
+  );
+
+  try {
+    if (fs.existsSync(appDataDir)) {
+      // Remove database file
+      const dbPath = path.join(appDataDir, "jellytau.db");
+      if (fs.existsSync(dbPath)) {
+        fs.unlinkSync(dbPath);
+        console.log("Cleared test database");
+      }
+
+      // Clear any cache files if needed
+      // Add more cleanup as needed
+    }
+  } catch (error) {
+    console.warn("Failed to clear app data:", error);
+    // Don't fail tests if cleanup fails
+  }
+}
+
+/**
+ * Wait for element with retries
+ * Useful for elements that might take time to appear
+ */
+export async function waitForElement(
+  selector: string,
+  timeout: number = 15000,
+  retries: number = 3
+): Promise<WebdriverIO.Element> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const element = await $(selector);
+      await element.waitForDisplayed({ timeout });
+      return element;
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      await browser.pause(1000);
+    }
+  }
+  throw new Error(`Element ${selector} not found after ${retries} retries`);
+}

e2e/pageobjects/BasePage.ts

@@ -0,0 +1,31 @@
+export default class BasePage {
+  async waitForElement(selector: string, timeout: number = 10000) {
+    const element = await $(selector);
+    await element.waitForDisplayed({ timeout });
+    return element;
+  }
+
+  async clickElement(selector: string) {
+    const element = await this.waitForElement(selector);
+    await element.click();
+  }
+
+  async enterText(selector: string, text: string) {
+    const element = await this.waitForElement(selector);
+    await element.setValue(text);
+  }
+
+  async getText(selector: string): Promise<string> {
+    const element = await this.waitForElement(selector);
+    return await element.getText();
+  }
+
+  async isElementDisplayed(selector: string): Promise<boolean> {
+    try {
+      const element = await $(selector);
+      return await element.isDisplayed();
+    } catch (error) {
+      return false;
+    }
+  }
+}

e2e/pageobjects/HomePage.ts

@@ -0,0 +1,55 @@
+import BasePage from "./BasePage";
+
+class HomePage extends BasePage {
+  // Selectors
+  get loadingSpinner() {
+    return $(".animate-spin");
+  }
+
+  get browseLibrariesButton() {
+    return $("button*=Browse all libraries");
+  }
+
+  get offlineBanner() {
+    return $(".bg-amber-600\\/90");
+  }
+
+  // Carousel sections
+  get heroSection() {
+    return $("div"); // Hero banner would need specific selector
+  }
+
+  // Actions
+  async waitForHomePageLoad(timeout: number = 15000) {
+    // Wait for loading spinner to disappear
+    try {
+      await this.loadingSpinner.waitForDisplayed({ timeout: 5000 });
+      await this.loadingSpinner.waitForDisplayed({ timeout, reverse: true });
+    } catch {
+      // Spinner might not appear if page loads quickly
+    }
+  }
+
+  async isOffline(): Promise<boolean> {
+    try {
+      return await this.offlineBanner.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+
+  async clickBrowseLibraries() {
+    await this.browseLibrariesButton.click();
+  }
+
+  async hasContent(): Promise<boolean> {
+    // Check if browse button exists (indicates loaded state)
+    try {
+      return await this.browseLibrariesButton.isExisting();
+    } catch {
+      return false;
+    }
+  }
+}
+
+export default new HomePage();

e2e/pageobjects/LoginPage.ts

@@ -0,0 +1,116 @@
+import BasePage from "./BasePage";
+
+class LoginPage extends BasePage {
+  // Selectors
+  get pageTitle() {
+    return $("h1");
+  }
+
+  get serverUrlInput() {
+    return $("#server-url");
+  }
+
+  get connectButton() {
+    return $('button[type="submit"]');
+  }
+
+  get usernameInput() {
+    return $("#username");
+  }
+
+  get passwordInput() {
+    return $("#password");
+  }
+
+  get signInButton() {
+    return $('button[type="submit"]');
+  }
+
+  get errorMessage() {
+    return $(".bg-red-900\\/50");
+  }
+
+  get backButton() {
+    return $("button*=Back");
+  }
+
+  get serverNameDisplay() {
+    return $('p.text-\\[var\\(--color-jellyfin\\)\\]');
+  }
+
+  // Actions
+  async waitForLoginPage(timeout: number = 10000) {
+    await this.serverUrlInput.waitForDisplayed({ timeout });
+  }
+
+  async enterServerUrl(url: string) {
+    await this.serverUrlInput.setValue(url);
+  }
+
+  async clickConnect() {
+    await this.connectButton.click();
+  }
+
+  async connectToServer(url: string) {
+    await this.enterServerUrl(url);
+    await this.clickConnect();
+
+    // Wait for transition to login form
+    await this.usernameInput.waitForDisplayed({ timeout: 10000 });
+  }
+
+  async enterUsername(username: string) {
+    await this.usernameInput.setValue(username);
+  }
+
+  async enterPassword(password: string) {
+    await this.passwordInput.setValue(password);
+  }
+
+  async clickSignIn() {
+    await this.signInButton.click();
+  }
+
+  async login(username: string, password: string) {
+    await this.enterUsername(username);
+    await this.enterPassword(password);
+    await this.clickSignIn();
+  }
+
+  async fullLoginFlow(serverUrl: string, username: string, password: string) {
+    await this.waitForLoginPage();
+    await this.connectToServer(serverUrl);
+    await this.login(username, password);
+  }
+
+  async isOnServerStep(): Promise<boolean> {
+    try {
+      return await this.serverUrlInput.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+
+  async isOnLoginStep(): Promise<boolean> {
+    try {
+      return await this.usernameInput.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+
+  async getErrorMessage(): Promise<string> {
+    await this.errorMessage.waitForDisplayed({ timeout: 5000 });
+    return await this.errorMessage.getText();
+  }
+
+  async hasError(): Promise<boolean> {
+    try {
+      return await this.errorMessage.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+}
+
+export default new LoginPage();

e2e/specs/app-launch.e2e.ts

@@ -0,0 +1,39 @@
+import { expect } from "@wdio/globals";
+
+describe("Application Launch", () => {
+  it("should launch the application", async () => {
+    // Wait for body element to appear
+    const body = await $("body");
+    await body.waitForDisplayed({ timeout: 15000 });
+
+    // Verify app launched successfully
+    expect(await body.isDisplayed()).toBe(true);
+  });
+
+  it("should render the main app container", async () => {
+    // The app has a root div with specific classes
+    const appContainer = await $("div.h-screen.bg-\\[var\\(--color-background\\)\\]");
+
+    // Verify the main container exists
+    expect(await appContainer.isExisting()).toBe(true);
+    expect(await appContainer.isDisplayed()).toBe(true);
+  });
+
+  it("should show JellyTau branding", async () => {
+    // The app should show JellyTau title on login page (default state)
+    const title = await $("h1");
+    await title.waitForDisplayed({ timeout: 10000 });
+
+    const titleText = await title.getText();
+    expect(titleText).toContain("JellyTau");
+  });
+
+  it("should redirect unauthenticated users to login", async () => {
+    // Wait for login page elements to appear
+    const serverUrlInput = await $("#server-url");
+    await serverUrlInput.waitForDisplayed({ timeout: 10000 });
+
+    // Verify we're on the login page
+    expect(await serverUrlInput.isDisplayed()).toBe(true);
+  });
+});

e2e/specs/auth.e2e.ts

@@ -0,0 +1,145 @@
+import { expect } from "@wdio/globals";
+import LoginPage from "../pageobjects/LoginPage";
+import { testConfig } from "../helpers/testConfig";
+
+describe("Authentication Flow", () => {
+  beforeEach(async () => {
+    // Each test starts fresh - app should redirect to login
+    await LoginPage.waitForLoginPage();
+  });
+
+  describe("Server Connection", () => {
+    it("should display the server connection form", async () => {
+      expect(await LoginPage.isOnServerStep()).toBe(true);
+      expect(await LoginPage.pageTitle.getText()).toContain("JellyTau");
+    });
+
+    it("should show server URL input field", async () => {
+      const serverInput = await LoginPage.serverUrlInput;
+
+      expect(await serverInput.isDisplayed()).toBe(true);
+      expect(await serverInput.getAttribute("placeholder")).toContain("jellyfin");
+    });
+
+    it("should have a disabled connect button when URL is empty", async () => {
+      const connectButton = await LoginPage.connectButton;
+
+      // Button should be disabled when input is empty
+      expect(await connectButton.isEnabled()).toBe(false);
+    });
+
+    it("should enable connect button when URL is entered", async () => {
+      await LoginPage.enterServerUrl(testConfig.serverUrl);
+
+      const connectButton = await LoginPage.connectButton;
+      expect(await connectButton.isEnabled()).toBe(true);
+    });
+
+    it("should show error for invalid server URL", async () => {
+      await LoginPage.enterServerUrl("not-a-valid-url");
+      await LoginPage.clickConnect();
+
+      // Wait for error to appear
+      await browser.pause(2000);
+
+      expect(await LoginPage.hasError()).toBe(true);
+    });
+
+    it("should transition to login form on successful connection", async () => {
+      // Using configured test server
+      await LoginPage.connectToServer(testConfig.serverUrl);
+
+      // Should now be on login step
+      expect(await LoginPage.isOnLoginStep()).toBe(true);
+      expect(await LoginPage.isOnServerStep()).toBe(false);
+    });
+  });
+
+  describe("User Login", () => {
+    beforeEach(async () => {
+      // Connect to configured test server before each login test
+      await LoginPage.connectToServer(testConfig.serverUrl);
+    });
+
+    it("should display login form after server connection", async () => {
+      expect(await LoginPage.usernameInput.isDisplayed()).toBe(true);
+      expect(await LoginPage.passwordInput.isDisplayed()).toBe(true);
+      expect(await LoginPage.signInButton.isDisplayed()).toBe(true);
+    });
+
+    it("should show server information", async () => {
+      // Server name and URL should be displayed
+      const serverName = await LoginPage.serverNameDisplay;
+      expect(await serverName.isDisplayed()).toBe(true);
+    });
+
+    it("should have back button to return to server selection", async () => {
+      expect(await LoginPage.backButton.isDisplayed()).toBe(true);
+
+      await LoginPage.backButton.click();
+      await browser.pause(500);
+
+      // Should be back on server step
+      expect(await LoginPage.isOnServerStep()).toBe(true);
+    });
+
+    it("should disable sign in button when username is empty", async () => {
+      const signInButton = await LoginPage.signInButton;
+      expect(await signInButton.isEnabled()).toBe(false);
+    });
+
+    it("should enable sign in button when username is entered", async () => {
+      await LoginPage.enterUsername("demo");
+
+      const signInButton = await LoginPage.signInButton;
+      expect(await signInButton.isEnabled()).toBe(true);
+    });
+
+    it("should show error for invalid credentials", async () => {
+      await LoginPage.login("invalid-user", "wrong-password");
+
+      // Wait for error
+      await browser.pause(2000);
+
+      expect(await LoginPage.hasError()).toBe(true);
+    });
+
+    // Enable this test by configuring e2e/.env with valid credentials
+    it.skip("should successfully login with valid credentials", async () => {
+      await LoginPage.login(testConfig.username, testConfig.password);
+
+      // Wait for redirect to home page
+      await browser.pause(3000);
+
+      // Should redirect away from login page
+      const currentUrl = await browser.getUrl();
+      expect(currentUrl).not.toContain("/login");
+    });
+  });
+
+  describe("Full Authentication Flow", () => {
+    it("should complete full auth flow with test server", async () => {
+      // Test the complete flow
+      await LoginPage.waitForLoginPage();
+
+      // Step 1: Enter server URL
+      expect(await LoginPage.isOnServerStep()).toBe(true);
+      await LoginPage.enterServerUrl(testConfig.serverUrl);
+      await LoginPage.clickConnect();
+
+      // Wait for transition
+      await browser.pause(2000);
+
+      // Step 2: Should be on login form
+      expect(await LoginPage.isOnLoginStep()).toBe(true);
+
+      // Step 3: Enter credentials
+      await LoginPage.enterUsername(testConfig.username);
+      await LoginPage.enterPassword(testConfig.password);
+
+      // Verify form is filled
+      const username = await LoginPage.usernameInput.getValue();
+      expect(username).toBe(testConfig.username);
+    });
+  });
+});

e2e/specs/navigation.e2e.ts

@@ -0,0 +1,39 @@
+import { expect } from "@wdio/globals";
+import LoginPage from "../pageobjects/LoginPage";
+import HomePage from "../pageobjects/HomePage";
+import { testConfig } from "../helpers/testConfig";
+
+describe("Navigation", () => {
+  it("should redirect unauthenticated users to login", async () => {
+    // App should automatically redirect to login when not authenticated
+    await LoginPage.waitForLoginPage();
+
+    expect(await LoginPage.isOnServerStep()).toBe(true);
+  });
+
+  it("should prevent direct access to protected routes", async () => {
+    // Try to navigate to a protected route
+    await browser.url("http://localhost:4444/session/fake-session-id/url");
+    await browser.pause(1000);
+
+    // Should redirect back to login
+    await LoginPage.waitForLoginPage(5000);
+    expect(await LoginPage.isOnServerStep()).toBe(true);
+  });
+
+  // This test requires valid authentication - configure e2e/.env to enable
+  it.skip("should allow navigation after login", async () => {
+    // Login first
+    await LoginPage.fullLoginFlow(
+      testConfig.serverUrl,
+      testConfig.username,
+      testConfig.password
+    );
+
+    // Wait for home page
+    await HomePage.waitForHomePageLoad();
+
+    // Should be able to navigate
+    expect(await HomePage.hasContent()).toBe(true);
+  });
+});

latest.json

@@ -1,15 +0,0 @@
-{
-  "version": "0.11.2",
-  "notes": "\n### 🐛 Fixes\n\n- **Subtitles appear on screen on Android.** Turning one on did nothing, even\n  once they were loading again: the player hands finished subtitles to a view\n  that draws them, and on the native Android path there was no such view — so\n  every cue was decoded, delivered and dropped. There is one now, sitting over\n  the picture and under the controls, following the video's shape when the\n  screen turns. This was hidden behind the loading failure fixed in v0.11.1;\n  with nothing to select, there had never been a cue to lose. (UR-020, UR-003 →\n  DR-260)",
-  "pub_date": "2026-08-23T21:48:32Z",
-  "platforms": {
-    "linux-x86_64": {
-      "signature": "dW50cnVzdGVkIGNvbW1lbnQ6IHNpZ25hdHVyZSBmcm9tIHRhdXJpIHNlY3JldCBrZXkKUlVSczV4N1FMRVFQaXNHUmIxbjlnTzB3dXAzbmU5OG4wUXBRVmZ0Y1lPN3F5OU5DV3o1N1R2eVdFWG1BNDBaR2ZwSXptOHJtQytiTVpVTTRkbkxKR1h1QXQrQk9kdG5LS1FnPQp0cnVzdGVkIGNvbW1lbnQ6IHRpbWVzdGFtcDoxNzg3NTE4ODAwCWZpbGU6SmVsbHlUYXVfMC4xMS4yX2FtZDY0LkFwcEltYWdlCmk0UVdnbU5RZzFNdkZua1dwdFIyMUo1RTZVR200ak1RUXFZaVlrTmVlaFlTYWJvTFRMK1hHRStmSkJobHVKK0NVTW5sOGVrSWp5NVh5TjVrM096cURBPT0K",
-      "url": "https://gitea.tourolle.paris/dtourolle/jellytau/releases/download/v0.11.2/JellyTau_0.11.2_amd64.AppImage"
-    },
-    "windows-x86_64": {
-      "signature": "dW50cnVzdGVkIGNvbW1lbnQ6IHNpZ25hdHVyZSBmcm9tIHRhdXJpIHNlY3JldCBrZXkKUlVSczV4N1FMRVFQaXZibUxGcDlxNlVscTBRNVdBMlhzRDBWalI0TGhLRDJqdWhTOE5iNW5wb1dQUjdiblZVRUd4MzZJeHRVK1gwa2s0WDhwL2FYem9OY3cyZkJ6SUZVbGdzPQp0cnVzdGVkIGNvbW1lbnQ6IHRpbWVzdGFtcDoxNzg3NTE5NzkzCWZpbGU6SmVsbHlUYXVfMC4xMS4yX3g2NC1zZXR1cC5leGUKbUdQajVUeVlmNDRtM3lTUFVMYVJ5YTFBUkdXUkxNcUJhaTRBRkdSVk1NR2tCd20rYUt1OW9hcGZDbkE2R1BvRHg1SjdyRGtKZzhwK1M3ZTFaRnY0QVE9PQo=",
-      "url": "https://gitea.tourolle.paris/dtourolle/jellytau/releases/download/v0.11.2/JellyTau_0.11.2_x64-setup.exe"
-    }
-  }
-}

package.json

@@ -0,0 +1,75 @@
+{
+  "name": "jellytau",
+  "version": "0.6.0",
+  "description": "",
+  "type": "module",
+  "packageManager": "bun@1.3.5",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:e2e": "wdio run ./wdio.conf.ts",
+    "test:e2e:dev": "wdio run ./wdio.conf.ts --watch",
+    "test:all": "./scripts/test-all.sh",
+    "test:rust": "./scripts/test-rust.sh",
+    "check:boundary": "bash scripts/check-frontend-boundary.sh",
+    "android:build": "./scripts/build-android.sh",
+    "android:build:release": "./scripts/build-android.sh release",
+    "android:build:device": "./scripts/build-android.sh --device",
+    "android:build:release:device": "./scripts/build-android.sh release --device",
+    "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",
+    "android:logs": "./scripts/logcat.sh",
+    "desktop:build:linux": "./scripts/build-desktop-linux.sh",
+    "desktop:build:arch": "./scripts/build-arch.sh",
+    "desktop:build:windows": "./scripts/build-windows-cross.sh",
+    "docker:build:linux": "docker compose run --rm desktop-linux-build",
+    "docker:build:arch": "docker compose run --rm arch-build",
+    "docker:build:windows": "docker compose run --rm windows-cross",
+    "clean": "./scripts/clean.sh",
+    "tauri": "tauri",
+    "traces": "bun run scripts/extract-traces.ts",
+    "traces:json": "bun run scripts/extract-traces.ts --format json",
+    "traces:markdown": "bun run scripts/extract-traces.ts --format markdown > docs/traceability.md",
+    "traces:coverage": "bun run scripts/extract-traces.ts --format coverage",
+    "release:notes": "bun run scripts/release-notes.ts"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@tauri-apps/api": "^2",
+    "@tauri-apps/plugin-opener": "^2",
+    "@tauri-apps/plugin-os": "^2.3.2",
+    "hls.js": "^1.6.15",
+    "svelte-dnd-action": "^0.9.69"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.6",
+    "@sveltejs/kit": "^2.9.0",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tauri-apps/cli": "^2",
+    "@testing-library/svelte": "^5.3.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.16",
+    "@wdio/cli": "^9.5.0",
+    "@wdio/local-runner": "^9.5.0",
+    "@wdio/mocha-framework": "^9.5.0",
+    "@wdio/spec-reporter": "^9.5.0",
+    "happy-dom": "^20.0.11",
+    "jsdom": "^27.4.0",
+    "svelte": "^5.47.1",
+    "svelte-check": "^4.0.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "~5.6.2",
+    "vite": "^6.0.3",
+    "vitest": ">=1.0.0 <5.0.0",
+    "webdriverio": "^9.5.0"
+  }
+}

packaging/arch/PKGBUILD

@@ -0,0 +1,52 @@
+# Maintainer: Duncan Tourolle <duncan@tourolle.paris>
+#
+# JellyTau — a cross-platform Jellyfin client (Tauri + SvelteKit).
+#
+# This PKGBUILD builds from the local source tree by default (see the `dev`
+# convenience below), which is what scripts/build-arch.sh uses inside the Arch
+# Docker stage. For AUR distribution, replace the `source=()` line with a release
+# tarball/VCS URL and drop the local-copy prepare() step.
+
+pkgname=jellytau
+pkgver=0.0.18
+pkgrel=1
+pkgdesc="A cross-platform Jellyfin client"
+arch=('x86_64')
+url="https://gitea.tourolle.paris/dtourolle/jellytau"
+license=('MIT')
+# Runtime: libmpv for audio, webkit2gtk for the webview + HTML5 transcoded video.
+depends=('webkit2gtk-4.1' 'mpv' 'gtk3' 'libayatana-appindicator')
+makedepends=('rust' 'cargo' 'bun' 'nodejs' 'pkgconf' 'libsoup3')
+options=('!strip' '!lto')
+
+# Populated from the working tree by scripts/build-arch.sh (SRC env var).
+_srcdir="${JELLYTAU_SRC:-$startdir/../..}"
+
+build() {
+  cd "$_srcdir"
+  export CARGO_HOME="${CARGO_HOME:-$srcdir/cargo-home}"
+  bun install --frozen-lockfile || bun install
+  bun run build
+  # Only the raw binary is needed; packaging is done in package() below so we
+  # control the Arch filesystem layout ourselves rather than via tauri-bundler.
+  (cd src-tauri && cargo build --release --locked)
+}
+
+package() {
+  cd "$_srcdir"
+
+  install -Dm755 "src-tauri/target/release/jellytau" \
+    "$pkgdir/usr/bin/jellytau"
+
+  # Desktop entry
+  install -Dm644 "packaging/arch/jellytau.desktop" \
+    "$pkgdir/usr/share/applications/jellytau.desktop"
+
+  # Icons (hicolor)
+  install -Dm644 "src-tauri/icons/32x32.png" \
+    "$pkgdir/usr/share/icons/hicolor/32x32/apps/jellytau.png"
+  install -Dm644 "src-tauri/icons/128x128.png" \
+    "$pkgdir/usr/share/icons/hicolor/128x128/apps/jellytau.png"
+  install -Dm644 "src-tauri/icons/128x128@2x.png" \
+    "$pkgdir/usr/share/icons/hicolor/256x256/apps/jellytau.png"
+}

packaging/arch/jellytau.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=JellyTau
+Comment=A cross-platform Jellyfin client
+Exec=jellytau
+Icon=jellytau
+Terminal=false
+Categories=AudioVideo;Player;Audio;Video;
+StartupWMClass=jellytau

scripts/README.md

@@ -0,0 +1,134 @@
+# Development Scripts
+
+Collection of utility scripts for building, testing, and deploying JellyTau.
+
+## Testing Scripts
+
+### `test-all.sh`
+Run all tests (frontend + Rust backend).
+```bash
+./scripts/test-all.sh
+```
+
+### `test-frontend.sh`
+Run frontend tests only.
+```bash
+./scripts/test-frontend.sh          # Run all tests
+./scripts/test-frontend.sh --watch  # Watch mode
+./scripts/test-frontend.sh --ui     # Open UI
+```
+
+### `test-rust.sh`
+Run Rust tests only.
+```bash
+./scripts/test-rust.sh              # Run all tests
+./scripts/test-rust.sh -- --nocapture  # Show println! output
+```
+
+## Android Scripts
+
+### `build-android.sh`
+Build the Android APK.
+```bash
+./scripts/build-android.sh          # Debug build
+./scripts/build-android.sh release  # Release build
+```
+
+### `deploy-android.sh`
+Install APK on connected Android device.
+```bash
+./scripts/deploy-android.sh         # Deploy debug APK
+./scripts/deploy-android.sh release # Deploy release APK
+```
+
+### `build-and-deploy.sh`
+Build and deploy in one command.
+```bash
+./scripts/build-and-deploy.sh       # Build + deploy debug
+./scripts/build-and-deploy.sh release  # Build + deploy release
+```
+
+### `check-android.sh`
+Check Android development environment setup.
+```bash
+./scripts/check-android.sh
+```
+
+### `logcat.sh`
+View Android logcat filtered for the app.
+```bash
+./scripts/logcat.sh
+```
+
+## Traceability & Documentation
+
+### `extract-traces.ts`
+Extract requirement IDs (TRACES) from source code and generate a traceability matrix mapping requirements to implementation locations.
+
+```bash
+bun run traces                    # Generate markdown report
+bun run traces:json              # Generate JSON report
+bun run traces:markdown           # Save to docs/traceability.md
+bun run traces:coverage           # Coverage gate — exits non-zero below 50%
+```
+
+The script scans all TypeScript, Svelte, and Rust files (plus `scripts/`)
+looking for `TRACES:` comments and generates a comprehensive mapping of:
+- Which code files implement which requirements
+- Line numbers and code context
+- Coverage summary by requirement type (UR, IR, DR, JA)
+
+**`bun run traces:coverage` is the supported way to check requirement coverage
+locally** — it runs the same computation CI does. Coverage denominators are
+derived from `docs/requirements.md` at run time; they are never hardcoded. An ID
+that appears in a `TRACES:` comment but is not defined in `requirements.md` is
+reported as *orphaned* and does not count toward coverage (see DR-093).
+
+> **Removed:** `check-req-coverage.sh`, `check-test-coverage.sh`, and
+> `find-req-implementations.sh` were deleted in July 2026. They read an
+> undocumented `@req:` tag convention parallel to `TRACES:`, grepped `src-tauri/`
+> unscoped (hanging on ~40 GB of `target/` artifacts), and in one case reported
+> "all requirements implemented" from an empty result set. `extract-traces.ts` is
+> the single source of truth for requirement coverage. See
+> [docs/specs/req-coverage-script-removal.md](../docs/specs/req-coverage-script-removal.md).
+
+Example TRACES comment in code:
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+function handlePlayback() { ... }
+```
+
+See [docs/traceability.md](../docs/traceability.md) for the latest generated mapping.
+
+### CI/CD Validation
+
+The traceability system is integrated with Gitea Actions CI/CD:
+- Automatically validates TRACES on every push and pull request
+- Enforces minimum 50% coverage threshold
+- Warns if new code lacks TRACES comments
+- Generates traceability reports automatically
+
+For details, see:
+- [Traceability CI Guide](../docs/traceability-ci.md) - Full CI/CD documentation
+- [TRACES Quick Reference](../docs/traces-quick-ref.md) - Quick guide for adding TRACES
+
+## Utility Scripts
+
+### `clean.sh`
+Clean all build artifacts.
+```bash
+./scripts/clean.sh
+```
+
+## NPM Script Aliases
+
+You can also run these via npm/bun:
+```bash
+bun run test:all           # All tests
+bun run test:rust          # Rust tests
+bun run android:build      # Build Android APK
+bun run android:deploy     # Deploy to device
+bun run android:dev        # Build + deploy debug
+bun run android:check      # Check environment
+bun run clean              # Clean artifacts
+```

scripts/android-dev.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -e
+
+echo "🚀 JellyTau Android Development Helper"
+echo "======================================"
+
+# Setup environment
+echo "Setting up environment..."
+source "$HOME/.cargo/env.fish" 2>/dev/null || source "$HOME/.cargo/env" || true
+export ANDROID_HOME="$HOME/Android/Sdk"
+export NDK_HOME="$ANDROID_HOME/ndk/$(ls $ANDROID_HOME/ndk 2>/dev/null | head -1)"
+
+# Check prerequisites
+echo -e "\n✓ Checking prerequisites..."
+
+if ! command -v rustc &> /dev/null; then
+    echo "❌ Rust not found. Please install from https://rustup.rs"
+    exit 1
+fi
+
+if ! command -v adb &> /dev/null; then
+    echo "❌ ADB not found. Please install Android SDK"
+    exit 1
+fi
+
+if [ ! -d "$ANDROID_HOME" ]; then
+    echo "⚠️  ANDROID_HOME not found at $ANDROID_HOME"
+    echo "   Please install Android SDK or update the path"
+fi
+
+# Check for connected devices
+echo -e "\n📱 Connected devices:"
+adb devices
+
+# Menu
+echo -e "\n📋 What would you like to do?"
+echo "1) Run in development mode (hot reload)"
+echo "2) Build debug APK"
+echo "3) Build release APK"
+echo "4) Install debug APK to device"
+echo "5) Check environment"
+read -p "Select option (1-5): " choice
+
+case $choice in
+    1)
+        echo -e "\n🔨 Starting development mode..."
+        bun run tauri android dev
+        ;;
+    2)
+        echo -e "\n🔨 Building debug APK..."
+        bun run tauri android build --debug
+        echo -e "\n✅ Debug APK built at:"
+        echo "   src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk"
+        ;;
+    3)
+        echo -e "\n🔨 Building release APK..."
+        bun run tauri android build
+        echo -e "\n✅ Release APK built at:"
+        echo "   src-tauri/gen/android/app/build/outputs/apk/release/"
+        ;;
+    4)
+        APK="src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk"
+        if [ -f "$APK" ]; then
+            echo -e "\n📲 Installing to device..."
+            adb install -r "$APK"
+            echo "✅ Installed!"
+        else
+            echo "❌ APK not found. Build it first (option 2)"
+        fi
+        ;;
+    5)
+        echo -e "\n🔍 Environment Check:"
+        echo "  Rust: $(rustc --version 2>/dev/null || echo 'Not found')"
+        echo "  Cargo: $(cargo --version 2>/dev/null || echo 'Not found')"
+        echo "  Bun: $(bun --version 2>/dev/null || echo 'Not found')"
+        echo "  ADB: $(adb --version 2>/dev/null | head -1 || echo 'Not found')"
+        echo "  ANDROID_HOME: $ANDROID_HOME"
+        echo "  NDK_HOME: $NDK_HOME"
+        echo ""
+        echo "  Rust Android targets:"
+        rustup target list 2>/dev/null | grep android | grep installed || echo "    None installed"
+        ;;
+    *)
+        echo "Invalid option"
+        exit 1
+        ;;
+esac

scripts/build-and-deploy.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Build and deploy Android APK in one command
+
+set -e
+
+echo "🚀 Build and Deploy Android APK"
+echo ""
+
+# Pass all args (build type and/or --clean) through to the build script.
+./scripts/build-android.sh "$@"
+
+echo ""
+
+# Deploy APK — forward the build type and the side-by-side flag (which decides
+# which package to launch), ignoring build-only flags like --clean and --device.
+DEPLOY_ARGS=("debug")
+for arg in "$@"; do
+    case "$arg" in
+        debug|release) DEPLOY_ARGS[0]="$arg" ;;
+        --debug|--side-by-side) DEPLOY_ARGS+=("--side-by-side") ;;
+    esac
+done
+./scripts/deploy-android.sh "${DEPLOY_ARGS[@]}"

scripts/build-android.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# Build Android APK
+
+set -e
+
+# Source Rust environment
+source "$HOME/.cargo/env.fish" 2>/dev/null || source "$HOME/.cargo/env" 2>/dev/null || true
+
+# Set Android environment variables
+export ANDROID_HOME="$HOME/Android/Sdk"
+export NDK_HOME="$ANDROID_HOME/ndk/$(ls "$ANDROID_HOME/ndk" | head -1)"
+
+echo "🤖 Building Android APK..."
+echo "Android SDK: $ANDROID_HOME"
+echo "NDK: $NDK_HOME"
+echo ""
+
+# Parse args: build type (debug/release) and optional --clean flag.
+# By default the build is INCREMENTAL — Cargo and Vite reuse their caches.
+# Pass --clean (or CLEAN=1) to wipe all caches for a from-scratch build.
+#
+# ABI selection: by default Tauri builds all four ABIs (arm64/arm/x86/x86_64),
+# which is what a distributable universal APK needs — but for an on-device test
+# it means three wasted Rust compiles. Pass --device (or ABI=aarch64) to build
+# only the connected device's architecture; --abi <t> targets one explicitly.
+#
+# Side-by-side: the `debug` build type always installs as
+# com.dtourolle.jellytau.debug ("JellyTau Debug"), so it never collides with a
+# real install. `release --debug` puts a *release* build — R8-minified, exactly
+# what ships — into that same slot, signed with the local debug keystore. That
+# is how you validate minification (R8 stripping JNI-loaded classes has broken
+# release APKs here before) without the real signing key and without
+# uninstalling the app you actually use.
+BUILD_TYPE="debug"
+CLEAN="${CLEAN:-0}"
+ABI="${ABI:-}"
+SIDE_BY_SIDE="${SIDE_BY_SIDE:-0}"
+next_is_abi=0
+for arg in "$@"; do
+    if [ "$next_is_abi" = "1" ]; then
+        ABI="$arg"
+        next_is_abi=0
+        continue
+    fi
+    case "$arg" in
+        --clean) CLEAN=1 ;;
+        --abi) next_is_abi=1 ;;
+        --device) ABI="device" ;;
+        --debug|--side-by-side) SIDE_BY_SIDE=1 ;;
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
+
+# The debug build type is side-by-side unconditionally; the flag only means
+# something for a release build.
+if [ "$BUILD_TYPE" = "debug" ]; then
+    SIDE_BY_SIDE=1
+fi
+
+# Resolve --device to the attached device's Rust target triple.
+if [ "$ABI" = "device" ]; then
+    device_abi="$(adb shell getprop ro.product.cpu.abi 2>/dev/null | tr -d '\r\n')"
+    case "$device_abi" in
+        arm64-v8a)   ABI="aarch64" ;;
+        armeabi-v7a) ABI="armv7" ;;
+        x86_64)      ABI="x86_64" ;;
+        x86)         ABI="i686" ;;
+        *)
+            echo "⚠️  Could not detect device ABI (got '${device_abi:-none}') — building all targets."
+            ABI=""
+            ;;
+    esac
+    [ -n "$ABI" ] && echo "🎯 Device ABI $device_abi → building only '$ABI'"
+fi
+
+TARGET_ARGS=()
+if [ -n "$ABI" ]; then
+    TARGET_ARGS=(--target "$ABI")
+fi
+
+# Step 0: Optionally clear build caches for a fully fresh build.
+if [ "$CLEAN" = "1" ]; then
+    echo "🧹 Clearing build caches (clean build)..."
+    rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target 2>/dev/null || true
+    npm install > /dev/null 2>&1
+fi
+
+# Step 1: Sync Android source files
+echo "🔄 Syncing Android sources..."
+./scripts/sync-android-sources.sh
+
+# Step 2: Build the frontend first to avoid dev server issues
+echo "🎨 Building frontend..."
+bun run build
+
+# Step 2: Build Android APK
+if [ "$BUILD_TYPE" = "release" ] && [ "$SIDE_BY_SIDE" = "1" ]; then
+    # A release build in the debug slot: R8 still runs, but the applicationId is
+    # suffixed and the debug keystore signs it (read by build.gradle.kts from
+    # JT_SIDE_BY_SIDE), so the real key is not needed and it replaces any other
+    # .debug install cleanly. Deliberately does NOT write keystore.properties.
+    echo "📦 Building side-by-side release APK (com.dtourolle.jellytau.debug)..."
+    JT_SIDE_BY_SIDE=1 bun run tauri android build --apk true "${TARGET_ARGS[@]}"
+elif [ "$BUILD_TYPE" = "release" ]; then
+    # Configure release signing from .env (single source of truth). Must run
+    # after sync-android-sources.sh, since gen/android is (re)generated there.
+    ./scripts/write-keystore-properties.sh
+    echo "📦 Building release APK..."
+    bun run tauri android build --apk true "${TARGET_ARGS[@]}"
+else
+    echo "📦 Building debug APK..."
+    bun run tauri android build --apk true --debug "${TARGET_ARGS[@]}"
+fi
+
+echo ""
+echo "✅ APK build complete!"
+echo "📱 APK location: src-tauri/gen/android/app/build/outputs/apk/"

scripts/build-arch.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Build an Arch Linux package (.pkg.tar.zst) for JellyTau via makepkg.
+#
+# Tauri's bundler has no pacman target (as of tauri-cli 2.9.x), so we ship a
+# hand-written PKGBUILD in packaging/arch/ and build it with makepkg. This must
+# run on an Arch host / the `arch-build` Docker stage — makepkg is Arch-specific
+# and refuses to run as root, so run it as a non-root user with sudo for deps.
+#
+# Usage (typically inside the arch-build Docker stage as a non-root user):
+#   scripts/build-arch.sh
+#   OUTPUT_DIR=/app/dist scripts/build-arch.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT/packaging/arch"
+
+echo "🏛️  Building JellyTau Arch package"
+echo "=================================="
+
+# Point the PKGBUILD at the working tree and give cargo/bun a writable home.
+export JELLYTAU_SRC="$REPO_ROOT"
+export CARGO_HOME="${CARGO_HOME:-$REPO_ROOT/.cargo-arch}"
+
+# -s installs missing deps (needs sudo/root privileges for pacman), -f overwrites.
+makepkg -sf --noconfirm
+
+echo ""
+echo "✅ Built Arch package(s):"
+ls -1 ./*.pkg.tar.zst
+
+if [[ -n "${OUTPUT_DIR:-}" ]]; then
+  mkdir -p "$OUTPUT_DIR"
+  cp -v ./*.pkg.tar.zst "$OUTPUT_DIR/"
+  echo ""
+  echo "📦 Copied Arch package(s) to $OUTPUT_DIR"
+fi

scripts/build-builder-image.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Build and push the JellyTau builder Docker image to your registry
+
+set -e
+
+# Configuration
+REGISTRY_HOST="${REGISTRY_HOST:-gitea.tourolle.paris}"
+REGISTRY_USER="${REGISTRY_USER:-dtourolle}"
+IMAGE_NAME="jellytau-builder"
+IMAGE_TAG="${1:-latest}"
+FULL_IMAGE_NAME="${REGISTRY_HOST}/${REGISTRY_USER}/${IMAGE_NAME}:${IMAGE_TAG}"
+
+echo "🐳 Building JellyTau Builder Image"
+echo "=================================="
+echo "Registry: $REGISTRY_HOST"
+echo "User: $REGISTRY_USER"
+echo "Image: $FULL_IMAGE_NAME"
+echo ""
+
+# Step 1: Build locally
+echo "🔨 Building Docker image locally..."
+docker build -f Dockerfile.builder -t ${IMAGE_NAME}:${IMAGE_TAG} .
+
+# Step 2: Tag for registry
+echo "🏷️  Tagging for registry..."
+docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${FULL_IMAGE_NAME}
+
+# Step 3: Login to registry (if not already logged in)
+echo "🔐 Checking registry authentication..."
+if ! docker info | grep -q "Username"; then
+    echo "Not authenticated to Docker. Logging in to ${REGISTRY_HOST}..."
+    docker login ${REGISTRY_HOST}
+fi
+
+# Step 4: Push to registry
+echo "📤 Pushing image to registry..."
+docker push ${FULL_IMAGE_NAME}
+
+echo ""
+echo "✅ Successfully built and pushed: ${FULL_IMAGE_NAME}"
+echo ""
+echo "Update your workflow to use:"
+echo "  container:"
+echo "    image: ${FULL_IMAGE_NAME}"

scripts/build-desktop-linux.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Build Linux desktop packages (deb + rpm) for JellyTau.
+#
+# Produces bundles under src-tauri/target/release/bundle/{deb,rpm}.
+# Runs on the existing Ubuntu builder image. NOTE: Tauri has no pacman bundle
+# target — the Arch package is built separately with makepkg (scripts/build-arch.sh
+# / Dockerfile.arch). `appimage` is also available if you want a portable bundle.
+#
+# Usage:
+#   scripts/build-desktop-linux.sh                 # deb + rpm
+#   BUNDLES="deb,appimage" scripts/build-desktop-linux.sh # subset / add appimage
+#   OUTPUT_DIR=/app/dist scripts/build-desktop-linux.sh   # copy bundles out
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+BUNDLES="${BUNDLES:-deb,rpm}"
+
+echo "🐧 Building JellyTau Linux desktop packages"
+echo "==========================================="
+echo "Bundles: $BUNDLES"
+echo ""
+
+bun install --frozen-lockfile 2>/dev/null || bun install
+bun run build
+
+# --bundles overrides tauri.conf.json bundle.targets so this script controls
+# exactly which Linux formats are produced (never NSIS here).
+bun run tauri build --bundles "$BUNDLES"
+
+BUNDLE_ROOT="src-tauri/target/release/bundle"
+echo ""
+echo "✅ Built packages:"
+find "$BUNDLE_ROOT" -maxdepth 2 -type f \
+  \( -name '*.deb' -o -name '*.rpm' -o -name '*.AppImage' \) -print
+
+if [[ -n "${OUTPUT_DIR:-}" ]]; then
+  mkdir -p "$OUTPUT_DIR"
+  find "$BUNDLE_ROOT" -maxdepth 2 -type f \
+    \( -name '*.deb' -o -name '*.rpm' -o -name '*.AppImage' \) \
+    -exec cp -v {} "$OUTPUT_DIR/" \;
+  echo ""
+  echo "📦 Copied bundles to $OUTPUT_DIR"
+fi

scripts/build-windows-cross.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Cross-compile JellyTau for Windows from Linux, producing an NSIS installer.
+#
+# Uses the OFFICIAL Tauri cross-compile path (https://v2.tauri.app/distribute/
+# windows-installer/): the MSVC target driven by cargo-xwin, which downloads the
+# MSVC CRT/Windows SDK headers and links with lld. This is the target Tauri
+# officially supports for Windows (the mingw/GNU target is not), and unlike GNU
+# it can bundle the NSIS installer from a Linux host.
+#
+# Playback on Windows: video renders via WebView2 and audio via the webview
+# <audio> backend (WebviewAudioBackend) — see docs/build-windows.md.
+#
+# Requirements (present in the Docker windows-cross target / unified builder):
+#   - rustup target x86_64-pc-windows-msvc
+#   - cargo-xwin           (cargo install --locked cargo-xwin)
+#   - lld, llvm            (linker + llvm-lib used by cargo-xwin)
+#   - nsis (makensis)      (installer generator)
+#
+# Usage:
+#   scripts/build-windows-cross.sh                    # exe + NSIS installer
+#   WIN_BUNDLES=none scripts/build-windows-cross.sh   # exe only, skip bundling
+#   OUTPUT_DIR=/app/dist scripts/build-windows-cross.sh
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+TARGET="x86_64-pc-windows-msvc"
+WIN_BUNDLES="${WIN_BUNDLES:-nsis}"
+
+echo "🪟 Cross-compiling JellyTau for Windows ($TARGET, via cargo-xwin)"
+echo "================================================================"
+echo "Video plays via WebView2; audio via the webview <audio> backend."
+echo "Bundles: $WIN_BUNDLES"
+echo ""
+
+bun install --frozen-lockfile 2>/dev/null || bun install
+bun run build
+
+# --runner cargo-xwin + the MSVC target is what makes the Tauri CLI treat this as
+# a real Windows build and enable the nsis/msi bundlers on a Linux host.
+#
+# IMPORTANT: do NOT pass `--bundles nsis` here. tauri-cli 2.9.x validates the
+# `--bundles` flag against a static clap enum gated by the HOST OS (Linux allows
+# only deb/rpm/appimage) *before* it considers --target/--runner, so `--bundles
+# nsis` is rejected at arg-parse time. Instead the Windows bundle targets come
+# from tauri.conf.json (bundle.targets includes "nsis"), which is not subject to
+# that CLI validation — the bundler then picks nsis once it knows the target is
+# Windows.
+if [[ "$WIN_BUNDLES" == "none" ]]; then
+  bun run tauri build --runner cargo-xwin --target "$TARGET" --no-bundle
+else
+  bun run tauri build --runner cargo-xwin --target "$TARGET"
+fi
+
+BIN_DIR="src-tauri/target/$TARGET/release"
+echo ""
+echo "✅ Built Windows artifacts:"
+find "$BIN_DIR" -maxdepth 1 -name '*.exe' -print
+find "$BIN_DIR/bundle" -type f \( -name '*.exe' -o -name '*.msi' \) -print 2>/dev/null || true
+
+if [[ -n "${OUTPUT_DIR:-}" ]]; then
+  mkdir -p "$OUTPUT_DIR"
+  find "$BIN_DIR" -maxdepth 1 -name 'jellytau.exe' -exec cp -v {} "$OUTPUT_DIR/" \;
+  # NSIS setup installers land in bundle/nsis/*-setup.exe; MSI in bundle/msi/*.msi.
+  find "$BIN_DIR/bundle" -type f \( -name '*-setup.exe' -o -name '*.msi' \) \
+    -exec cp -v {} "$OUTPUT_DIR/" \; 2>/dev/null || true
+  echo ""
+  echo "📦 Copied Windows artifacts to $OUTPUT_DIR"
+fi

scripts/check-android.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Check Android development environment
+
+set -e
+
+echo "🔍 Checking Android development environment..."
+echo ""
+
+# Check ADB
+if command -v adb &> /dev/null; then
+    echo "✅ ADB installed: $(adb version | head -1)"
+else
+    echo "❌ ADB not found"
+fi
+
+# Check Android SDK
+if [ -d "$HOME/Android/Sdk" ]; then
+    echo "✅ Android SDK found at: $HOME/Android/Sdk"
+else
+    echo "❌ Android SDK not found at: $HOME/Android/Sdk"
+fi
+
+# Check NDK
+if [ -d "$HOME/Android/Sdk/ndk" ]; then
+    NDK_VERSION=$(ls "$HOME/Android/Sdk/ndk" | head -1)
+    echo "✅ NDK found: $NDK_VERSION"
+else
+    echo "❌ NDK not found"
+fi
+
+# Check Rust
+if command -v rustc &> /dev/null; then
+    echo "✅ Rust installed: $(rustc --version)"
+else
+    echo "❌ Rust not found"
+fi
+
+# Check Cargo
+if command -v cargo &> /dev/null; then
+    echo "✅ Cargo installed: $(cargo --version)"
+else
+    echo "❌ Cargo not found"
+fi
+
+# Check for connected devices
+echo ""
+echo "📱 Connected Android devices:"
+if adb devices | grep -q "device$"; then
+    adb devices | grep "device$"
+else
+    echo "⚠️  No devices connected"
+fi
+
+echo ""
+echo "🔍 Environment check complete!"

scripts/check-frontend-boundary.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Boundary tripwire: flag domain-taxonomy leaks in the Svelte frontend.
+#
+# Implements DR-094 (see docs/requirements.md).
+#
+# The project rule (CLAUDE.md, docs/architecture/02-svelte-frontend.md) is that
+# the frontend is presentation-only and the Rust backend owns domain logic —
+# including Jellyfin's item-type *taxonomy* (what the category "Music" means as a
+# set of item types). See docs/specs/scoped-search-boundary.md for the incident
+# that motivated this check.
+#
+# ⚠️ This is a TRIPWIRE, NOT A PROOF. A grep cannot distinguish taxonomy-as-policy
+# (a leak) from taxonomy-as-display (legitimate: "is this a music card?"). It
+# targets the machine-detectable signature of the leak class and defers
+# everything subtler to the human spec-review checklist
+# (docs/specs/SPEC-REVIEW-CHECKLIST.md). A clean run here does not mean the
+# boundary is respected; it means the crudest violation isn't present.
+#
+# What it flags: an array literal naming two or more Jellyfin item types,
+# ANYWHERE in src/ — i.e. the frontend deciding that a *category* maps to a *set*
+# of Jellyfin types, which is domain knowledge the backend should own.
+# Single-type arrays (`includeItemTypes: ["Movie"]`) are a page saying "I show
+# movies" and are allowed. Type *inspection* (`item.type === "Audio"`) is display
+# logic and is not matched.
+#
+# 🔴 What it still CANNOT see (do not read a green run as proof):
+#   - a type set built at run time:      [...musicTypes, "Playlist"]
+#   - types split across variables:      const A = "Audio"; [A, B]
+#   - taxonomy as control flow:          switch (t) { case "Audio": … }
+#                                        t === "Audio" || t === "MusicAlbum"
+#   - an item type absent from ITEM_TYPES below (false negative by design)
+#
+# This check was hardened in July 2026 after the audit found it passing on the
+# very leak it was written for: the original pattern was anchored to
+# `includeItemTypes:` at the query site, so assigning the same array to a named
+# const evaded it entirely. See docs/specs/boundary-tripwire-hardening.md (DR-094).
+#
+# Escaping a genuine exception: add the file+reason to the ALLOWLIST below.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Files permitted to contain a multi-type item-type array, with the reason.
+# Keep this SHORT. A growing allowlist means the boundary is eroding — that is a
+# signal to push taxonomy into Rust, not to keep appending here.
+ALLOWLIST=(
+  # "Things a person appeared in" is arguably taxonomy, but it is a fixed
+  # two-type filmography query with no category-configuration behind it. Tracked
+  # as acceptable pending any person-scope work; revisit if it grows.
+  "src/lib/components/library/PersonDetailView.svelte"
+
+  # Grid styling predicate over `config.itemType`, a value the page already
+  # declares about itself. Selects a *look*, issues no query, and would only
+  # change if the UI were redesigned — presentation, not taxonomy-as-policy.
+  "src/lib/components/library/GenericMediaListPage.svelte"
+
+  # "Is this item a container?" predicate for downloads browsing.
+  # BORDERLINE — leans domain: the container set grows when Jellyfin adds a
+  # container type. TODO: replace with a backend-supplied `MediaItem.isContainer`
+  # flag and remove this entry. Tracked in
+  # docs/specs/boundary-tripwire-hardening.md §Out of scope.
+  "src/lib/components/downloads/DownloadedBrowse.svelte"
+)
+
+# Hard cap so erosion is caught mechanically rather than by whoever notices.
+# Deliberately just above the current count: the next exception forces a
+# conversation instead of a one-line append.
+MAX_ALLOWLIST=4
+
+if [[ "${#ALLOWLIST[@]}" -gt "$MAX_ALLOWLIST" ]]; then
+  echo "❌ Allowlist has ${#ALLOWLIST[@]} entries (max $MAX_ALLOWLIST)."
+  echo "   Push taxonomy into Rust instead of appending here."
+  exit 1
+fi
+
+is_allowed() {
+  local file="$1"
+  for allowed in "${ALLOWLIST[@]}"; do
+    [[ "$file" == "$allowed" ]] && return 0
+  done
+  return 1
+}
+
+# Two or more adjacent Jellyfin item-type string literals inside a bracket.
+#
+# NOT anchored to `includeItemTypes:` — that was the original rule, and it missed
+# the real leak: `searchScope.ts` assigned the same array to a named const and
+# dereferenced it one indirection away from the query, so the grep never saw it
+# while CI stayed green. Matching the array literal itself catches a const, a
+# Record value, a function return, and an inline query alike.
+#
+# Deliberate limits:
+#   - requires TWO adjacent types, so single-type presentation
+#     (`itemType: "Movie"`) stays legal — the rule targets *category* taxonomy;
+#   - requires string literals, so `item.type === "Audio"` (display inspection)
+#     does not match;
+#   - uses an explicit type list rather than a generic capitalised-word pattern,
+#     so unrelated string arrays (`["High","Low"]`) produce no noise.
+#
+# An item type missing from this list is a false *negative*, never a false
+# positive — the check degrades safely as Jellyfin adds types.
+ITEM_TYPES='Movie|Series|Episode|Audio|MusicAlbum|MusicArtist|MusicVideo|Season|BoxSet|Playlist|Book|AudioBook|Video|Person|Folder|CollectionFolder|TvChannel|LiveTvChannel'
+PATTERN="\[[[:space:]]*\"($ITEM_TYPES)\"[[:space:]]*,[[:space:]]*\"($ITEM_TYPES)\""
+
+echo "🔎 Checking frontend for domain-taxonomy leaks (item-type array literals)…"
+
+# Collect hits, excluding tests and the allowlist.
+violations=""
+while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+  file="${line%%:*}"
+  case "$file" in
+    *.test.*) continue ;;
+  esac
+  if is_allowed "$file"; then
+    echo "  ⏭️  allowlisted: $line"
+    continue
+  fi
+  violations+="$line"$'\n'
+done < <(grep -rInE "$PATTERN" src/ 2>/dev/null || true)
+
+if [[ -n "$violations" ]]; then
+  echo ""
+  echo "❌ Frontend boundary violation: an item-type array literal defines a"
+  echo "   category in the presentation layer. That taxonomy belongs in Rust —"
+  echo "   send an opaque scope/enum and let the backend expand it to item types"
+  echo "   (see SearchScope::item_types() in src-tauri/src/repository/types.rs)."
+  echo "   Assigning the array to a const does not make it presentation."
+  echo "   See docs/specs/scoped-search-boundary.md and CLAUDE.md."
+  echo ""
+  echo "$violations" | sed 's/^/   /'
+  echo "   If this is a genuine exception, add the file + reason to ALLOWLIST in"
+  echo "   scripts/check-frontend-boundary.sh — but prefer moving it to Rust."
+  exit 1
+fi
+
+echo "✅ No multi-type taxonomy queries in the frontend."
+echo "   (Reminder: this is a tripwire, not a proof — the spec-review checklist is"
+echo "    the real gate for subtler leaks.)"

scripts/clean.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Clean build artifacts
+
+set -e
+
+echo "🧹 Cleaning build artifacts..."
+echo ""
+
+# Clean frontend
+if [ -d "node_modules/.cache" ]; then
+    echo "Cleaning Vite cache..."
+    rm -rf node_modules/.cache
+fi
+
+if [ -d ".svelte-kit" ]; then
+    echo "Cleaning SvelteKit build..."
+    rm -rf .svelte-kit
+fi
+
+if [ -d "build" ]; then
+    echo "Cleaning build directory..."
+    rm -rf build
+fi
+
+# Clean Rust
+echo "Cleaning Rust target..."
+cd src-tauri
+cargo clean
+cd ..
+
+# Clean Android
+if [ -d "src-tauri/gen/android" ]; then
+    echo "Cleaning Android build..."
+    cd src-tauri/gen/android
+    ./gradlew clean 2>/dev/null || true
+    cd ../../..
+fi
+
+echo ""
+echo "✅ Clean complete!"

scripts/deploy-android.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Deploy APK to connected Android device
+
+set -e
+
+echo "📱 Deploying to Android device..."
+echo ""
+
+# Check if device is connected
+if ! adb devices | grep -q "device$"; then
+    echo "❌ No Android device connected!"
+    echo "Please connect a device or start an emulator."
+    exit 1
+fi
+
+# Build type: debug or release (default: debug). `--debug` alongside `release`
+# means the side-by-side release build — same APK path, but it was packaged
+# under the .debug applicationId, so the package to launch differs.
+BUILD_TYPE="debug"
+SIDE_BY_SIDE=0
+for arg in "$@"; do
+    case "$arg" in
+        --debug|--side-by-side) SIDE_BY_SIDE=1 ;;
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
+[ "$BUILD_TYPE" = "debug" ] && SIDE_BY_SIDE=1
+
+# The .debug applicationId (see src-tauri/android/app/build.gradle.kts) is a
+# separate package, so it installs alongside a real release build — no
+# uninstall dance needed.
+if [ "$BUILD_TYPE" = "release" ]; then
+    APK_PATH="src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk"
+else
+    APK_PATH="src-tauri/gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk"
+fi
+
+if [ "$SIDE_BY_SIDE" = "1" ]; then
+    APP_PACKAGE="com.dtourolle.jellytau.debug"
+else
+    APP_PACKAGE="com.dtourolle.jellytau"
+fi
+
+# Check if APK exists
+if [ ! -f "$APK_PATH" ]; then
+    echo "❌ APK not found at: $APK_PATH"
+    if [ "$BUILD_TYPE" = "release" ] && [ "$SIDE_BY_SIDE" = "1" ]; then
+        echo "Run './scripts/build-android.sh release --debug' first"
+    else
+        echo "Run './scripts/build-android.sh $BUILD_TYPE' first"
+    fi
+    exit 1
+fi
+
+echo "📦 Installing APK: $APK_PATH"
+echo "📛 Package: $APP_PACKAGE"
+
+if ! adb install -r "$APK_PATH"; then
+    echo ""
+    echo "❌ Install failed."
+    echo "   If it says INSTALL_FAILED_UPDATE_INCOMPATIBLE, an older build of"
+    echo "   '$APP_PACKAGE' signed with a different key is still installed."
+    echo "   Uninstall just that one and retry:"
+    echo "     adb uninstall $APP_PACKAGE"
+    exit 1
+fi
+
+echo ""
+echo "✅ Deployment complete!"
+echo "🚀 Launching..."
+adb shell monkey -p "$APP_PACKAGE" -c android.intent.category.LAUNCHER 1 > /dev/null 2>&1 \
+    || echo "   (auto-launch failed — start it from the launcher)"

scripts/extract-traces.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for the traceability coverage computation.
+ *
+ * These run over fixture strings rather than the live docs/requirements.md, so
+ * their meaning does not drift as requirements are added.
+ *
+ * Background: the CI gate divided traced-requirement counts by hardcoded
+ * denominators (UR/39, IR/24, DR/48, JA/3, total 114) that had fallen out of
+ * date, reporting 158% coverage and making the 50% threshold unreachable. These
+ * tests pin the parsing and arithmetic that replace those literals.
+ *
+ * @req-test: UT-089 - Requirement definitions parsed from requirements.md
+ * @req-test: UT-090 - Coverage is the intersection of traced and defined IDs
+ */
+
+import { describe, it, expect } from "vitest";
+import { countDefinedRequirements, computeCoverage } from "./extract-traces";
+
+describe("countDefinedRequirements", () => {
+  it("counts a well-formed table row as a defined requirement", () => {
+    const md = `
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| UR-001 | Run the app on multiple platforms | High | In Progress |
+| UR-002 | Access media when online or offline | High | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(2);
+    expect(defined.DR).toBe(0);
+  });
+
+  it("does not count IDs that appear only in the Traces To column", () => {
+    // The bug this rule avoids: a naive grep for /DR-\d{3}/ over the whole file
+    // counts DR-001 here as "defined", inflating the denominator with IDs that
+    // are merely referenced.
+    const md = `
+| DR-001 | Player state machine | Player | UR-005 | Done |
+| DR-002 | MediaItem struct | Player | UR-003, UR-004 | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.DR).toBe(2);
+    // UR-005/UR-003/UR-004 are referenced, never defined here.
+    expect(defined.UR).toBe(0);
+  });
+
+  it("does not count IDs mentioned in prose", () => {
+    const md = `
+Some prose explaining that UR-005 relates to DR-001 and JA-002.
+
+| UR-005 | Control media playback | High | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(1);
+    expect(defined.DR).toBe(0);
+    expect(defined.JA).toBe(0);
+  });
+
+  it("deduplicates an ID listed in both the spec table and the traceability matrix", () => {
+    // requirements.md lists every UR twice: once in §1 (definition) and again in
+    // §3 (traceability matrix), both as a leading table cell. Counting rows
+    // instead of unique IDs double-counts the UR denominator (121 vs 61).
+    const md = `
+| UR-005 | Control media playback | High | Done |
+| UR-006 | Browse the library | High | Done |
+
+### Traceability Matrix
+
+| UR-005 | - | DR-001, DR-005, DR-009 |
+| UR-006 | - | DR-012 |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(2);
+  });
+
+  it("collects the defined ID set, not just counts", () => {
+    const md = `
+| UR-001 | A | High | Done |
+| DR-050 | B | Player | UR-001 | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.ids.has("UR-001")).toBe(true);
+    expect(defined.ids.has("DR-050")).toBe(true);
+    expect(defined.ids.has("UR-999")).toBe(false);
+  });
+});
+
+describe("computeCoverage", () => {
+  const defined = {
+    UR: 2,
+    IR: 0,
+    DR: 2,
+    JA: 0,
+    total: 4,
+    ids: new Set(["UR-001", "UR-002", "DR-001", "DR-002"]),
+  };
+
+  it("computes coverage as traced ∩ defined over defined", () => {
+    const traced = ["UR-001", "DR-001"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(2);
+    expect(cov.total).toBe(4);
+    expect(cov.percent).toBe(50);
+  });
+
+  it("does not let a traced-but-undefined ID inflate the numerator", () => {
+    // This is how a ratio exceeds 100%: a TRACES comment naming a typo'd or
+    // deleted requirement counted as covered.
+    const traced = ["UR-001", "DR-001", "DR-097"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(2);
+    expect(cov.percent).toBe(50);
+  });
+
+  it("reports traced-but-undefined IDs as orphaned so they get fixed", () => {
+    const traced = ["UR-001", "DR-097", "JA-404"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.orphaned).toEqual(["DR-097", "JA-404"]);
+  });
+
+  it("has no orphans when every traced ID is defined", () => {
+    const cov = computeCoverage(["UR-001", "UR-002"], defined);
+    expect(cov.orphaned).toEqual([]);
+  });
+
+  it("ignores UT/IT test IDs entirely — they are a separate taxonomy", () => {
+    // UT/IT are defined in §4 of requirements.md, not among the four
+    // requirement types. Treating them as orphans buries real typos in ~60
+    // lines of noise, and counting them would corrupt the ratio.
+    const cov = computeCoverage(["UR-001", "UT-088", "IT-017"], defined);
+    expect(cov.orphaned).toEqual([]);
+    expect(cov.covered).toBe(1);
+  });
+
+  it("reports 0% rather than dividing by zero for an empty trace set", () => {
+    const cov = computeCoverage([], defined);
+    expect(cov.covered).toBe(0);
+    expect(cov.percent).toBe(0);
+  });
+
+  it("reports 0% rather than NaN when nothing is defined", () => {
+    const empty = { UR: 0, IR: 0, DR: 0, JA: 0, total: 0, ids: new Set<string>() };
+    const cov = computeCoverage([], empty);
+    expect(cov.percent).toBe(0);
+    expect(Number.isNaN(cov.percent)).toBe(false);
+  });
+
+  it("reports exactly 100% when all defined requirements are traced, never above", () => {
+    const traced = ["UR-001", "UR-002", "DR-001", "DR-002"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.percent).toBe(100);
+  });
+
+  it("ignores duplicate traced IDs", () => {
+    const traced = ["UR-001", "UR-001", "UR-001"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(1);
+  });
+});
+
+describe("live requirements.md", () => {
+  it("parses the real file to the counts the CI gate must use", () => {
+    // Guards the specific regression: CI hardcoded UR/39, IR/24, DR/48, JA/3
+    // (total 114) while the real file had grown to 211. Update these numbers
+    // deliberately when requirements are added — that edit is the signal the
+    // denominator is live rather than frozen.
+    const fs = require("fs");
+    const path = require("path");
+    // import.meta.dir is Bun-only; derive from import.meta.url under vitest.
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    const md = fs.readFileSync(
+      path.resolve(here, "../docs/requirements.md"),
+      "utf-8"
+    );
+    const defined = countDefinedRequirements(md);
+
+    expect(defined.UR).toBe(75);
+    expect(defined.IR).toBe(32);
+    expect(defined.DR).toBe(185);
+    expect(defined.JA).toBe(35);
+    expect(defined.total).toBe(327);
+  });
+});

scripts/extract-traces.ts

@@ -0,0 +1,462 @@
+#!/usr/bin/env bun
+/**
+ * Extract TRACES from source code and generate requirement mapping
+ *
+ * Usage:
+ *   bun run scripts/extract-traces.ts
+ *   bun run scripts/extract-traces.ts --format json
+ *   bun run scripts/extract-traces.ts --format markdown > docs/traceability.md
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+interface TraceEntry {
+  file: string;
+  line: number;
+  context: string;
+  requirements: string[];
+}
+
+interface RequirementMapping {
+  [reqId: string]: TraceEntry[];
+}
+
+interface TracesData {
+  timestamp: string;
+  totalFiles: number;
+  totalTraces: number;
+  requirements: RequirementMapping;
+  byType: {
+    UR: string[];
+    IR: string[];
+    DR: string[];
+    JA: string[];
+  };
+  /** Requirements *defined* in requirements.md — the coverage denominators. */
+  defined?: { UR: number; IR: number; DR: number; JA: number; total: number };
+  coverage?: CoverageResult;
+}
+
+// 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.
+//
+// `import.meta.dir` is a Bun extension and is undefined when this module is
+// imported by vitest (which runs it as an ordinary ESM module), so fall back to
+// import.meta.url — this file must stay importable for extract-traces.test.ts.
+const SCRIPT_DIR =
+  import.meta.dir ?? path.dirname(new URL(import.meta.url).pathname);
+const BASE_DIR = path.resolve(SCRIPT_DIR, "..");
+
+const TRACES_PATTERN = /TRACES:\s*([^\n]+)/gi;
+const REQ_ID_PATTERN = /([A-Z]{2})-(\d{3})/g;
+
+function extractRequirementIds(tracesString: string): string[] {
+  const matches = [...tracesString.matchAll(REQ_ID_PATTERN)];
+  return matches.map((m) => `${m[1]}-${m[2]}`);
+}
+
+function getAllSourceFiles(): string[] {
+  const baseDir = BASE_DIR;
+  // `scripts` is scanned too: build tooling implements requirements (e.g.
+  // DR-093, the coverage engine itself) and would otherwise be invisible to the
+  // very matrix it generates.
+  const patterns = ["src", "src-tauri/src", "scripts"];
+  const files: string[] = [];
+
+  function walkDir(dir: string) {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(baseDir, fullPath);
+
+        // Skip node_modules, target, build
+        if (
+          relativePath.includes("node_modules") ||
+          relativePath.includes("target") ||
+          relativePath.includes("build") ||
+          relativePath.includes(".git")
+        ) {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          walkDir(fullPath);
+        } else if (
+          entry.name.endsWith(".ts") ||
+          entry.name.endsWith(".svelte") ||
+          entry.name.endsWith(".rs")
+        ) {
+          files.push(fullPath);
+        }
+      }
+    } catch (error) {
+      // Skip directories we can't read
+    }
+  }
+
+  for (const pattern of patterns) {
+    const dir = path.join(baseDir, pattern);
+    if (fs.existsSync(dir)) {
+      walkDir(dir);
+    }
+  }
+
+  return files;
+}
+
+function extractTraces(): TracesData {
+  const requirementMap: RequirementMapping = {};
+  const byType: Record<string, Set<string>> = {
+    UR: new Set(),
+    IR: new Set(),
+    DR: new Set(),
+    JA: new Set(),
+  };
+
+  let totalTraces = 0;
+  const baseDir = BASE_DIR;
+
+  const files = getAllSourceFiles();
+
+  for (const fullPath of files) {
+    try {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      const lines = content.split("\n");
+      const relativePath = path.relative(baseDir, fullPath);
+
+      let match;
+      TRACES_PATTERN.lastIndex = 0;
+
+      while ((match = TRACES_PATTERN.exec(content)) !== null) {
+        const tracesStr = match[1];
+        const reqIds = extractRequirementIds(tracesStr);
+
+        if (reqIds.length === 0) continue;
+
+        // Find line number
+        const beforeMatch = content.substring(0, match.index);
+        const lineNum = beforeMatch.split("\n").length - 1;
+
+        // Get context (function/class name if available)
+        let context = "Unknown";
+        for (let i = lineNum; i >= Math.max(0, lineNum - 10); i--) {
+          const line = lines[i];
+          if (
+            line.includes("function ") ||
+            line.includes("export const ") ||
+            line.includes("pub fn ") ||
+            line.includes("pub enum ") ||
+            line.includes("pub struct ") ||
+            line.includes("impl ") ||
+            line.includes("async function ") ||
+            line.includes("class ") ||
+            line.includes("export type ")
+          ) {
+            context = line
+              .trim()
+              .replace(/^\s*\/\/\s*/, "")
+              .replace(/^\s*\/\*\*\s*/, "");
+            break;
+          }
+        }
+
+        const entry: TraceEntry = {
+          file: relativePath,
+          line: lineNum + 1,
+          context,
+          requirements: reqIds,
+        };
+
+        for (const reqId of reqIds) {
+          if (!requirementMap[reqId]) {
+            requirementMap[reqId] = [];
+          }
+          requirementMap[reqId].push(entry);
+
+          // Track by type
+          const type = reqId.substring(0, 2);
+          if (byType[type]) {
+            byType[type].add(reqId);
+          }
+        }
+
+        totalTraces++;
+      }
+    } catch (error) {
+      // Skip files we can't read
+    }
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    totalFiles: files.length,
+    totalTraces,
+    requirements: requirementMap,
+    byType: {
+      UR: Array.from(byType["UR"]).sort(),
+      IR: Array.from(byType["IR"]).sort(),
+      DR: Array.from(byType["DR"]).sort(),
+      JA: Array.from(byType["JA"]).sort(),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Coverage: how many *defined* requirements are actually traced.
+//
+// The denominators MUST be derived from requirements.md, never hardcoded. The
+// CI gate previously divided by frozen literals (UR/39, IR/24, DR/48, JA/3,
+// total 114) while the real file had grown to 211 requirements, so it reported
+// 158% coverage and the 50% threshold became unreachable — the gate could not
+// fail. See docs/specs/traceability-gate-repair.md.
+//
+// TRACES: | DR-093
+// ---------------------------------------------------------------------------
+
+export interface DefinedRequirements {
+  UR: number;
+  IR: number;
+  DR: number;
+  JA: number;
+  total: number;
+  ids: Set<string>;
+}
+
+export interface CoverageResult {
+  covered: number;
+  total: number;
+  percent: number;
+  /** Traced in code but not defined in requirements.md (typo, or deleted req). */
+  orphaned: string[];
+}
+
+/**
+ * A requirement is *defined* only where its ID is the leading cell of a markdown
+ * table row: `| DR-001 | … |`.
+ *
+ * This deliberately ignores IDs in the "Traces To" column and in prose — a
+ * naive scan for /DR-\d{3}/ counts those as definitions and inflates the
+ * denominator. IDs are deduplicated because requirements.md lists each UR twice
+ * (once in §1 as a definition, again in §3's traceability matrix), which would
+ * otherwise double the UR count from 61 to 121.
+ *
+ * TRACES: | DR-093
+ */
+export function countDefinedRequirements(markdown: string): DefinedRequirements {
+  const ids = new Set<string>();
+  const ROW_ID = /^\|\s*(UR|IR|DR|JA)-(\d{3})\s*\|/;
+
+  for (const line of markdown.split("\n")) {
+    const match = line.match(ROW_ID);
+    if (match) ids.add(`${match[1]}-${match[2]}`);
+  }
+
+  const countOf = (type: string) =>
+    [...ids].filter((id) => id.startsWith(`${type}-`)).length;
+
+  return {
+    UR: countOf("UR"),
+    IR: countOf("IR"),
+    DR: countOf("DR"),
+    JA: countOf("JA"),
+    total: ids.size,
+    ids,
+  };
+}
+
+/**
+ * Coverage is the *intersection* of traced and defined IDs over defined IDs.
+ *
+ * Using the raw traced count as the numerator is what lets a ratio exceed 100%:
+ * a TRACES comment naming a requirement that no longer exists would count as
+ * covered. Those IDs are reported as `orphaned` so they get fixed rather than
+ * silently counted or silently dropped.
+ *
+ * TRACES: | DR-093
+ */
+export function computeCoverage(
+  tracedIds: string[],
+  defined: DefinedRequirements
+): CoverageResult {
+  // Only the four *requirement* types participate in coverage. UT/IT are test
+  // identifiers defined in §4 of requirements.md — a different taxonomy, and
+  // flagging them as orphans would bury real typos in ~60 lines of noise.
+  const isRequirement = (id: string) => /^(UR|IR|DR|JA)-\d{3}$/.test(id);
+
+  const traced = new Set(tracedIds.filter(isRequirement));
+  const covered = [...traced].filter((id) => defined.ids.has(id));
+  const orphaned = [...traced].filter((id) => !defined.ids.has(id)).sort();
+
+  return {
+    covered: covered.length,
+    total: defined.total,
+    percent:
+      defined.total === 0
+        ? 0
+        : Math.round((covered.length / defined.total) * 100),
+    orphaned,
+  };
+}
+
+/** Read requirements.md from the repo and count what it defines. */
+export function readDefinedRequirements(): DefinedRequirements {
+  const reqPath = path.join(BASE_DIR, "docs", "requirements.md");
+  return countDefinedRequirements(fs.readFileSync(reqPath, "utf-8"));
+}
+
+function generateMarkdown(data: TracesData): string {
+  let md = `# Code Traceability Matrix
+
+**Generated:** ${new Date(data.timestamp).toLocaleString()}
+
+## Summary
+
+- **Total Files Scanned:** ${data.totalFiles}
+- **Total TRACES Found:** ${data.totalTraces}
+- **Requirements Covered:**
+  - User Requirements (UR): ${data.byType.UR.length}
+  - Integration Requirements (IR): ${data.byType.IR.length}
+  - Development Requirements (DR): ${data.byType.DR.length}
+  - Jellyfin API Requirements (JA): ${data.byType.JA.length}
+
+## Requirements by Type
+
+### User Requirements (UR)
+\`\`\`
+${data.byType.UR.join(", ")}
+\`\`\`
+
+### Integration Requirements (IR)
+\`\`\`
+${data.byType.IR.join(", ")}
+\`\`\`
+
+### Development Requirements (DR)
+\`\`\`
+${data.byType.DR.join(", ")}
+\`\`\`
+
+### Jellyfin API Requirements (JA)
+\`\`\`
+${data.byType.JA.join(", ")}
+\`\`\`
+
+## Detailed Mapping
+
+`;
+
+  // Sort requirements by ID
+  const sortedReqs = Object.keys(data.requirements).sort((a, b) => {
+    const typeA = a.substring(0, 2);
+    const typeB = b.substring(0, 2);
+    const typeOrder = { UR: 0, IR: 1, DR: 2, JA: 3 };
+    if (typeOrder[typeA] !== typeOrder[typeB]) {
+      return (typeOrder[typeA] || 4) - (typeOrder[typeB] || 4);
+    }
+    return a.localeCompare(b);
+  });
+
+  for (const reqId of sortedReqs) {
+    const entries = data.requirements[reqId];
+    md += `### ${reqId}\n\n`;
+    md += `**Locations:** ${entries.length} file(s)\n\n`;
+
+    for (const entry of entries) {
+      md += `- **File:** [\`${entry.file}\`](${entry.file}#L${entry.line})\n`;
+      md += `  - **Line:** ${entry.line}\n`;
+      const contextPreview = entry.context.substring(0, 70);
+      md += `  - **Context:** \`${contextPreview}${entry.context.length > 70 ? "..." : ""}\`\n`;
+    }
+    md += "\n";
+  }
+
+  return md;
+}
+
+function generateJson(data: TracesData): string {
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Human-readable coverage report; exits non-zero below the threshold so this is
+ * runnable as a local gate (`bun run traces:coverage`), not just in CI.
+ *
+ * TRACES: | DR-093
+ */
+function reportCoverage(data: TracesData, minThreshold: number): number {
+  const defined = data.defined!;
+  const cov = data.coverage!;
+
+  const definedIds = readDefinedRequirements().ids;
+
+  console.log("📋 Requirement coverage (traced / defined):");
+  for (const type of ["UR", "IR", "DR", "JA"] as const) {
+    const traced = data.byType[type].filter((id) => definedIds.has(id)).length;
+    console.log(`   ${type}: ${traced} / ${defined[type]}`);
+  }
+  console.log("");
+  console.log(`📈 Overall: ${cov.covered} / ${cov.total} (${cov.percent}%)`);
+
+  if (cov.orphaned.length > 0) {
+    console.log("");
+    console.log(
+      `⚠️  Traced but not defined in requirements.md: ${cov.orphaned.join(", ")}`
+    );
+    console.log("   Fix the TRACES comment or add the requirement.");
+  }
+
+  // A ratio above 100% means the computation is broken (the condition that hid
+  // the stale-denominator bug for so long). Fail loudly rather than report it.
+  if (cov.percent > 100) {
+    console.log("");
+    console.log(`❌ Coverage > 100% — the gate is miscomputing.`);
+    return 1;
+  }
+
+  if (cov.percent < minThreshold) {
+    console.log("");
+    console.log(`❌ Coverage (${cov.percent}%) is below minimum (${minThreshold}%)`);
+    return 1;
+  }
+
+  console.log("");
+  console.log(`✅ Coverage is acceptable (${cov.percent}% >= ${minThreshold}%)`);
+  return 0;
+}
+
+// Main — guarded so this module stays importable from extract-traces.test.ts.
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const format = args.includes("--format")
+    ? args[args.indexOf("--format") + 1]
+    : "markdown";
+
+  console.error("🔍 Extracting TRACES from codebase...");
+  const data = extractTraces();
+
+  const defined = readDefinedRequirements();
+  const allTraced = Object.keys(data.requirements);
+  data.defined = {
+    UR: defined.UR,
+    IR: defined.IR,
+    DR: defined.DR,
+    JA: defined.JA,
+    total: defined.total,
+  };
+  data.coverage = computeCoverage(allTraced, defined);
+
+  if (format === "json") {
+    console.log(generateJson(data));
+  } else if (format === "coverage") {
+    process.exit(reportCoverage(data, 50));
+  } else {
+    console.log(generateMarkdown(data));
+  }
+
+  console.error(
+    `\n✅ Complete! Found ${data.totalTraces} TRACES across ${data.totalFiles} files`
+  );
+}

scripts/generate-traceability-matrix.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Generate traceability matrix in Markdown format
+#
+
+echo "# Requirements Traceability Matrix"
+echo ""
+echo "**Generated**: $(date '+%Y-%m-%d %H:%M:%S')"
+echo ""
+echo "| Requirement | Files Implementing | Status | Notes |"
+echo "|-------------|--------------------|--------|-------|"
+
+requirements=$(grep -E "^\| (UR|IR|DR|JA)-[0-9]+" README.md | sed -E 's/^\| ([A-Z]+-[0-9]+).*/\1/' | sort -u)
+
+for req in $requirements; do
+    files=$(grep -rl "@req: $req" src-tauri/ src/ 2>/dev/null | \
+            sed 's|src-tauri/src/||; s|src/||' | \
+            paste -sd, -)
+
+    partial_files=$(grep -rl "@req-partial: $req" src-tauri/ src/ 2>/dev/null | wc -l)
+    planned=$(grep -rl "@req-planned: $req" src-tauri/ src/ 2>/dev/null | wc -l)
+
+    if [ -n "$files" ]; then
+        status="✅ Done"
+        notes=""
+    elif [ "$partial_files" -gt 0 ]; then
+        status="🔶 Partial"
+        notes="Platform-specific"
+    elif [ "$planned" -gt 0 ]; then
+        status="📋 Planned"
+        notes="Not implemented"
+    else
+        status="❌ Missing"
+        notes="No implementation"
+    fi
+
+    echo "| $req | ${files:-N/A} | $status | $notes |"
+done

scripts/logcat.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# View Android logcat output filtered for the app.
+#
+# Usage: ./scripts/logcat.sh [debug|release]   (default: debug)
+#
+# The debug build has applicationIdSuffix ".debug" so it can be installed
+# alongside a release build; pick the package to follow accordingly.
+
+set -e
+
+BUILD_TYPE="${1:-debug}"
+
+if [ "$BUILD_TYPE" = "release" ]; then
+    APP_PACKAGE="com.dtourolle.jellytau"
+else
+    APP_PACKAGE="com.dtourolle.jellytau.debug"
+fi
+
+echo "📱 Showing logcat for $APP_PACKAGE"
+echo "Press Ctrl+C to stop"
+echo ""
+
+# Prefer PID-scoped output when the app is running — it drops the noise that a
+# text grep can't. Fall back to the old keyword filter when it isn't (so you can
+# start the script first and then launch the app).
+PID="$(adb shell pidof "$APP_PACKAGE" 2>/dev/null | tr -d '\r\n' | awk '{print $1}')"
+
+if [ -n "$PID" ]; then
+    echo "   (attached to pid $PID)"
+    adb logcat --pid="$PID"
+else
+    echo "   (app not running — falling back to keyword filter)"
+    adb logcat | grep -i "$APP_PACKAGE\|jellytau\|tauri\|rust"
+fi

scripts/release-notes.ts

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

scripts/set-version.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# Stamp the release version into every file that carries it.
+#
+# The git tag is the single source of truth for a release version. The versions
+# committed in package.json / tauri.conf.json / Cargo.toml are a placeholder for
+# dev builds; a tagged build overwrites all of them from the tag so they cannot
+# disagree with each other or with the tag.
+#
+# Usage:
+#   ./scripts/set-version.sh 0.5.0        # explicit
+#   JELLYTAU_VERSION=0.5.0 ./scripts/set-version.sh
+#   ./scripts/set-version.sh              # derive from git describe (dev builds)
+#
+# Accepts the version with or without a leading "v".
+#
+# Why a script and not four sed lines in CI: the version lived in four files and
+# CI only ever rewrote one of them (tauri.conf.json), so a tagged release shipped
+# a matching installer name and mismatched package metadata. Keeping the write in
+# one place is what makes "the tag is authoritative" actually true.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+VERSION="${1:-${JELLYTAU_VERSION:-}}"
+
+# CI passes "${GITHUB_REF#refs/tags/}" unconditionally, which on an untagged
+# build is still a full ref ("refs/heads/master"). Treat anything that is not a
+# bare version as "no version given" and fall through to git describe, so a
+# branch build gets a sane dev version instead of failing the job.
+case "$VERSION" in
+  refs/*) VERSION="" ;;
+esac
+
+if [ -z "$VERSION" ]; then
+  # No explicit version: derive from the most recent tag. Dev builds land on
+  # something like 0.5.0 (exact tag) or 0.5.0-3-gabc1234 (ahead of the tag).
+  VERSION="$(git describe --tags --always --match 'v*' 2>/dev/null || echo "0.0.0")"
+fi
+
+# Tags are written v0.5.0; the files carry a bare semver.
+VERSION="${VERSION#v}"
+
+# Validate before writing anything — a malformed version silently propagated
+# into four files is far worse than a failed script.
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'; then
+  echo "❌ Not a valid semver: '$VERSION'" >&2
+  echo "   Expected MAJOR.MINOR.PATCH with an optional -prerelease/+build suffix." >&2
+  exit 1
+fi
+
+echo "📌 Setting version to $VERSION"
+
+# --- The three committed manifests -----------------------------------------
+# Anchored to the first "version" key so a dependency's version is never hit.
+
+# package.json — the top-level "version", which sits in the first few lines.
+perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' package.json
+
+# tauri.conf.json — likewise; this is the one the bundler reads for installer
+# names, and the one CI used to patch alone.
+perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' src-tauri/tauri.conf.json
+
+# Cargo.toml — only the [package] version, never a dependency's. Restricted to
+# the first occurrence of a line-anchored `version = "..."`.
+perl -0pi -e 's/^(version\s*=\s*)"[^"]*"/$1"'"$VERSION"'"/m' src-tauri/Cargo.toml
+
+# Cargo.lock — the jellytau entry. Left alone if the lock has not been generated
+# yet; the next cargo invocation writes it. Cargo would otherwise rewrite the
+# lock mid-build and dirty the tree.
+if [ -f src-tauri/Cargo.lock ]; then
+  perl -0pi -e 's/(name = "jellytau"\nversion = )"[^"]*"/$1"'"$VERSION"'"/' src-tauri/Cargo.lock
+fi
+
+# --- Android versionCode ----------------------------------------------------
+# Only when the generated Android project exists (i.e. after `tauri android
+# init`); on Linux/Windows jobs there is nothing to stamp.
+#
+# `tauri android init` derives a versionCode from the semver (0.0.15 -> 15).
+# That is both tiny and NOT monotonic across our history: earlier local/dev
+# builds shipped versionCode 1000 (from a 0.1.0 config), so a plain 15 is a
+# *downgrade* and Android refuses the update.
+#
+# The floor has to clear the highest code actually in the field, which is not the
+# same as the highest this formula has produced. v0.5.2 shipped versionCode
+# **5002** under an earlier `minor*1000` scheme; the `minor*100` formula that
+# replaced it yields only 1502 for that same version, and 1503 for 0.5.3 — so
+# every 0.5.x release built from it was an un-installable downgrade for anyone
+# already on v0.5.2, which is exactly the failure this block exists to prevent.
+# The multipliers are widened and the floor raised past 5002 accordingly.
+#
+#   code = 10000 + major*1000000 + minor*1000 + patch
+# e.g. 0.0.14 -> 10014, 0.1.0 -> 11000, 0.5.3 -> 15003, 1.0.0 -> 1010000.
+PROPS="src-tauri/gen/android/app/tauri.properties"
+if [ -f "$PROPS" ]; then
+  # Strip any -rc1/+build suffix first: it is not numeric, and feeding it to
+  # $(( )) would abort the script under `set -e`.
+  CORE="${VERSION%%-*}"
+  CORE="${CORE%%+*}"
+  MAJ=$(echo "$CORE" | cut -d. -f1)
+  MIN=$(echo "$CORE" | cut -d. -f2)
+  PAT=$(echo "$CORE" | cut -d. -f3)
+  : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
+  CODE=$(( 10000 + MAJ*1000000 + MIN*1000 + PAT ))
+  echo "   versionCode=$CODE (from $CORE)"
+  if grep -q '^tauri.android.versionCode=' "$PROPS"; then
+    sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
+  else
+    echo "tauri.android.versionCode=$CODE" >> "$PROPS"
+  fi
+fi
+
+# --- Report -----------------------------------------------------------------
+echo "✅ Version stamped:"
+grep -m1 '"version"' package.json | sed 's/^/   package.json:      /'
+grep -m1 '"version"' src-tauri/tauri.conf.json | sed 's/^/   tauri.conf.json:   /'
+grep -m1 '^version' src-tauri/Cargo.toml | sed 's/^/   Cargo.toml:        /'
+[ -f "$PROPS" ] && grep '^tauri.android.versionCode=' "$PROPS" | sed 's/^/   tauri.properties:  /'
+exit 0

scripts/set-version.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Guards for scripts/set-version.sh — the release version stamper.
+ *
+ * TRACES: DR-153 | UT-150
+ *
+ * These run the real script against a throwaway copy of the manifests, because
+ * the failure modes are all in the shell, not in any TS logic: a regex that also
+ * matches a dependency's version, arithmetic that aborts on a `-rc1` suffix, or
+ * a CI ref reaching the validator verbatim.
+ *
+ * The versionCode formula matters most. Android refuses an update whose code is
+ * lower than the installed one, and builds already in the field shipped code
+ * 1000 — so any formula that can emit a smaller number for a *newer* release
+ * bricks updates for those users, silently and irreversibly.
+ */
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const script = path.join(repoRoot, "scripts", "set-version.sh");
+
+let tmp: string;
+
+/** A minimal repo skeleton: just the files the script rewrites. */
+function seed(dir: string) {
+  fs.mkdirSync(path.join(dir, "src-tauri", "gen", "android", "app"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "scripts"), { recursive: true });
+  fs.copyFileSync(script, path.join(dir, "scripts", "set-version.sh"));
+  fs.chmodSync(path.join(dir, "scripts", "set-version.sh"), 0o755);
+
+  fs.writeFileSync(
+    path.join(dir, "package.json"),
+    JSON.stringify({ name: "jellytau", version: "0.0.1", dependencies: { hls: "1.2.3" } }, null, 2)
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "tauri.conf.json"),
+    JSON.stringify({ productName: "jellytau", version: "0.0.1" }, null, 2)
+  );
+  // A dependency carrying its own `version =` is the trap: a greedy regex
+  // rewrites it too and the build then resolves the wrong crate.
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "Cargo.toml"),
+    ['[package]', 'name = "jellytau"', 'version = "0.0.1"', '', '[dependencies]', 'serde = { version = "1.0.100" }', ''].join("\n")
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "Cargo.lock"),
+    ['[[package]]', 'name = "serde"', 'version = "1.0.100"', '', '[[package]]', 'name = "jellytau"', 'version = "0.0.1"', ''].join("\n")
+  );
+  fs.writeFileSync(
+    path.join(dir, "src-tauri", "gen", "android", "app", "tauri.properties"),
+    "tauri.android.versionCode=1\n"
+  );
+}
+
+function run(version: string, dir = tmp) {
+  return execFileSync("bash", [path.join(dir, "scripts", "set-version.sh"), version], {
+    cwd: dir,
+    encoding: "utf-8",
+  });
+}
+
+function read(rel: string): string {
+  return fs.readFileSync(path.join(tmp, rel), "utf-8");
+}
+
+function versionCode(): number {
+  const m = read("src-tauri/gen/android/app/tauri.properties").match(
+    /^tauri\.android\.versionCode=(\d+)$/m
+  );
+  return m ? Number(m[1]) : NaN;
+}
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "setversion-"));
+  seed(tmp);
+});
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("set-version.sh", () => {
+  it("stamps the version into all four manifests", () => {
+    run("0.5.0");
+    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
+    expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.5.0");
+    expect(read("src-tauri/Cargo.toml")).toContain('version = "0.5.0"');
+    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "jellytau"\nversion = "0\.5\.0"/);
+  });
+
+  it("accepts a leading v, as git tags are written", () => {
+    run("v0.5.0");
+    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
+  });
+
+  // The regression that motivates anchoring the patterns.
+  it("does not rewrite dependency versions", () => {
+    run("0.5.0");
+    expect(read("src-tauri/Cargo.toml")).toContain('serde = { version = "1.0.100" }');
+    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "serde"\nversion = "1\.0\.100"/);
+    expect(JSON.parse(read("package.json")).dependencies.hls).toBe("1.2.3");
+  });
+
+  describe("Android versionCode", () => {
+    // A newer release must never produce a smaller number than an older one, or
+    // Android refuses the update. The floor tracks the highest code actually in
+    // the field, which is NOT the same as the highest this formula has produced:
+    // v0.5.2 shipped versionCode 5002 from an earlier `minor*1000` scheme, while
+    // the `minor*100` formula that replaced it yields only 1502 for that same
+    // version — so every 0.5.x release built from it was an un-installable
+    // downgrade for anyone already on v0.5.2. The floor is raised to clear it.
+    it("clears the highest code shipped by earlier builds", () => {
+      run("0.0.1");
+      // v0.5.2 shipped 5002; anything at or below that cannot install over it.
+      expect(versionCode()).toBeGreaterThan(5002);
+    });
+
+    it("keeps 0.5.3 installable over the 5002 that shipped as v0.5.2", () => {
+      run("0.5.3");
+      expect(versionCode()).toBeGreaterThan(5002);
+    });
+
+    it("uses 10000 + major*1000000 + minor*1000 + patch", () => {
+      const cases: Array<[string, number]> = [
+        ["0.0.14", 10014],
+        ["0.0.15", 10015],
+        ["0.1.0", 11000],
+        ["0.4.8", 14008],
+        ["0.5.0", 15000],
+        ["0.5.3", 15003],
+        ["1.0.0", 1010000],
+      ];
+      for (const [version, code] of cases) {
+        seed(tmp);
+        run(version);
+        expect(versionCode(), `versionCode for ${version}`).toBe(code);
+      }
+    });
+
+    it("increases monotonically across an upgrade sequence", () => {
+      const ordered = ["0.0.14", "0.0.15", "0.1.0", "0.4.8", "0.5.0", "1.0.0"];
+      const codes = ordered.map((v) => {
+        seed(tmp);
+        run(v);
+        return versionCode();
+      });
+      const sorted = [...codes].sort((a, b) => a - b);
+      expect(codes).toEqual(sorted);
+      expect(new Set(codes).size).toBe(codes.length);
+    });
+
+    // `$(( 0-rc1 ))` aborts the script under `set -e`, so the suffix has to be
+    // stripped before the arithmetic.
+    it("derives the code from the numeric core of a prerelease", () => {
+      run("0.6.0-rc1");
+      expect(versionCode()).toBe(16000);
+      expect(JSON.parse(read("package.json")).version).toBe("0.6.0-rc1");
+    });
+  });
+
+  describe("input validation", () => {
+    it("rejects a malformed version without writing anything", () => {
+      expect(() => run("not-a-version")).toThrow();
+      // The manifests must be untouched, not half-written.
+      expect(JSON.parse(read("package.json")).version).toBe("0.0.1");
+      expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.0.1");
+    });
+
+    // CI passes "${GITHUB_REF#refs/tags/}" unconditionally; on a branch build
+    // that is still a full ref, and must not fail the job.
+    it("falls back to a dev version when handed a non-tag ref", () => {
+      const out = run("refs/heads/master");
+      expect(out).not.toMatch(/refs\/heads/);
+      expect(JSON.parse(read("package.json")).version).not.toBe("0.0.1");
+    });
+  });
+});