# Svelte Frontend Architecture

## Store Structure

Location: `src/lib/stores/`

    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:

    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.

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:

    <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

    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/`

    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. 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):

       #![allow(unused)]
       fn main() {
       // 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:

    #![allow(unused)]
    fn main() {
    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)`):

       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:

    #![allow(unused)]
    fn main() {
    #[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:

    #![allow(unused)]
    fn main() {
    // 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

    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):

    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:

    #![allow(unused)]
    fn main() {
    #[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:

    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

> ⚠️ Autoplay is season-bounded. `player/mod.rs:fetch_next_episode_for_item` does not cross a season boundary, so autoplay stops at the end of a season even though the "More Episodes" strip runs past it. 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) — its own change, not a drive-by.

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:

    #![allow(unused)]
    fn main() {
    // 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

    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:

    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`

## App Shell and Chrome

Location: `src/lib/utils/layoutShell.ts` (pure rules), `src/lib/components/AppHeader.svelte`, `src/lib/components/account/AccountMenu.svelte`, `BottomUi.svelte` TRACES: UR-054 | DR-075, DR-076, DR-077

Account actions used to be reachable only from `/library/*` — the header that hosted them belonged to the library layout, the bottom nav offered Home / Search / Library, and the desktop username was inert text. From `/`, `/search` or `/downloads` there was no route to Settings or Sign out at all. The header is now shared and rendered from the root layout.

### Visibility rules

All four rules are pure functions in `layoutShell.ts`, so the contract is unit-testable rather than a scattering of `$derived` booleans that drift per route and platform (which is what they were):

Function | Rule
--- | ---
`showBottomNav` | Every authenticated route except `/player/*` and `/login`
`showGlobalMiniPlayer` | Everything except `/player/*`, `/login`, `/settings`. Not gated on platform or `/library` — the root owns the mini player everywhere, so the library route must never render a second one
`routeOwnsLayout` | `/library`, `/player/`, `/login` render their own full-height flex column; everything else renders into the root scroller
`showGlobalHeader` | Authenticated, not a layout-owning route, not `/settings` (the user is already there)

### The structural fix worth not undoing

The "last row hidden behind the nav" bug is solved structurally, not by measurement: the bottom UI is an in-flow flex child below the scroller (`BottomUi.svelte`), so the scroller is physically bounded above it and cannot render behind it. There is no measurement and no reserved padding. If you restructure the shell, preserve the scroll containment — reintroducing padding math reintroduces the bug.

### AccountMenu

One component for both breakpoints, anchored to the username/avatar (a real button with `aria-expanded`, not a bare three-dot icon). Fixed item order: identity block (user + server) → Downloads, Settings, Display → divider → Sign out, destructive and last. Dismissal is backdrop click, `Escape`, and focus return to the trigger.

The identity block falls back to the bare host of the server URL when the server has no human-readable name, so it always shows something server-identifying.

Settings' Display section and the library page-header toggle are two views onto the same persisted `viewMode` store (`jellytau-view-mode`) — no second state, no migration, and they stay in sync for free.

## Library Mosaic

Location: `src/lib/components/library/libraryMosaic.ts` (pure), `MosaicGrid.svelte`, `MosaicTile.svelte` TRACES: UR-075, UR-067 | DR-174, DR-175

The library overview and the home "Your Libraries" strip are a mosaic, not a grid: rows share one height and each tile is as wide as its own artwork is, so 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 a grid picked.

`libraryMosaic.ts` is deliberately pure — it takes the libraries and returns the tiles to draw, so ordering and de-duplication are unit-testable rather than buried in markup. Tiles start at an assumed aspect (square, 16:9) and a measured image overrides it in `MosaicGrid`.

Note what this file does not decide: which favourites category a library belongs to. That is Jellyfin vocabulary and arrives on the library itself as `favoritesScope`, from `SearchScope::for_collection_type` in Rust (see 01-rust-backend.md). The frontend only decides what to call it and where to put it.

## Series and Episode Navigation

Location: `src/lib/components/library/` — `SeasonSection.svelte`, `EpisodeFocusView.svelte`, `episodeStrip.ts` (pure) TRACES: UR-062 … UR-064 | DR-101 … DR-107

Opening a series lands the viewer where they actually are in it. "Where is this viewer in this series" is resolved in Rust (DR-101), not by the page: the series detail page asks the repository and anchors on the answer — the current season expanded, the current episode highlighted and scrolled into view, and a hero button labelled `Resume S2E4` / `Play S1E1`.

A season is not a destination: `/library/<seasonId>` redirects to its series (DR-103). Video library routes collapse to one per library (DR-105).

`episodeStrip.ts` holds the pure logic for the "More Episodes" strip, extracted from the component because it had three distinct bugs that markup made untestable: the strip collapsing to just the current episode while real siblings existed, number-less episodes all matching as "current" (`undefined === undefined`), and the window dead-ending at a season boundary instead of running past it. It matches by id first and only falls back to season+episode number when both numbers are known on both sides.

## Downloaded Browse

Location: `src/lib/services/downloadedCatalog.ts`, `src/lib/components/downloads/DownloadedBrowse.svelte` TRACES: UR-055, UR-056 | DR-081 … DR-085

`/downloads` is two views: Downloaded (the default) — the library filtered to what is on the device, reusing the same grids, cards and detail pages as online browsing — and Transfers, the in-flight progress rows demoted to a secondary tab.

`downloadedCatalog` reads the offline-only browse path on the repository, never the hybrid merge. That is the point: an empty result means "nothing downloaded here", never "server unreachable", so the view is authoritative regardless of connectivity. It also owns disk usage — a per-item/container byte map plus the device total, aggregated by the backend from `downloads.file_size` (DR-085).

## Safe-area Insets

Location: `src/app.css`, `WindowInsetsBridge.kt` TRACES: UR-066 | DR-112, IR-031

The Android WebView does not reliably report system-bar insets through `env(safe-area-inset-*)`. Native `WindowInsets` (`systemBars() | displayCutout()`) are therefore pushed in as CSS custom properties, and every edge takes the larger of the two sources:

    --safe-top: max(env(safe-area-inset-top, 0px), var(--jt-inset-top, 0px));

Two rules keep this from going wrong: one owner per edge (two components both padding the top edge double-pads it), and no nested `h-screen` — a full-height child inside a full-height parent that has already consumed the inset overflows by exactly the inset.

Unlike `addJavascriptInterface`, the inset push only writes CSS properties, so it can safely be re-sent on resume.

## Stream Transport

Location: `src/lib/player/streamTransport.ts` TRACES: UR-079 | DR-225 | UT-214

`videoLoaderFor(selection, capabilities)` picks the loader for the webview `<video>` element — `hlsjs`, `nativeHls`, or `direct` — from the backend's tagged `selection.transport`. `elementSrcFor` is its template companion: the element's `src` is emptied only when hls.js is driving it.

The split is the point. The transport is the stream's property and comes from Rust; whether a given loader exists is the browser's, and is the only thing decided here.

> This replaced `currentStreamUrl.includes(".m3u8")`, which appeared twice in `VideoPlayer.svelte` — once in the HLS `$effect` and once inline in the template's `src`. Rust builds that URL and knows what it is; re-deriving it here by substring match was a domain fact reconstructed in the presentation layer, and it fails silently in both directions. The two tests that pin it are the ones that failed against the old implementation: a `progressive` stream whose URL contains `.m3u8` must not get an HLS loader, and an `hls` stream whose URL contains no `.m3u8` must.

> Logic lives in a plain `.ts` module rather than in the component for the usual reason — it is testable there. Same pattern as `episodeStrip.ts`.

`VideoPlayer` holds a `currentSelection`, not a URL string; `currentStreamUrl` is derived from it. A reload replaces the selection wholesale (the adapter's bridge takes a `StreamSelection`, not a URL), so transport and URL can never drift apart. The background-audio handoff states the transport it is moving to — progressive mp3 out, HLS back — via `selectionAt()`, rather than leaving it to be inferred.

The quality picker is filled from `selection.available` (DR-227): rungs the backend marked `exceedsSource` are not drawn, because they produce the same bytes as `Original`. Nothing is optimistically assigned when the viewer picks a rung — what the menu shows comes from the selection the backend hands back, since a ceiling above the source bitrate is the source.

## Native Video Store

Location: `src/lib/stores/nativeVideo.ts` TRACES: UR-003, UR-004 | DR-188

Two separate concerns live here, deliberately:

- `experimentalNativeVideo` — the user-facing opt-in flag, defaulting to on. Rust already decides which backend this platform has (`useHtml5Element` from `player_play_item`); this flag only suppresses that decision. It never turns native on where Rust says HTML5. An explicit stored choice wins in both directions, so someone who opted out is not re-enabled by a default flip — hence the `null` check rather than a bare `=== "true"`.
- `nativeVideoActive` — whether a native surface is on screen right now. Setting it toggles `data-native-video` on `<html>`, which is what the CSS in `app.css` keys off to clear the app's opaque backgrounds. It is deliberately not derived from the flag: the backgrounds must come back the moment the player unmounts.

See 05-platform-backends.md for what is behind the WebView.

## Logging

Location: `src/lib/utils/logger.ts` TRACES: DR-204

The frontend's equivalent of the Rust `log` crate: four levels (`debug < info < warn < error`), a compile-environment default (dev → `debug`, production → `warn`), and a runtime override that is the moral equivalent of `RUST_LOG`. Scoped loggers carry the subsystem in the message, so a filtered console stays usable while a player, a download worker and a store are all talking.

Production deliberately keeps warn and error: this is a client talking to a server that may or may not be there, and a silent failure is worse to support than a noisy console. Only the chatter is suppressed.

`no-console` is an ESLint error, with the sink module itself the only exception, so a raw `console.*` cannot re-appear.