Updated readme

Cargo.lock

@@ -1938,7 +1938,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
 
 [[package]]
 name = "furumusic"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "anyhow",
  "async-stream",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "furumusic"
-version = "0.10.1"
+version = "0.10.2"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 

README.md

@@ -1,208 +1,143 @@
-# furumusic
+# Furumusic
 
-Furumusic can join the decentralized Furumi federation while remaining a
-complete local web player. Optional similarity search stores versioned audio
-embeddings in PostgreSQL and uses signed two-level LSH summaries in a separate
-DHT to discover compatible peers without a central recommendation index. The
-shared `music-dht` layer owns routing and wire compatibility; model inference
-and exact cosine ranking stay local to each instance.
+**Your library. Your users. Your network.**
 
-Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL.
+Furumusic is a self-hosted, multi-user music server with a full web player and
+support for the Furumi federated network. It turns a collection of music files
+into a shared library that is available from any modern browser, while every
+user keeps their own playlists, likes, listening history, and playback state.
 
-Built with Rust ([cot](https://cot.rs) framework).
+Music can be uploaded directly, imported from a `.torrent` file, or downloaded
+from a magnet link. An optional AI-assisted import pipeline reads the available
+tags and path information, reconstructs inconsistent metadata, finds artwork,
+and organizes the result into artists, releases, and tracks. Uncertain matches
+are kept for review instead of silently entering the library with bad data.
 
-## Quick start
+## Why Furumusic?
+
+Furumusic is for a household, a small community, or anyone who wants one music
+library without handing it to a subscription service. The server owns the
+catalog and media files; the browser is only the player.
+
+- one shared library with separate user accounts;
+- a responsive web player with artists, releases, search, queue, and playlists;
+- direct file uploads and torrent or magnet imports;
+- optional AI-assisted recognition and normalization of metadata;
+- password login or OIDC/SSO with group-based access control;
+- optional federation without a central catalog or search service;
+- trusted-device pairing, playback handoff, and synchronization between Furumi
+  players;
+- Last.fm scrobbling and similarity-based discovery when configured.
+
+Furumusic does not include music. Import only media you are allowed to store and
+share.
+
+## Importing music
+
+Users can add audio files from the web interface or ask the server to download
+selected files from a torrent. Both routes feed the same import pipeline, so a
+library remains consistent regardless of where its files came from.
+
+The importer combines embedded tags, filenames, folder structure, and existing
+catalog context. With an OpenAI-compatible language model configured, it can
+normalize artist and release names, separate featured artists, recover track
+numbers and release types, and flag ambiguous results for a user to approve.
+Cover art is taken from nearby image files or embedded artwork when available.
+
+The inbox and permanent library are separate directories. New files are first
+processed in the inbox and are moved into the organized library only after
+their metadata has been accepted.
+
+## Federation
+
+Federation is optional. Independent Furumusic and Furumi players that use the
+same Network ID discover one another as a logical network. Each peer keeps its
+own library and can continue working alone.
+
+When federation is enabled, local and remote artists, releases, and tracks can
+appear in the same search and library views. Missing audio is streamed from an
+available peer and can optionally be retained locally. Similarity search also
+stays decentralized: embeddings and exact ranking remain on the instance that
+owns the music.
+
+Trusted-device pairing is separate from public catalog discovery. It connects
+a user's own Furumi players so likes, playlists, playback state, and control can
+move between approved devices.
+
+## Build and run
+
+Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition
+support. Create an empty database, provide its connection URL, and start the
+server:
 
 ```bash
-export FURU_DATABASE_URL=postgresql://user:pass@localhost/furumusic
-cargo run
-# Open http://localhost:8000/admin/setup to create the first admin account
+export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic'
+cargo run --release --locked
 ```
 
-## Project structure
+Open <http://127.0.0.1:8000/admin/setup> to create the first administrator.
+After setup, configure the inbox and library directories under **Admin →
+Settings** before importing music.
 
+To listen on another address or port:
+
+```bash
+cargo run --release --locked -- -l 0.0.0.0:8000
 ```
-Cargo.toml                  Project manifest and dependencies
-build.rs                    Captures rustc version + target at compile time
-src/
-  main.rs                   Entrypoint; HTTP router, login/logout handlers, tracing init
-  config.rs                 3-tier config system (default → DB → env); FURU_* env vars
-  auth.rs                   Session auth, Role enum (Admin/User), login/logout/guards
-  user.rs                   User + OidcLink DB models, CRUD, password hashing, migrations
-  oidc.rs                   OIDC/SSO flow: discovery, PKCE, token exchange, user provisioning
-  i18n/
-    mod.rs                  Language resolution (cookie → Accept-Language → default), extractor
-    phrases.rs              All UI strings in English and Russian (translations! macro)
-  api/
-    mod.rs                  JSON API endpoints (mounted at /api), session-based auth
-  admin/
-    mod.rs                  Admin sub-app router: dashboard, settings, users, debug, setup
-    views.rs                Admin page handlers and templates
-templates/
-  base.html                 Root HTML layout with lang/title blocks
-  login.html                Login page (password + optional SSO button)
-  admin/
-    layout.html             Admin sidebar/nav wrapper
-    index.html              Admin dashboard
-    debug.html              Build info + config table (with secret redaction)
-    settings.html           OIDC and auth settings form
-    setup.html              First-run admin account creation
-    users.html              User list
-    user_form.html          User create/edit form
+
+A Nix development shell is included for Linux and macOS:
+
+```bash
+nix develop
+cargo run --locked
 ```
 
+The repository also contains a multi-stage `Dockerfile` for building a small
+runtime image. A deployment must provide PostgreSQL plus persistent, writable
+volumes for the inbox and music library.
+
+## Configuration
+
+Most settings can be changed from the administration interface. Every setting
+also has a `FURU_`-prefixed environment variable; environment values take
+priority over values stored in PostgreSQL.
+
+The settings needed for a useful first installation are:
+
+| Setting | Purpose |
+| --- | --- |
+| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service |
+| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files |
+| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library |
+| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline |
+| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server |
+| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata |
+| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery |
+| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network |
+
+AI recognition, federation, similarity search, Last.fm, and OIDC are optional.
+A local password-authenticated server can be used without any of them.
+
 ## Architecture
 
-### Config system (`src/config.rs`)
+Furumusic is written in Rust on the
+[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts,
+playlists, configuration, and background-job state. Audio inspection uses
+Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid
+protocol stack provides decentralized catalog search, media transfer, and
+connected-device synchronization.
 
-Every setting lives in `AppConfig` and is resolved in three layers:
+The browser interface and JSON API are served by the same application. Import,
+artwork, metadata enrichment, similarity indexing, and maintenance run as
+durable background jobs rather than blocking playback requests.
 
-1. **Compiled default** — `AppConfig::default()`
-2. **Database override** — rows in the `furumusic__config_entry` table
-3. **Environment variable** — `FURU_<FIELD_NAME>` (highest priority)
+## Contributing
 
-`ConfigSources` tracks where each field's effective value came from (shown in the admin debug page).
+Bug reports, design discussions, and patches are welcome. Before submitting a
+change, run:
 
-**To add a new config field:**
-
-1. Add the field to `AppConfig` struct
-2. Set its default in `AppConfig::default()`
-3. Add the field to `ConfigSources` struct and its `Default` impl
-4. Add it to the `impl_env_overrides!(…)` invocation
-5. Add an `apply_db_field!()` call in `apply_db_overrides`
-6. Add an `entry!()` line in `admin/views.rs → config_display_entries()`
-
-### Auth (`src/auth.rs`)
-
-Session-based authentication with two roles:
-
-- **`Role::Admin`** — full access to admin panel
-- **`Role::User`** — standard user
-
-Key functions:
-- `login(session, user_id)` — sets session, cycles session ID
-- `logout(session)` — flushes session
-- `get_session_user(session, db)` — returns `AuthenticatedUser` if active
-- `require_admin_or_redirect(session, db)` — guard that returns 403 or redirects to `/login`
-
-### OIDC/SSO (`src/oidc.rs`)
-
-Full OpenID Connect authorization code flow with PKCE:
-
-1. `GET /auth/oidc/start` — discovers provider, builds auth URL, stores CSRF/nonce/PKCE in session, redirects to IdP
-2. `GET /auth/oidc/callback` — validates CSRF, exchanges code for tokens, verifies ID token, provisions user
-
-Provider metadata is cached for 1 hour and invalidated when OIDC config changes.
-
-**Group access and role mapping:** The `oidc_user_groups` config field lists OIDC group names (comma-separated) allowed to access the service. When it is set, users outside both `oidc_user_groups` and `oidc_admin_groups` are denied before provisioning/login. The `oidc_admin_groups` config field lists OIDC group names that grant the admin role. Groups are extracted from the `groups` claim in the ID token JWT payload.
-
-**User provisioning order:**
-1. Find existing `OidcLink` by issuer+sub → update claims, update role
-2. Find existing `User` by email → create OidcLink, update role
-3. Create new user (no password) + OidcLink
-
-Stale links (pointing to deleted users) are cleaned up automatically.
-
-### User model (`src/user.rs`)
-
-Two database models:
-
-- **`User`** — id, username (unique), password (optional for OIDC-only), email, display_name, avatar_url, role, is_active
-- **`OidcLink`** — id, user_id, issuer, sub, email, name, avatar_url; unique index on (issuer, sub)
-
-Migrations: M0003 (User table), M0004 (OidcLink table), M0005 (OidcLink indexes).
-
-### i18n (`src/i18n/`)
-
-Compile-time bilingual UI (English + Russian).
-
-- `translations!` macro in `phrases.rs` generates a `Translations` struct with static `EN` and `RU` instances
-- Language resolution: `furu_lang` cookie → `Accept-Language` header → English default
-- `I18n` is a cot request extractor — handlers receive it automatically
-- `set_lang` endpoint (`/set-lang?lang=ru&next=/`) sets the cookie
-
-### API (`src/api/`)
-
-JSON API mounted at `/api`. Uses the same session cookie as HTML pages — works automatically for same-origin frontend requests (no CORS, no tokens needed).
-
-Helpers in `api/mod.rs`:
-- `json_ok(value)` — 200 with `application/json`
-- `json_error(status, message)` — error response as `{"error": "..."}`
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/api/me` | GET | Current user (id, name, role) or 401 |
-
-**Swagger UI** is available at `/swagger/` when `FURU_SWAGGER_ENABLED=true`. The OpenAPI spec is auto-generated from handler types.
-
-To add a new API endpoint:
-1. Define request/response structs with `#[derive(Serialize, JsonSchema)]`
-2. Write an async handler, return `Json(response).into_response()`
-3. Add a `Route::with_api_handler_and_name(…, api_get(handler), …)` in `ApiApp::router()`
-4. The endpoint appears automatically in Swagger UI
-
-### Admin panel (`src/admin/`)
-
-Mounted at `/admin`. All routes (except `/admin/setup`) require `Role::Admin`.
-
-| Route | Purpose |
-|-------|---------|
-| `/admin/setup` | First-run: create initial admin (only works when zero users exist) |
-| `/admin/` | Dashboard |
-| `/admin/debug` | Build info, config values with sources, DB connectivity |
-| `/admin/settings` | OIDC config, auth toggles (saved to DB config table) |
-| `/admin/users` | User list |
-| `/admin/users/new` | Create user |
-| `/admin/users/{id}/edit` | Edit user |
-| `/admin/users/{id}/delete` | Delete user (POST) |
-
-## How to extend
-
-### 1. Add a config field
-
-See [Config system](#config-system-srcconfigrs) above — 6 locations to update.
-
-### 2. Add a database model
-
-1. Define a struct with `#[cot::db::model]` in a new or existing file
-2. Write a migration struct implementing `cot::db::migrations::Migration`
-3. Register the migration in the `AdminApp::migrations()` method in `src/admin/mod.rs`
-
-### 3. Add a page
-
-1. Create a template in `templates/`
-2. Write a handler function that returns `Html`
-3. Add a `Route::with_handler_and_name(…)` in the appropriate `router()` method
-4. If admin-only, wrap with `require_admin_or_redirect`
-
-### 4. Add a translation
-
-Add a line to the `translations!` macro in `src/i18n/phrases.rs`:
-
-```rust
-my_key: "English text", "Русский текст";
+```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
+cargo test --all-targets
 ```
-
-Access it in handlers/templates as `i18n.t.my_key` (or `t.my_key` in templates).
-
-### 5. Add an API endpoint
-
-Same as adding a page, but return a JSON response instead of `Html`. The `json` feature is enabled in Cargo.toml.
-
-## Environment variables
-
-All prefixed with `FURU_`. Priority: env var > DB override > compiled default.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `FURU_DATABASE_URL` | PostgreSQL connection URL | *(empty — required)* |
-| `FURU_LOG_LEVEL` | Tracing filter (e.g. `info`, `debug`, `warn,furumusic=trace`) | `info` |
-| `FURU_AUTH_PASSWORD_ENABLED` | Enable password login | `true` |
-| `FURU_AUTH_SSO_ENABLED` | Enable SSO/OIDC login | `false` |
-| `FURU_OIDC_ISSUER` | OIDC issuer URL | *(empty)* |
-| `FURU_OIDC_CLIENT_ID` | OIDC client ID | *(empty)* |
-| `FURU_OIDC_CLIENT_SECRET` | OIDC client secret | *(empty)* |
-| `FURU_OIDC_BUTTON_TEXT` | SSO button label | `Sign in with SSO` |
-| `FURU_OIDC_ADMIN_GROUPS` | Comma-separated OIDC groups that grant admin | *(empty)* |
-| `FURU_OIDC_USER_GROUPS` | Comma-separated OIDC groups allowed to access the service. Empty means any authenticated SSO user is allowed. | *(empty)* |
-| `FURU_SWAGGER_ENABLED` | Serve Swagger UI at `/swagger/` | `false` |

src/federation/client.rs

@@ -85,6 +85,8 @@ pub struct TrackDto {
     pub key: TrackKeyDto,
     pub metadata: TrackMetadataDto,
     pub availability: TrackAvailabilityDto,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub similarity_score: Option<f32>,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -151,6 +153,7 @@ impl Federation {
                     local: None,
                     federation: vec![FederationSourceDto { owner, item_id }],
                 },
+                similarity_score: Some(track.similarity_score),
             };
             persist_track_ref(&pool, &dto).await?;
             prepared.push(dto);
@@ -491,6 +494,7 @@ fn track_from_item(
             local,
             federation: vec![FederationSourceDto { owner, item_id }],
         },
+        similarity_score: None,
     }
 }
 

src/federation/mod.rs

@@ -213,6 +213,50 @@ impl TransportStats {
     }
 }
 
+async fn enrich_transport_users(pool: &PgPool, transport: &mut Value) {
+    let Some(samples) = transport.get_mut("last").and_then(Value::as_array_mut) else {
+        return;
+    };
+    let peer_ids: Vec<String> = samples
+        .iter()
+        .filter_map(|sample| sample.get("peer_id").and_then(Value::as_str))
+        .map(str::to_owned)
+        .collect();
+    if peer_ids.is_empty() {
+        return;
+    }
+    let Ok(rows) = sqlx::query(
+        "SELECT DISTINCT ON (d.endpoint_id)
+                d.endpoint_id,
+                COALESCE(NULLIF(u.display_name, ''), u.username::text) AS user_name
+         FROM furumusic__fed_device d
+         JOIN furumusic__user u ON u.id = d.user_id
+         WHERE d.endpoint_id = ANY($1) AND d.revoked_at_ms IS NULL
+         ORDER BY d.endpoint_id, d.last_seen_ms DESC NULLS LAST",
+    )
+    .bind(&peer_ids)
+    .fetch_all(pool)
+    .await
+    else {
+        return;
+    };
+    let users: HashMap<String, String> = rows
+        .into_iter()
+        .map(|row| (row.get("endpoint_id"), row.get("user_name")))
+        .collect();
+    for sample in samples {
+        let Some(peer_id) = sample.get("peer_id").and_then(Value::as_str) else {
+            continue;
+        };
+        let Some(user_name) = users.get(peer_id) else {
+            continue;
+        };
+        if let Some(object) = sample.as_object_mut() {
+            object.insert("user_name".to_owned(), Value::String(user_name.clone()));
+        }
+    }
+}
+
 pub fn record_stream_transport(
     stats: &Arc<TransportStats>,
     protocol: &'static str,
@@ -849,6 +893,10 @@ impl Federation {
                     .iter()
                     .map(|p| p.to_string())
                     .collect();
+                let mut transport = self.transport_stats.snapshot();
+                if let Ok(pool) = self.pool().await {
+                    enrich_transport_users(&pool, &mut transport).await;
+                }
                 json!({
                     "running": true,
                     "network": running.network_name,
@@ -857,7 +905,7 @@ impl Federation {
                     "known_contacts": service.known_peers().len(),
                     "similarity_routing_peers": running.similarity_dht.known_peers(),
                     "published_items": published,
-                    "transport": self.transport_stats.snapshot(),
+                    "transport": transport,
                 })
             }
             None => json!({ "running": false }),
@@ -895,7 +943,7 @@ impl Federation {
         &self,
         query: crate::similarity::QueryVector,
         limit: usize,
-    ) -> Result<Vec<similarity::RemoteSimilarityTrack>> {
+    ) -> Result<similarity::SimilaritySearchOutcome> {
         anyhow::ensure!(
             crate::similarity::handle().enabled(),
             "similarity search is disabled"

src/federation/similarity.rs

@@ -39,6 +39,12 @@ pub struct RemoteSimilarityTrack {
     pub release_title: Option<String>,
     pub track_number: Option<i32>,
     pub disc_number: Option<i32>,
+    pub similarity_score: f32,
+}
+
+pub struct SimilaritySearchOutcome {
+    pub tracks: Vec<RemoteSimilarityTrack>,
+    pub queried_peers: usize,
 }
 
 pub async fn serve_peers(
@@ -151,7 +157,7 @@ pub async fn search(
     query: QueryVector,
     limit: usize,
     transport: Arc<TransportStats>,
-) -> Result<Vec<RemoteSimilarityTrack>> {
+) -> Result<SimilaritySearchOutcome> {
     let own = service.endpoint_id();
     let routed = match tokio::time::timeout(
         ROUTING_TIMEOUT,
@@ -204,6 +210,7 @@ pub async fn search(
 
     let mut hits = Vec::new();
     let initial = peers.len().min(INITIAL_QUERY_PEERS);
+    let mut queried_peers = initial;
     let responses = query_peers(
         Arc::clone(&service),
         &peers[..initial],
@@ -222,6 +229,7 @@ pub async fn search(
         }
     }
     if initial < peers.len() && (hits.len() < limit || successful < initial.min(4)) {
+        queried_peers += peers.len() - initial;
         for response in query_peers(
             Arc::clone(&service),
             &peers[initial..],
@@ -282,7 +290,10 @@ pub async fn search(
             break;
         }
     }
-    Ok(tracks)
+    Ok(SimilaritySearchOutcome {
+        tracks,
+        queried_peers,
+    })
 }
 
 type PeerHits = Vec<(
@@ -360,6 +371,7 @@ async fn query_peer(
                     release_title: hit.release_title,
                     track_number: hit.track_number,
                     disc_number: hit.disc_number,
+                    similarity_score: score,
                 },
                 score,
                 signature,

src/i18n/phrases.rs

@@ -96,9 +96,9 @@ translations! {
     settings_swagger:         "Swagger UI"                    , "Swagger UI";
     settings_swagger_help:    "Serves interactive API docs at /swagger/ (requires restart)" , "Интерактивная документация API на /swagger/ (требуется перезапуск)";
     settings_lastfm_api_key:  "Last.fm API key"               , "API ключ Last.fm";
-    settings_lastfm_api_key_help: "Used for Last.fm popularity and account connection" , "Используется для популярности Last.fm и подключения аккаунта";
+    settings_lastfm_api_key_help: "Identifies this application to Last.fm and enables metadata, popularity data, and user account connection" , "Идентифицирует приложение в Last.fm и включает метаданные, данные о популярности и подключение аккаунтов";
     settings_lastfm_shared_secret: "Last.fm shared secret"    , "Shared secret Last.fm";
-    settings_lastfm_shared_secret_help: "Required for signed Last.fm scrobbling requests" , "Нужен для подписанных запросов скробблинга Last.fm";
+    settings_lastfm_shared_secret_help: "Authenticates signed Last.fm requests, including scrobbling. Keep this value private" , "Подтверждает подписанные запросы Last.fm, включая скробблинг. Не раскрывайте это значение";
 
     // OIDC login errors
     login_oidc_error:         "SSO login failed. Please try again." , "Ошибка входа через SSO. Попробуйте ещё раз.";

src/player/mod.rs

@@ -14,7 +14,7 @@ use cot::router::method::{delete, get, post};
 use cot::router::{Route, Router};
 use cot::session::Session;
 use cot::{App, Body, Template};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use sqlx::Row as _;
 
 use crate::auth;
@@ -4318,9 +4318,25 @@ async fn load_track_items_by_ids(pool: &sqlx::PgPool, ids: &[i64]) -> cot::Resul
 #[derive(Debug, Serialize)]
 struct SimilaritySearchResponse {
     label: String,
-    tracks: Vec<TrackItem>,
+    tracks: Vec<ScoredSimilarityTrack>,
     federation_tracks: Vec<crate::federation::client::TrackDto>,
     federation_error: Option<String>,
+    queried_peers: usize,
+    elapsed_ms: u64,
+    complete: bool,
+}
+
+#[derive(Debug, Serialize)]
+struct ScoredSimilarityTrack {
+    #[serde(flatten)]
+    track: TrackItem,
+    similarity_score: f32,
+}
+
+#[derive(Debug, Deserialize)]
+struct SimilaritySearchQuery {
+    #[serde(default)]
+    local_only: bool,
 }
 
 async fn similarity_search_handler(
@@ -4329,7 +4345,9 @@ async fn similarity_search_handler(
     db: Database,
     pool: &sqlx::PgPool,
     Path(path): Path<PathId>,
+    options: cot::request::extractors::UrlQuery<SimilaritySearchQuery>,
 ) -> cot::Result<cot::response::Response> {
+    let started = std::time::Instant::now();
     let Some(_user) = auth::get_request_user(&auth_ctx, &session, &db).await else {
         return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
     };
@@ -4385,28 +4403,48 @@ async fn similarity_search_handler(
         .iter()
         .map(|track| track.track_id)
         .collect::<Vec<_>>();
-    let mut tracks = Vec::with_capacity(ids.len() + 1);
-    tracks.push(source_track.clone());
-    tracks.extend(load_track_items_by_ids(pool, &ids).await?);
+    let scores: HashMap<i64, f32> = ranked
+        .iter()
+        .map(|track| (track.track_id, track.score))
+        .collect();
+    let mut local_tracks = Vec::with_capacity(ids.len() + 1);
+    local_tracks.push(source_track.clone());
+    local_tracks.extend(load_track_items_by_ids(pool, &ids).await?);
+    let tracks = local_tracks
+        .into_iter()
+        .map(|track| ScoredSimilarityTrack {
+            similarity_score: if track.id == path.id {
+                1.0
+            } else {
+                scores.get(&track.id).copied().unwrap_or_default()
+            },
+            track,
+        })
+        .collect();
 
     let (config, _) = AppConfig::load_with_db(&db).await;
-    let (federation_tracks, federation_error) = if config.federation_enabled {
-        match crate::federation::handle()
-            .search_similarity(query, 50)
-            .await
-        {
-            Ok(remote) => match crate::federation::handle()
-                .prepare_similarity_tracks(remote)
+    let (federation_tracks, federation_error, queried_peers) =
+        if config.federation_enabled && !options.0.local_only {
+            match crate::federation::handle()
+                .search_similarity(query, 50)
                 .await
             {
-                Ok(tracks) => (tracks, None),
-                Err(error) => (Vec::new(), Some(format!("{error:#}"))),
-            },
-            Err(error) => (Vec::new(), Some(format!("{error:#}"))),
-        }
-    } else {
-        (Vec::new(), None)
-    };
+                Ok(outcome) => match crate::federation::handle()
+                    .prepare_similarity_tracks(outcome.tracks)
+                    .await
+                {
+                    Ok(tracks) => (tracks, None, outcome.queried_peers),
+                    Err(error) => (
+                        Vec::new(),
+                        Some(format!("{error:#}")),
+                        outcome.queried_peers,
+                    ),
+                },
+                Err(error) => (Vec::new(), Some(format!("{error:#}")), 0),
+            }
+        } else {
+            (Vec::new(), None, 0)
+        };
     let artists = source_track
         .artists
         .iter()
@@ -4423,6 +4461,9 @@ async fn similarity_search_handler(
         tracks,
         federation_tracks,
         federation_error,
+        queried_peers,
+        elapsed_ms: started.elapsed().as_millis() as u64,
+        complete: !options.0.local_only,
     })
     .into_response()
 }
@@ -9934,7 +9975,8 @@ impl App for PlayerApp {
                     move |auth_ctx: auth::AuthContext,
                           session: Session,
                           db: Database,
-                          path: Path<PathId>| {
+                          path: Path<PathId>,
+                          query: cot::request::extractors::UrlQuery<SimilaritySearchQuery>| {
                         let pool = Arc::clone(&pool);
                         let pool_config = Arc::clone(&pool_config);
                         async move {
@@ -9947,7 +9989,7 @@ impl App for PlayerApp {
                                         .expect("player pool")
                                 })
                                 .await;
-                            similarity_search_handler(auth_ctx, session, db, pg_pool, path).await
+                            similarity_search_handler(auth_ctx, session, db, pg_pool, path, query).await
                         }
                     }
                 }),

src/similarity.rs

@@ -244,10 +244,61 @@ impl Manager {
                 return;
             }
         };
+        let mut effective = config.clone();
+        let mut rows = None;
+        for attempt in 0..20 {
+            match sqlx::query(
+                "SELECT key, value FROM furumusic__config_entry
+                 WHERE key IN ('similarity_enabled', 'similarity_model',
+                               'similarity_profile', 'similarity_workers',
+                               'agent_storage_dir')",
+            )
+            .fetch_all(&pool)
+            .await
+            {
+                Ok(loaded) => {
+                    rows = Some(loaded);
+                    break;
+                }
+                Err(error) if attempt < 19 => {
+                    tracing::debug!(attempt, %error, "similarity boot: settings table not ready");
+                    tokio::time::sleep(Duration::from_millis(500)).await;
+                }
+                Err(error) => {
+                    tracing::warn!(%error, "similarity boot: database settings unavailable");
+                }
+            }
+        }
+        for row in rows.unwrap_or_default() {
+            let key: String = row.get(0);
+            let value: String = row.get(1);
+            let env_key = format!("FURU_{}", key.to_ascii_uppercase());
+            if std::env::var(&env_key).is_ok() {
+                continue;
+            }
+            match key.as_str() {
+                "similarity_enabled" => {
+                    if let Ok(parsed) = value.parse() {
+                        effective.similarity_enabled = parsed;
+                    }
+                }
+                "similarity_model" => effective.similarity_model = value,
+                "similarity_profile" => effective.similarity_profile = value,
+                "similarity_workers" => {
+                    if let Ok(parsed) = value.parse() {
+                        effective.similarity_workers = parsed;
+                    }
+                }
+                "agent_storage_dir" => {
+                    effective.agent_storage_dir = crate::media_paths::resolve_config_path(&value);
+                }
+                _ => {}
+            }
+        }
         if let Err(error) = self.restore_stored_status(&pool).await {
             tracing::warn!(%error, "similarity boot: stored status unavailable");
         }
-        self.apply(config);
+        self.apply(&effective);
     }
 
     pub fn apply(self: &Arc<Self>, config: &AppConfig) {

templates/admin/v2.html

@@ -806,35 +806,68 @@ tbody tr:hover {
 }
 
 .settings-page {
-    max-width: none;
+    max-width: 1440px;
+    margin: 0 auto;
 }
 
 .settings-layout {
     display: grid;
-    grid-template-columns: minmax(620px, 1fr) minmax(360px, 440px);
-    gap: 14px;
-    align-items: start;
+    grid-template-columns: repeat(12, minmax(0, 1fr));
+    grid-template-areas:
+        "access access access access oidc oidc oidc oidc oidc oidc oidc oidc"
+        "agent agent agent agent agent agent agent agent agentstatus agentstatus agentstatus agentstatus"
+        "similarity similarity similarity similarity similarity similarity similarity similarity similaritystatus similaritystatus similaritystatus similaritystatus"
+        "federation federation federation federation federation federation federation federation federation federation federation federation"
+        "lastfm lastfm lastfm lastfm lastfm lastfm lastfm lastfm developer developer developer developer"
+        "actions actions actions actions actions actions actions actions actions actions actions actions";
+    gap: 16px;
+    align-items: stretch;
 }
 
 .settings-column {
-    display: grid;
-    gap: 14px;
-    align-content: start;
+    display: contents;
 }
 
-.settings-side .settings-grid {
+.settings-section {
+    min-width: 0;
+    margin: 0;
+}
+.settings-access { grid-area: access; }
+.settings-oidc { grid-area: oidc; }
+.settings-agent { grid-area: agent; }
+.settings-agent-status { grid-area: agentstatus; }
+.settings-similarity { grid-area: similarity; }
+.settings-similarity-status { grid-area: similaritystatus; }
+.settings-federation { grid-area: federation; }
+.settings-lastfm { grid-area: lastfm; }
+.settings-developer { grid-area: developer; }
+.settings-section-narrow { border-left: 2px solid rgba(29, 185, 84, 0.55); }
+
+.settings-access .settings-grid,
+.settings-developer .settings-grid {
     grid-template-columns: minmax(0, 1fr);
 }
 
+.settings-section-narrow .panel-head {
+    background: rgba(29, 185, 84, 0.035);
+}
+
 .settings-actions {
-    grid-column: 1 / -1;
+    grid-area: actions;
+    position: sticky;
+    bottom: 0;
+    z-index: 5;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    background: rgba(35, 35, 35, 0.96);
+    backdrop-filter: blur(10px);
 }
 
 .settings-grid {
     display: grid;
     grid-template-columns: repeat(2, minmax(0, 1fr));
-    gap: 10px;
-    padding: 14px;
+    gap: 14px 16px;
+    padding: 16px;
 }
 
 .settings-card {
@@ -843,22 +876,26 @@ tbody tr:hover {
 
 .setting-field {
     min-width: 0;
+    max-width: 480px;
 }
 
+.setting-field.settings-short { max-width: 150px; }
+.settings-wide { max-width: 680px; }
+
 .setting-field label,
 .setting-toggle label {
     display: flex;
     align-items: center;
     justify-content: space-between;
     gap: 8px;
-    margin-bottom: 6px;
+    margin-bottom: 7px;
     color: var(--text-secondary);
-    font-size: 11px;
-    font-weight: 800;
-    text-transform: uppercase;
+    font-size: 12px;
+    font-weight: 700;
 }
 
-.setting-field input {
+.setting-field input,
+.setting-field select {
     width: 100%;
     height: 34px;
     padding: 0 10px;
@@ -869,13 +906,27 @@ tbody tr:hover {
     outline: none;
 }
 
-.setting-field input:focus {
+.setting-field textarea {
+    width: 100%;
+    min-height: 68px;
+    padding: 8px 10px;
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    outline: none;
+    resize: vertical;
+}
+
+.setting-field input:focus,
+.setting-field select:focus,
+.setting-field textarea:focus {
     border-color: var(--accent);
 }
 
 .setting-toggle {
-    min-height: 74px;
-    padding: 12px;
+    min-height: 68px;
+    padding: 11px 12px;
     border: 1px solid var(--border-color);
     border-radius: 8px;
     background: var(--bg-primary);
@@ -894,9 +945,12 @@ tbody tr:hover {
     font-weight: 800;
 }
 
-.setting-toggle input {
+.setting-toggle input,
+.setting-toggle-row input[type="checkbox"] {
+    flex: 0 0 auto;
     width: 18px;
     height: 18px;
+    padding: 0;
     accent-color: var(--accent);
 }
 
@@ -904,7 +958,8 @@ tbody tr:hover {
     margin-top: 6px;
     color: var(--text-subdued);
     font-size: 11px;
-    line-height: 1.4;
+    line-height: 1.45;
+    max-width: 68ch;
 }
 
 .source-pill {
@@ -929,6 +984,101 @@ tbody tr:hover {
     grid-column: 1 / -1;
 }
 
+.settings-federation-body {
+    display: grid;
+    grid-template-columns: minmax(360px, 4fr) minmax(580px, 8fr);
+    gap: 20px;
+    padding: 16px;
+}
+
+.settings-federation-body > .settings-grid,
+.settings-federation-body > .probe-body {
+    padding: 0;
+}
+
+.federation-status-grid {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 12px;
+}
+
+.transport-log {
+    grid-column: 1 / -1;
+    min-width: 0;
+}
+
+.transport-log-head {
+    display: flex;
+    align-items: end;
+    justify-content: space-between;
+    gap: 12px;
+    margin: 14px 0 7px;
+}
+
+.transport-log-head strong { font-size: 12px; }
+.transport-log-head span { color: var(--text-subdued); font-size: 11px; }
+
+.transport-log-scroll {
+    max-height: 210px;
+    overflow: auto;
+    border: 1px solid var(--border-color);
+    border-radius: 7px;
+    background: var(--bg-primary);
+}
+
+.transport-row {
+    display: grid;
+    grid-template-columns: 68px minmax(100px, 1.2fr) 84px 72px 54px 64px 64px 66px 66px 66px;
+    gap: 8px;
+    align-items: center;
+    min-width: 850px;
+    min-height: 30px;
+    padding: 5px 9px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.055);
+    color: var(--text-secondary);
+    font: 11px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+
+.transport-row:last-child { border-bottom: 0; }
+.transport-row.transport-header {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    color: var(--text-subdued);
+    background: var(--bg-elevated);
+    font-size: 10px;
+    font-weight: 850;
+    text-transform: uppercase;
+}
+.transport-row > span { overflow: hidden; text-overflow: ellipsis; }
+.transport-number { text-align: right; }
+
+@media (max-width: 1000px) {
+    .settings-layout {
+        grid-template-columns: 1fr;
+        grid-template-areas:
+            "access"
+            "oidc"
+            "agent"
+            "agentstatus"
+            "similarity"
+            "similaritystatus"
+            "federation"
+            "lastfm"
+            "developer"
+            "actions";
+    }
+    .settings-federation-body { grid-template-columns: 1fr; }
+}
+
+@media (max-width: 700px) {
+    .settings-grid,
+    .federation-status-grid { grid-template-columns: 1fr; }
+    .setting-field { max-width: none; }
+}
+
 .settings-note {
     padding: 14px;
     color: var(--text-secondary);
@@ -937,7 +1087,7 @@ tbody tr:hover {
 }
 
 .probe-body {
-    padding: 14px;
+    padding: 16px;
 }
 
 .probe-intro {
@@ -955,9 +1105,43 @@ tbody tr:hover {
 }
 
 .probe-row {
-    display: flex;
-    justify-content: space-between;
-    gap: 10px;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: baseline;
+    gap: 12px;
+    min-height: 22px;
+}
+
+.probe-row strong {
+    max-width: 210px;
+    overflow: hidden;
+    text-align: right;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.similarity-profile-details {
+    margin-top: 12px;
+    padding-top: 12px;
+    border-top: 1px solid var(--border-color);
+}
+
+.similarity-profile-details > span {
+    display: block;
+    margin-bottom: 5px;
+    color: var(--text-subdued);
+    font-size: 10px;
+    font-weight: 800;
+    text-transform: uppercase;
+}
+
+.similarity-profile-details pre {
+    margin: 0;
+    color: var(--text-secondary);
+    font: inherit;
+    font-size: 11px;
+    line-height: 1.45;
+    white-space: pre-wrap;
 }
 
 .library-row {
@@ -1560,7 +1744,7 @@ tbody tr:hover {
                 <p x-text="pageSubtitle()"></p>
             </div>
             <div class="top-actions">
-                <button class="btn" @click="refreshAll()">
+                <button class="btn" @click="refreshAll()" x-show="activeView !== 'settings'">
                     <i data-lucide="refresh-cw"></i>
                     Refresh
                 </button>
@@ -2059,7 +2243,7 @@ tbody tr:hover {
             <div class="settings-page">
                 <form class="settings-layout" @submit.prevent="saveSettings()">
                     <div class="settings-column">
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-wide settings-oidc">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>OIDC</strong>
@@ -2070,6 +2254,7 @@ tbody tr:hover {
                                 <div class="setting-field settings-wide">
                                     <label>Callback URL</label>
                                     <input readonly :value="callbackUrl()" />
+                                    <div class="setting-help">Register this exact redirect URL in your identity provider.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2105,6 +2290,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('oidc_admin_groups')" x-text="settingSource('oidc_admin_groups')"></span>
                                     </label>
                                     <input x-model="settingsDraft.oidc_admin_groups" placeholder="/admin,/furumusic-admins" />
+                                    <div class="setting-help">Comma-separated identity-provider groups whose members receive administrator access.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2112,11 +2298,12 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('oidc_user_groups')" x-text="settingSource('oidc_user_groups')"></span>
                                     </label>
                                     <input x-model="settingsDraft.oidc_user_groups" />
+                                    <div class="setting-help">Comma-separated groups allowed to sign in. Leave empty to allow any authenticated OIDC user.</div>
                                 </div>
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-wide settings-agent">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Agent</strong>
@@ -2134,12 +2321,13 @@ tbody tr:hover {
                                         <input type="checkbox" x-model="settingsDraft.agent_enabled" />
                                     </div>
                                 </div>
-                                <div class="setting-field">
+                                <div class="setting-field settings-short">
                                     <label>
                                         <span>Concurrency</span>
                                         <span class="source-pill" :class="sourceClass('agent_concurrency')" x-text="settingSource('agent_concurrency')"></span>
                                     </label>
                                     <input type="number" min="1" max="32" x-model="settingsDraft.agent_concurrency" />
+                                    <div class="setting-help">Maximum number of inbox items processed at the same time. Higher values use more CPU and LLM capacity.</div>
                                 </div>
                                 <div class="setting-field settings-wide">
                                     <label>
@@ -2161,6 +2349,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_url')" x-text="settingSource('agent_llm_url')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_llm_url" />
+                                    <div class="setting-help">Base URL of an OpenAI-compatible service. The agent sends chat requests to its <code>/v1/chat/completions</code> endpoint.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2168,6 +2357,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_model')" x-text="settingSource('agent_llm_model')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_llm_model" />
+                                    <div class="setting-help">Model identifier sent to the configured LLM service, for example the name exposed by your local model server.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2175,6 +2365,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_auth')" x-text="settingSource('agent_llm_auth')"></span>
                                     </label>
                                     <input type="password" x-model="settingsDraft.agent_llm_auth" autocomplete="off" />
+                                    <div class="setting-help">Complete HTTP Authorization value expected by the LLM endpoint, for example <code>Bearer …</code>.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2182,6 +2373,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_confidence_threshold')" x-text="settingSource('agent_confidence_threshold')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_confidence_threshold" />
+                                    <div class="setting-help">Minimum confidence required to accept generated metadata automatically. Lower-confidence results are sent for review.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2189,11 +2381,12 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_context_limit')" x-text="settingSource('agent_context_limit')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_context_limit" />
+                                    <div class="setting-help">Maximum model context budget in tokens. Reduce it for smaller models or increase it when processing large batches.</div>
                                 </div>
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-wide settings-similarity">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Similarity Search</strong>
@@ -2210,7 +2403,7 @@ tbody tr:hover {
                                         <span x-text="settingsDraft.similarity_enabled ? 'Enabled for this instance' : 'Disabled'"></span>
                                         <input type="checkbox" x-model="settingsDraft.similarity_enabled" />
                                     </div>
-                                    <div class="setting-help">Downloads the selected model and processes every visible local track. With federation enabled, signed anonymous LSH summaries discover likely peers; full query embeddings are sent only to those peers, and this instance answers their searches.</div>
+                                    <div class="setting-help">Builds an audio fingerprint index for finding musically similar tracks. When federation is enabled, compatible peers can also participate in searches.</div>
                                 </div>
                                 <div class="setting-field settings-wide">
                                     <label>
@@ -2222,7 +2415,10 @@ tbody tr:hover {
                                             <option :value="model.id" x-text="`${model.id} · ${model.dimensions}d`"></option>
                                         </template>
                                     </select>
-                                    <div class="setting-help" x-text="(similarityStatus.models || []).find(model => model.id === settingsDraft.similarity_model)?.license || ''"></div>
+                                    <div class="setting-help">
+                                        <span>The model converts audio into vectors used for comparison. Changing it rebuilds the search index.</span>
+                                        <span x-show="(similarityStatus.models || []).find(model => model.id === settingsDraft.similarity_model)?.license" x-text="' License: ' + (similarityStatus.models || []).find(model => model.id === settingsDraft.similarity_model)?.license"></span>
+                                    </div>
                                 </div>
                                 <div class="setting-field settings-wide">
                                     <label>
@@ -2234,25 +2430,22 @@ tbody tr:hover {
                                             <option :value="profile.id" x-text="profile.title"></option>
                                         </template>
                                     </select>
-                                    <details class="setting-help" style="margin-top:8px">
-                                        <summary style="cursor:pointer">Show profile details</summary>
-                                        <pre style="white-space:pre-wrap;font:inherit;margin:8px 0 0" x-text="selectedSimilarityProfile()?.details || 'Profile details are loading…'"></pre>
-                                    </details>
+                                    <div class="setting-help">Controls how audio is decoded and normalized before comparison. Changing it rebuilds the search index.</div>
                                 </div>
-                                <div class="setting-field">
+                                <div class="setting-field settings-short">
                                     <label>
                                         <span>Background workers</span>
                                         <span class="source-pill" :class="sourceClass('similarity_workers')" x-text="settingSource('similarity_workers')"></span>
                                     </label>
                                     <input type="number" min="1" max="16" step="1" x-model="settingsDraft.similarity_workers" />
-                                    <div class="setting-help">Applied immediately after saving.</div>
+                                    <div class="setting-help">Number of tracks indexed in parallel. Higher values finish sooner but use more CPU and memory.</div>
                                 </div>
                             </div>
                         </section>
                     </div>
 
                     <div class="settings-column settings-side">
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-narrow settings-access">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Authentication</strong>
@@ -2283,26 +2476,15 @@ tbody tr:hover {
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-lastfm">
                             <div class="panel-head">
                                 <div class="panel-title">
-                                    <strong>API</strong>
-                                    <span>Developer and enrichment integrations</span>
+                                    <strong>Last.fm Integration</strong>
+                                    <span>Metadata enrichment and scrobbling credentials</span>
                                 </div>
                                 <span class="badge" :class="settings.lastfm_scrobbling_configured ? 'ok' : 'disabled'" x-text="settings.lastfm_scrobbling_configured ? 'Last.fm configured' : 'Last.fm missing'"></span>
                             </div>
                             <div class="settings-grid">
-                                <div class="setting-toggle">
-                                    <label>
-                                        <span>Swagger UI</span>
-                                        <span class="source-pill" :class="sourceClass('swagger_enabled')" x-text="settingSource('swagger_enabled')"></span>
-                                    </label>
-                                    <div class="setting-toggle-row">
-                                        <span x-text="settingsDraft.swagger_enabled ? 'Enabled' : 'Disabled'"></span>
-                                        <input type="checkbox" x-model="settingsDraft.swagger_enabled" />
-                                    </div>
-                                    <div class="setting-help">Interactive API docs at /swagger/ after restart.</div>
-                                </div>
                                 <div class="setting-field">
                                     <label>
                                         <span>{{ t.settings_lastfm_api_key }}</span>
@@ -2322,7 +2504,29 @@ tbody tr:hover {
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-developer">
+                            <div class="panel-head">
+                                <div class="panel-title">
+                                    <strong>Developer API</strong>
+                                    <span>Interactive API documentation</span>
+                                </div>
+                            </div>
+                            <div class="settings-grid">
+                                <div class="setting-toggle settings-wide">
+                                    <label>
+                                        <span>Swagger UI</span>
+                                        <span class="source-pill" :class="sourceClass('swagger_enabled')" x-text="settingSource('swagger_enabled')"></span>
+                                    </label>
+                                    <div class="setting-toggle-row">
+                                        <span x-text="settingsDraft.swagger_enabled ? 'Available at /swagger/' : 'Disabled' "></span>
+                                        <input type="checkbox" x-model="settingsDraft.swagger_enabled" />
+                                    </div>
+                                    <div class="setting-help">Exposes interactive API documentation at <code>/swagger/</code> for developers and integrations.</div>
+                                </div>
+                            </div>
+                        </section>
+
+                        <section class="panel settings-section settings-section-full settings-federation">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Federation</strong>
@@ -2330,6 +2534,7 @@ tbody tr:hover {
                                 </div>
                                 <span class="badge" :class="federationStatus.node && federationStatus.node.running ? 'ok' : 'disabled'" x-text="federationStatus.node && federationStatus.node.running ? 'running' : 'stopped'"></span>
                             </div>
+                            <div class="settings-federation-body">
                             <div class="settings-grid">
                                 <div class="setting-toggle">
                                     <label>
@@ -2340,7 +2545,7 @@ tbody tr:hover {
                                         <span x-text="settingsDraft.federation_enabled ? 'Enabled' : 'Disabled'"></span>
                                         <input type="checkbox" x-model="settingsDraft.federation_enabled" />
                                     </div>
-                                    <div class="setting-help">Applies immediately on save — no restart needed. Peers can browse and stream every visible track.</div>
+                                    <div class="setting-help">Lets other peers in this logical network discover the visible library and request audio streams from this instance.</div>
                                 </div>
                                 <div class="setting-field settings-wide">
                                     <label>
@@ -2348,9 +2553,9 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('federation_network_id')" x-text="settingSource('federation_network_id')"></span>
                                     </label>
                                     <input x-model="settingsDraft.federation_network_id" placeholder="my-crew-music-7f3a" autocomplete="off" />
-                                    <div class="setting-help">Every peer using the same id finds the others automatically.</div>
+                                    <div class="setting-help">Peers with the same Network ID form one isolated logical network and discover each other automatically. You may choose any private value; use the exact same value on every peer that should join this network.</div>
                                 </div>
-                                <div class="setting-field">
+                                <div class="setting-field settings-wide">
                                     <label>
                                         <span>Save federated tracks on play</span>
                                         <span class="source-pill" :class="sourceClass('federation_save_on_listen')" x-text="settingSource('federation_save_on_listen')"></span>
@@ -2359,10 +2564,11 @@ tbody tr:hover {
                                         <span x-text="settingsDraft.federation_save_on_listen ? 'Import into the shared library' : 'Use temporary cache'"></span>
                                         <input type="checkbox" x-model="settingsDraft.federation_save_on_listen" />
                                     </div>
-                                    <div class="setting-help">Server-wide policy. Imported tracks become available to every user and are published by this peer. Federation metadata is trusted and bypasses the AI agent.</div>
+                                    <div class="setting-help">When enabled, a federated track is permanently imported after playback and becomes available to every local user. Otherwise it remains only in the temporary cache. Imported peer metadata is trusted as provided and does not enter AI review.</div>
                                 </div>
                             </div>
                             <div class="probe-body" x-show="federationStatus.node">
+                                <div class="federation-status-grid">
                                 <div class="probe-table" x-show="federationStatus.node && federationStatus.node.running">
                                     <div class="probe-row"><span>Endpoint</span><strong x-text="fedShort(federationStatus.node && federationStatus.node.endpoint_id)"></strong></div>
                                     <div class="probe-row"><span>Network</span><strong x-text="(federationStatus.node && federationStatus.node.network) || '-'"></strong></div>
@@ -2372,7 +2578,7 @@ tbody tr:hover {
                                     <div class="probe-row"><span>Published items</span><strong x-text="(federationStatus.node && federationStatus.node.published_items) ?? '-'"></strong></div>
                                     <div class="probe-row"><span>Last sync</span><strong x-text="federationStatus.last_sync || 'not yet'"></strong></div>
                                 </div>
-                                <div class="probe-table" x-show="fedTransport().total_samples > 0" style="margin-top:10px">
+                                <div class="probe-table" x-show="fedTransport().total_samples > 0">
                                     <div class="probe-row">
                                         <span>Transport path</span>
                                         <strong>
@@ -2384,23 +2590,34 @@ tbody tr:hover {
                                     <div class="probe-row"><span>Protocols</span><strong x-text="`${fedTransport().audio_samples || 0} audio · ${fedTransport().catalog_samples || 0} catalog · ${fedTransport().similarity_samples || 0} similarity · ${fedTransport().sync_samples || 0} sync`"></strong></div>
                                     <div class="probe-row"><span>Last peer</span><strong x-text="fedShort(fedTransport().last_peer)"></strong></div>
                                 </div>
-                                <div class="probe-table" x-show="fedTransport().last && fedTransport().last.length" style="margin-top:10px">
-                                    <template x-for="(sample, index) in fedTransport().last.slice(0, 5)" :key="`${sample.at}-${sample.protocol}-${sample.direction}-${sample.phase}-${sample.peer_id}-${index}`">
-                                        <div class="probe-row">
-                                            <span x-text="`${sample.protocol} · ${sample.direction} · ${sample.phase}`"></span>
-                                            <strong>
-                                                <span class="badge" :class="fedPathBadge(sample.selected_path)" x-text="sample.selected_path || 'unknown'"></span>
-                                                <span x-text="` ${fedRtt(sample.selected_rtt_ms)} · tx ${formatBytes(sample.total_tx_bytes || 0)} · rx ${formatBytes(sample.total_rx_bytes || 0)} · lost ${formatBytes(sample.lost_bytes || 0)}`"></span>
-                                            </strong>
+                                <div class="transport-log" x-show="fedTransport().last && fedTransport().last.length">
+                                    <div class="transport-log-head">
+                                        <strong>Recent transport operations</strong>
+                                        <span>Newest first · updates automatically</span>
+                                    </div>
+                                    <div class="transport-log-scroll">
+                                        <div class="transport-row transport-header">
+                                            <span>Time</span><span>User / peer</span><span>Protocol</span><span>Direction</span><span>Phase</span><span>Path</span><span class="transport-number">RTT</span><span class="transport-number">TX</span><span class="transport-number">RX</span><span class="transport-number">Lost</span>
                                         </div>
-                                    </template>
+                                        <template x-for="(sample, index) in fedTransport().last" :key="`${sample.at}-${sample.protocol}-${sample.direction}-${sample.phase}-${sample.peer_id}-${index}`">
+                                            <div class="transport-row">
+                                                <span :title="sample.at" x-text="formatTransportTime(sample.at)"></span>
+                                                <span :title="sample.user_name || sample.peer_id" x-text="sample.user_name || fedShort(sample.peer_id)"></span>
+                                                <span x-text="sample.protocol || '-'"></span>
+                                                <span x-text="sample.direction || '-'"></span>
+                                                <span x-text="sample.phase || '-'"></span>
+                                                <span x-text="sample.selected_path || 'unknown'"></span>
+                                                <span class="transport-number" x-text="fedRtt(sample.selected_rtt_ms)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.total_tx_bytes || 0)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.total_rx_bytes || 0)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.lost_bytes || 0)"></span>
+                                            </div>
+                                        </template>
+                                    </div>
+                                </div>
                                 </div>
                                 <p class="probe-intro muted" x-show="federationStatus.last_error" x-text="federationStatus.last_error"></p>
                                 <div class="toolbar" style="margin-top:14px; flex-wrap:wrap; gap:8px">
-                                    <button class="btn" type="button" @click="loadFederation()" :disabled="federationLoading">
-                                        <i data-lucide="refresh-cw"></i>
-                                        Refresh
-                                    </button>
                                     <button class="btn" type="button" @click="fedSyncNow()" :disabled="federationLoading || !(federationStatus.node && federationStatus.node.running)">
                                         <i data-lucide="upload-cloud"></i>
                                         Publish now
@@ -2422,13 +2639,14 @@ tbody tr:hover {
                                     </div>
                                 </div>
                             </div>
+                            </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-narrow settings-similarity-status">
                             <div class="panel-head">
                                 <div class="panel-title">
-                                    <strong>Similarity Status</strong>
-                                    <span>Model download, indexing, and active profile</span>
+                                    <strong>Search Index Statistics</strong>
+                                    <span>Similarity model, indexing progress, and storage</span>
                                 </div>
                                 <span class="badge" :class="similarityBadge()" x-text="similarityStatus.status?.phase || 'disabled'"></span>
                             </div>
@@ -2445,15 +2663,15 @@ tbody tr:hover {
                                     <div class="probe-row"><span>Stored</span><strong x-text="`${similarityStatus.status?.stored_vectors || 0} vectors · ${formatBytes(similarityStatus.status?.stored_bytes || 0)}`"></strong></div>
                                     <div class="probe-row" x-show="similarityStatus.status?.current_track"><span>Current track</span><strong x-text="similarityStatus.status?.current_track"></strong></div>
                                 </div>
+                                <div class="similarity-profile-details">
+                                    <span>Selected preprocessing profile</span>
+                                    <pre x-text="selectedSimilarityProfile()?.details || 'Profile information is not available.'"></pre>
+                                </div>
                                 <div style="height:6px;background:rgba(255,255,255,.08);border-radius:999px;overflow:hidden;margin-top:12px" x-show="similarityStatus.status?.phase === 'processing'">
                                     <div style="height:100%;background:var(--accent);transition:width .25s" :style="`width:${similarityProgress()}%`"></div>
                                 </div>
                                 <p class="probe-intro muted" x-show="similarityStatus.status?.last_error" x-text="similarityStatus.status?.last_error"></p>
                                 <div class="toolbar" style="margin-top:14px;flex-wrap:wrap;gap:8px">
-                                    <button class="btn" type="button" @click="loadSimilarity()" :disabled="similarityLoading">
-                                        <i data-lucide="refresh-cw"></i>
-                                        Refresh
-                                    </button>
                                     <button class="btn danger" type="button" @click="clearSimilarityEmbeddings()" :disabled="similarityLoading || !(similarityStatus.status?.stored_vectors > 0)">
                                         <i data-lucide="trash-2"></i>
                                         Clear all embeddings
@@ -2462,7 +2680,7 @@ tbody tr:hover {
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-narrow settings-agent-status">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Agent Status</strong>
@@ -2493,10 +2711,6 @@ tbody tr:hover {
                     <div class="action-strip settings-actions">
                         <span class="selection-summary">Settings are stored as database overrides unless an environment variable wins.</span>
                         <div class="toolbar">
-                            <button class="btn" type="button" @click="loadSettings()">
-                                <i data-lucide="refresh-cw"></i>
-                                Reload
-                            </button>
                             <button class="btn primary" type="submit" :disabled="settingsSaving">
                                 <i :data-lucide="settingsSaving ? 'loader-circle' : 'save'"></i>
                                 <span x-text="settingsSaving ? 'Saving...' : 'Save settings'"></span>
@@ -2568,7 +2782,7 @@ tbody tr:hover {
                             <div class="user-activity-row">
                                 <div class="user-activity-cover">
                                     <template x-if="play.cover_url">
-                                        <img :src="play.cover_url" :alt="play.release_title || play.title" loading="lazy">
+                                        <img :src="play.cover_url" alt="" aria-hidden="true" loading="lazy">
                                     </template>
                                     <template x-if="!play.cover_url">
                                         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
@@ -3497,6 +3711,17 @@ function adminV2() {
             return ms != null ? `${Math.round(Number(ms))} ms` : '-';
         },
 
+        formatTransportTime(value) {
+            const date = new Date(value);
+            if (!value || Number.isNaN(date.getTime())) return '-';
+            return date.toLocaleTimeString([], {
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit',
+                hour12: false
+            });
+        },
+
         async loadSettingsProbe(showErrors = true) {
             this.settingsProbeLoading = true;
             try {

templates/player/modals.html

@@ -825,7 +825,7 @@
                                     @click.stop="$store.history.playFrom(idx)"
                                     :title="item.track?.title || item.track_title">
                                 <template x-if="item.track && item.track.cover_url">
-                                    <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
+                                    <img :src="item.track.cover_url" alt="" aria-hidden="true" loading="lazy">
                                 </template>
                                 <template x-if="!item.track || !item.track.cover_url">
                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>

templates/player/scripts.html

@@ -2198,6 +2198,8 @@ document.addEventListener('alpine:init', () => {
         _dragOverIdx: null,
         _pointerDragMove: null,
         _pointerDragEnd: null,
+        _playNextGroupId: null,
+        _playNextGroupSequence: 0,
 
         add(track) {
             this.addToEnd([track]);
@@ -2210,13 +2212,21 @@ document.addEventListener('alpine:init', () => {
 
         effectiveCurrentIndex() {
             const currentTrack = Alpine.store('player')?.currentTrack || null;
-            if (currentTrack?.id) {
-                return this.tracks.findIndex(track => Number(track?.id) === Number(currentTrack.id));
+            const currentKey = this._trackIdentity(currentTrack);
+            if (currentKey) {
+                const index = this.tracks.findIndex(track => this._trackIdentity(track) === currentKey);
+                if (index >= 0) return index;
             }
             if (!this.tracks.length) return -1;
             return Math.max(0, Math.min(Number(this.currentIndex || 0), this.tracks.length - 1));
         },
 
+        _trackIdentity(track) {
+            if (track?.content_id) return `content:${track.content_id}`;
+            if (track?.id != null && track.id !== '') return `id:${String(track.id)}`;
+            return '';
+        },
+
         queueItemState(index) {
             const current = this.effectiveCurrentIndex();
             if (current < 0) return 'upcoming';
@@ -2252,8 +2262,9 @@ document.addEventListener('alpine:init', () => {
         },
 
         syncCurrentIndexToTrack(track) {
-            if (!track?.id || !this.tracks.length) return -1;
-            const index = this.tracks.findIndex(item => Number(item?.id) === Number(track.id));
+            const key = this._trackIdentity(track);
+            if (!key || !this.tracks.length) return -1;
+            const index = this.tracks.findIndex(item => this._trackIdentity(item) === key);
             if (index >= 0) this.currentIndex = index;
             return index;
         },
@@ -2280,6 +2291,7 @@ document.addEventListener('alpine:init', () => {
 
         playRelease(tracks, startIndex) {
             this.tracks = this._tracksForQueueAdd(tracks);
+            this._playNextGroupId = null;
             this.playFromIndex(startIndex || 0);
         },
 
@@ -2447,8 +2459,35 @@ document.addEventListener('alpine:init', () => {
         _addNextLocal(tracks) {
             const items = this._tracksWithJamDefaults(tracks);
             if (!items.length) return;
-            const insertAt = Math.min(this.currentIndex + 1, this.tracks.length);
-            this.tracks.splice(insertAt, 0, ...items);
+            const current = this.effectiveCurrentIndex();
+            let insertAt = Math.min(Math.max(0, current + 1), this.tracks.length);
+            let groupId = this._playNextGroupId
+                || this.tracks[insertAt]?._playNextGroupId
+                || null;
+            if (groupId) this._playNextGroupId = groupId;
+            if (groupId) {
+                let lastGroupIndex = -1;
+                for (let index = current; index < this.tracks.length; index++) {
+                    if (this.tracks[index]?._playNextGroupId === groupId) {
+                        lastGroupIndex = index;
+                    }
+                }
+                if (lastGroupIndex >= current) {
+                    insertAt = lastGroupIndex + 1;
+                } else {
+                    groupId = null;
+                }
+            }
+            if (!groupId) {
+                this._playNextGroupSequence += 1;
+                groupId = `next-${Date.now()}-${this._playNextGroupSequence}`;
+                this._playNextGroupId = groupId;
+            }
+            const groupedItems = items.map(item => ({
+                ...item,
+                _playNextGroupId: groupId,
+            }));
+            this.tracks.splice(insertAt, 0, ...groupedItems);
         },
 
         _removeLocal(idx) {
@@ -2471,6 +2510,7 @@ document.addEventListener('alpine:init', () => {
             if (toIdx < 0 || toIdx >= this.tracks.length) return;
             const [track] = this.tracks.splice(fromIdx, 1);
             this.tracks.splice(toIdx, 0, track);
+            this._playNextGroupId = null;
             // Adjust currentIndex to follow the currently playing track
             if (this.currentIndex === fromIdx) {
                 this.currentIndex = toIdx;
@@ -2484,6 +2524,7 @@ document.addEventListener('alpine:init', () => {
         _clearLocal() {
             this.tracks = [];
             this.currentIndex = 0;
+            this._playNextGroupId = null;
         },
     });
 
@@ -2508,6 +2549,7 @@ document.addEventListener('alpine:init', () => {
         searchLoading: false,
         similaritySearchLabel: '',
         similaritySearchError: '',
+        similaritySearchStats: { loading: false, tracks: 0, artists: 0, peers: 0, elapsed_ms: 0 },
         federationSearch: { loading: false, error: '', artists: [], releases: [], tracks: [] },
         artistFederation: { loading: false, error: '', releases: [], tracks: [] },
         federationPreparing: {},
@@ -3400,6 +3442,7 @@ document.addEventListener('alpine:init', () => {
                 const res = await fetch(`/api/player/search?q=${encodeURIComponent(q)}&limit=10`);
                 if (!res.ok) throw new Error('failed');
                 this.searchResults = await res.json();
+                this.applyFederationArtworkFallbacks();
             } catch {
                 this.searchResults = { artists: [], releases: [], tracks: [] };
             }
@@ -3425,18 +3468,30 @@ document.addEventListener('alpine:init', () => {
             this.searchLoading = true;
             this.searchResults = null;
             this.federationSearch = { loading: true, error: '', artists: [], releases: [], tracks: [] };
+            this.similaritySearchStats = { loading: true, tracks: 0, artists: 0, peers: 0, elapsed_ms: 0 };
             Alpine.store('info').close();
             try {
-                const response = await fetch(`/api/player/similarity/${id}`);
-                const data = await response.json().catch(() => ({}));
-                if (!response.ok) throw new Error(data.error || T.similarityFailed);
-                this.similaritySearchLabel = data.label || initialLabel;
+                const completeRequest = fetch(`/api/player/similarity/${id}`);
+                const localResponse = await fetch(`/api/player/similarity/${id}?local_only=true`);
+                const localData = await localResponse.json().catch(() => ({}));
+                if (!localResponse.ok) throw new Error(localData.error || T.similarityFailed);
+                this.similaritySearchLabel = localData.label || initialLabel;
                 this.searchQuery = this.similaritySearchLabel;
                 this.searchResults = {
                     artists: [],
                     releases: [],
-                    tracks: Array.isArray(data.tracks) ? data.tracks : [],
+                    tracks: Array.isArray(localData.tracks) ? localData.tracks : [],
                 };
+                this.searchLoading = false;
+                this.similaritySearchStats = {
+                    loading: true,
+                    ...this.similarityResultCounts(this.searchResults.tracks, []),
+                    peers: 0,
+                    elapsed_ms: localData.elapsed_ms || 0,
+                };
+                const response = await completeRequest;
+                const data = await response.json().catch(() => ({}));
+                if (!response.ok) throw new Error(data.error || T.similarityFailed);
                 this.federationSearch = {
                     loading: false,
                     error: data.federation_error || '',
@@ -3444,15 +3499,94 @@ document.addEventListener('alpine:init', () => {
                     releases: [],
                     tracks: Array.isArray(data.federation_tracks) ? data.federation_tracks : [],
                 };
+                this.similaritySearchStats = {
+                    loading: false,
+                    ...this.similarityResultCounts(
+                        this.searchResults.tracks,
+                        this.federationSearch.tracks
+                    ),
+                    peers: Number(data.queried_peers || 0),
+                    elapsed_ms: Number(data.elapsed_ms || 0),
+                };
             } catch (error) {
-                this.searchResults = { artists: [], releases: [], tracks: [] };
-                this.federationSearch = { loading: false, error: '', artists: [], releases: [], tracks: [] };
-                this.similaritySearchError = error?.message || T.similarityFailed;
+                if (!this.searchResults) {
+                    this.searchResults = { artists: [], releases: [], tracks: [] };
+                    this.similaritySearchError = error?.message || T.similarityFailed;
+                } else {
+                    this.federationSearch = {
+                        ...this.federationSearch,
+                        loading: false,
+                        error: error?.message || T.similarityFailed,
+                    };
+                }
+                this.similaritySearchStats = {
+                    ...this.similaritySearchStats,
+                    loading: false,
+                };
             }
             this.searchLoading = false;
             this._afterNavigation(options);
         },
 
+        similarityResultCounts(localTracks = [], federationTracks = []) {
+            const artists = new Set();
+            for (const track of localTracks) {
+                for (const artist of [...(track?.artists || []), ...(track?.featured_artists || [])]) {
+                    const name = this.normalizeFederationSearchText(artist?.name);
+                    if (name) artists.add(name);
+                }
+            }
+            for (const track of federationTracks) {
+                const metadata = track?.metadata || {};
+                for (const artist of [...(metadata.artists || []), ...(metadata.featured_artists || [])]) {
+                    const name = this.normalizeFederationSearchText(artist?.name);
+                    if (name) artists.add(name);
+                }
+            }
+            return {
+                tracks: localTracks.length + federationTracks.length,
+                artists: artists.size,
+            };
+        },
+
+        similarityTrackOrder(track) {
+            const score = Number(track?.similarity_score);
+            if (!Number.isFinite(score)) return 1000000;
+            return Math.max(0, Math.round((1 - score) * 100000));
+        },
+
+        similarityQueueTracks() {
+            const local = (this.searchResults?.tracks || []).map(track => ({ ...track }));
+            const federated = (this.federationSearch?.tracks || []).map(track => ({
+                ...this.federationQueueTrack(track),
+                similarity_score: track.similarity_score,
+            }));
+            return [...local, ...federated].sort((left, right) => {
+                const score = Number(right?.similarity_score || 0)
+                    - Number(left?.similarity_score || 0);
+                if (score) return score;
+                return String(left?.title || '').localeCompare(String(right?.title || ''));
+            });
+        },
+
+        playSimilarityResult(track) {
+            const queue = Alpine.store('queue');
+            const tracks = this.similarityQueueTracks();
+            const key = queue._trackIdentity(track);
+            const index = tracks.findIndex(item => queue._trackIdentity(item) === key);
+            if (index >= 0) queue.playRelease(tracks, index);
+        },
+
+        formatSearchDuration(milliseconds) {
+            const ms = Math.max(0, Number(milliseconds) || 0);
+            if (ms < 10000) return `${(ms / 1000).toFixed(1)} s`;
+            if (ms < 60000) return `${Math.round(ms / 1000)} s`;
+            const totalSeconds = Math.round(ms / 1000);
+            const minutes = Math.floor(totalSeconds / 60);
+            const seconds = totalSeconds % 60;
+            return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+        },
+
         clearSearch() {
             this.stopFederationSearch();
             this.searchQuery = '';
@@ -3460,6 +3594,7 @@ document.addEventListener('alpine:init', () => {
             this.searchLoading = false;
             this.similaritySearchLabel = '';
             this.similaritySearchError = '';
+            this.similaritySearchStats = { loading: false, tracks: 0, artists: 0, peers: 0, elapsed_ms: 0 };
             if (this.view === 'search') {
                 this.view = this._previousView || 'artists';
                 this._setHash(this.view === 'my_uploads' ? '#uploads' : '#artists');
@@ -3518,13 +3653,17 @@ document.addEventListener('alpine:init', () => {
             };
             source.addEventListener('federation.track', upsertTrack);
             source.addEventListener('federation.artist', event => {
-                const artist = JSON.parse(event.data)?.entity;
+                const artist = this.withFederationArtistFallback(
+                    JSON.parse(event.data)?.entity
+                );
                 const key = artist?.key?.normalized_name;
                 if (!key) return;
                 updateResults('artists', item => item.key.normalized_name, item => item.name, artist);
             });
             source.addEventListener('federation.release', event => {
-                const release = JSON.parse(event.data)?.entity;
+                const release = this.hydrateFederationSearchRelease(
+                    JSON.parse(event.data)?.entity
+                );
                 if (!release?.key) return;
                 updateResults('releases', item => JSON.stringify(item.key || {}), item => item.title, release);
             });
@@ -3601,9 +3740,98 @@ document.addEventListener('alpine:init', () => {
 
         federationArtistImage(artist) {
             if (!artist?.name) return '';
+            if (artist._federationArtworkFailed) return artist.local_image_url || '';
             return this.federationDiscoveredArtwork(artist.name);
         },
 
+        localArtistImage(name) {
+            const key = this.normalizeFederationSearchText(name);
+            return (this.searchResults?.artists || []).find(candidate =>
+                this.normalizeFederationSearchText(candidate.name) === key
+            )?.image_url || '';
+        },
+
+        withFederationArtistFallback(artist) {
+            if (!artist) return artist;
+            return { ...artist, local_image_url: this.localArtistImage(artist.name) };
+        },
+
+        applyFederationArtworkFallbacks() {
+            this.federationSearch = {
+                ...this.federationSearch,
+                artists: this.federationSearch.artists.map(artist =>
+                    this.withFederationArtistFallback(artist)
+                ),
+            };
+        },
+
+        federationArtistImageFailed(artist) {
+            const key = artist?.key?.normalized_name;
+            if (!key) return;
+            this.federationSearch = {
+                ...this.federationSearch,
+                artists: this.federationSearch.artists.map(candidate =>
+                    candidate?.key?.normalized_name === key
+                        ? {
+                            ...candidate,
+                            _federationArtworkFailed: true,
+                            local_image_url: candidate.local_image_url
+                                || this.localArtistImage(candidate.name),
+                        }
+                        : candidate
+                ),
+            };
+        },
+
+        hydrateFederationSearchRelease(release) {
+            if (!release) return release;
+            const title = this.normalizeFederationSearchText(release.title);
+            const primaryArtists = (release.key?.primary_artists || [])
+                .map(name => this.normalizeFederationSearchText(name));
+            const tracks = this.federationSearch.tracks.filter(track => {
+                const metadata = track?.metadata || {};
+                if (this.normalizeFederationSearchText(metadata.release?.title) !== title) return false;
+                if (release.year && metadata.year && Number(release.year) !== Number(metadata.year)) return false;
+                if (!primaryArtists.length) return true;
+                const trackArtists = (metadata.artists || []).map(artist =>
+                    this.normalizeFederationSearchText(artist.name)
+                );
+                return primaryArtists.some(artist => trackArtists.includes(artist));
+            });
+            const owners = [...new Set([
+                ...(release.sources || []).map(source => source.owner),
+                ...tracks.flatMap(track =>
+                    (track.availability?.federation || []).map(source => source.owner)
+                ),
+            ].filter(Boolean))];
+            return { ...release, tracks, owners };
+        },
+
+        federationReleaseCover(release) {
+            if (!release) return '';
+            if (release._federationArtworkFailed) return release._discoveredCoverUrl || '';
+            return release.cover_url
+                || this.federationDiscoveredArtwork(release.artists?.[0], release.title);
+        },
+
+        federationReleaseCoverFailed(release, failedUrl) {
+            const discovered = this.federationDiscoveredArtwork(release?.artists?.[0], release?.title);
+            if (!release?.key) return;
+            const key = JSON.stringify(release.key);
+            this.federationSearch = {
+                ...this.federationSearch,
+                releases: this.federationSearch.releases.map(candidate =>
+                    JSON.stringify(candidate?.key) === key
+                        ? {
+                            ...candidate,
+                            _federationArtworkFailed: true,
+                            _discoveredCoverUrl: failedUrl === discovered ? '' : discovered,
+                        }
+                        : candidate
+                ),
+            };
+        },
+
         federationDiscoveredArtwork(artist, release = '') {
             if (!artist) return '';
             const params = new URLSearchParams({ artist });
@@ -3696,22 +3924,26 @@ document.addEventListener('alpine:init', () => {
                 uploader_name: 'Federation',
                 federation_pending: true,
                 _federationTrack: track,
+                similarity_score: track.similarity_score,
             };
         },
 
         openFederatedRelease(release, options = {}) {
             if (!release?.key) return;
-            this._federatedReleaseCache[release.key] = release;
-            this._beginNavigation('#releasefed?key=' + encodeURIComponent(release.key), options);
+            const cacheKey = typeof release.key === 'string'
+                ? release.key
+                : JSON.stringify(release.key);
+            this._federatedReleaseCache[cacheKey] = release;
+            this._beginNavigation('#releasefed?key=' + encodeURIComponent(cacheKey), options);
             const queuedTracks = (release.tracks || []).map(track => this.federationQueueTrack(track));
             const first = queuedTracks[0];
             this.currentRelease = {
                 id: null,
                 title: release.title,
-                release_type: release.release_type || 'release',
+                release_type: release.release_type || release.key?.release_type || 'release',
                 year: release.year,
-                cover_url: release.cover_url,
-                artists: first?.artists || [],
+                cover_url: this.federationReleaseCover(release),
+                artists: first?.artists || (release.artists || []).map(name => ({ id: null, name })),
                 tracks: queuedTracks,
                 uploaders: (release.owners || []).map(owner => ({
                     name: `Federation ${owner.slice(0, 10)}`,

templates/player/shell.html

@@ -17,6 +17,17 @@
                         <div class="user-role" x-text="$store.user.profile?.role || ''"></div>
                     </div>
                     <div class="user-widget-actions">
+                        <button class="user-logout-btn"
+                                x-show="$store.user.profile?.role === 'admin'"
+                                x-cloak
+                                @click="window.location.href = '/admin/'"
+                                title="{{ t.player_admin_panel }}"
+                                aria-label="{{ t.player_admin_panel }}">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
+                                <path d="M12 3l7 3v5c0 4.6-2.9 8.1-7 10-4.1-1.9-7-5.4-7-10V6l7-3z"/>
+                                <path d="M9.5 12l1.7 1.7 3.6-4"/>
+                            </svg>
+                        </button>
                         <button class="user-logout-btn" @click="$store.user.openSettings()" title="User settings" aria-label="User settings">
                             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
                                 <circle cx="12" cy="12" r="3"/>
@@ -80,7 +91,7 @@
                              @click="$store.library.openArtist(artist.id)">
                             <div class="following-avatar">
                                 <template x-if="artist.image_url">
-                                    <img :src="artist.image_url" :alt="artist.name" loading="lazy">
+                                    <img :src="artist.image_url" alt="" aria-hidden="true" loading="lazy">
                                 </template>
                                 <template x-if="!artist.image_url">
                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/></svg>
@@ -143,9 +154,6 @@
                     </div>
                 </template>
             </div>
-            <div class="sidebar-bottom">
-                <a href="/admin/">{{ t.player_admin_panel }}</a>
-            </div>
         </div>
 
         <template x-if="$store.mobile.libraryOpen">
@@ -196,7 +204,7 @@
                                              @click="$store.library.openArtist(artist.id); $store.mobile.closeLibrary()">
                                             <div class="following-avatar">
                                                 <template x-if="artist.image_url">
-                                                    <img :src="artist.image_url" :alt="artist.name" loading="lazy">
+                                                    <img :src="artist.image_url" alt="" aria-hidden="true" loading="lazy">
                                                 </template>
                                                 <template x-if="!artist.image_url">
                                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/></svg>
@@ -359,6 +367,17 @@
                         </div>
                     </div>
                     <div class="mobile-account-actions">
+                        <button class="user-logout-btn"
+                                x-show="$store.user.profile?.role === 'admin'"
+                                x-cloak
+                                @click="window.location.href = '/admin/'"
+                                title="{{ t.player_admin_panel }}"
+                                aria-label="{{ t.player_admin_panel }}">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
+                                <path d="M12 3l7 3v5c0 4.6-2.9 8.1-7 10-4.1-1.9-7-5.4-7-10V6l7-3z"/>
+                                <path d="M9.5 12l1.7 1.7 3.6-4"/>
+                            </svg>
+                        </button>
                         <button class="user-logout-btn"
                                 @click="$store.user.menuOpen = false; $store.user.openSettings()"
                                 title="User settings"
@@ -379,12 +398,24 @@
             <!-- Search Results -->
             <template x-if="$store.library.view === 'search'">
                 <div>
-                    <h2 class="search-similarity-title"
-                        x-show="$store.library.similaritySearchLabel"
-                        x-cloak>
-                        <span>{{ t.player_search_similar_to }}</span>
-                        <strong x-text="$store.library.similaritySearchLabel"></strong>
-                    </h2>
+                    <div class="search-similarity-heading"
+                         x-show="$store.library.similaritySearchLabel"
+                         x-cloak>
+                        <h2 class="search-similarity-title">
+                            <span>{{ t.player_search_similar_to }}</span>
+                            <strong x-text="$store.library.similaritySearchLabel"></strong>
+                        </h2>
+                        <div class="search-similarity-progress"
+                             :class="{ loading: $store.library.similaritySearchStats.loading }">
+                            <template x-if="$store.library.similaritySearchStats.loading">
+                                <span class="search-progress-live"><i></i> Searching peers…</span>
+                            </template>
+                            <span x-text="`${$store.library.similaritySearchStats.tracks} tracks · ${$store.library.similaritySearchStats.artists} artists`"></span>
+                            <template x-if="!$store.library.similaritySearchStats.loading">
+                                <span x-text="`${$store.library.similaritySearchStats.peers} peers · ${$store.library.formatSearchDuration($store.library.similaritySearchStats.elapsed_ms)}`"></span>
+                            </template>
+                        </div>
+                    </div>
                     <template x-if="$store.library.searchLoading">
                         <div class="loading-spinner"><div class="spinner"></div></div>
                     </template>
@@ -394,7 +425,7 @@
                         </div>
                     </template>
                     <template x-if="!$store.library.searchLoading && $store.library.searchResults">
-                        <div>
+                        <div :class="{ 'similarity-unified-results': $store.library.similaritySearchLabel }">
                             <template x-if="!$store.library.similaritySearchError && $store.library.searchResults.artists.length === 0 && $store.library.searchResults.releases.length === 0 && $store.library.searchResults.tracks.length === 0">
                                 <div class="empty-state">
                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
@@ -409,11 +440,9 @@
                                         <template x-for="artist in $store.library.searchResults.artists" :key="artist.id">
                                             <div class="search-artist-card" @click="$store.library.openArtist(artist.id)">
                                                 <div class="search-artist-img">
+                                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/></svg>
                                                     <template x-if="artist.image_url">
-                                                        <img :src="artist.image_url" :alt="artist.name" loading="lazy">
-                                                    </template>
-                                                    <template x-if="!artist.image_url">
-                                                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/></svg>
+                                                        <img class="artwork-image" :src="artist.image_url" alt="" aria-hidden="true" loading="lazy" @load="$event.currentTarget.classList.add('artwork-loaded')" @error="$event.currentTarget.classList.remove('artwork-loaded')">
                                                     </template>
                                                 </div>
                                                 <div class="search-artist-name" x-text="artist.name"></div>
@@ -430,11 +459,9 @@
                                         <template x-for="release in $store.library.searchResults.releases" :key="release.id">
                                             <div class="search-release-card" @click="$store.library.openRelease(release.id)" style="position:relative">
                                                 <div class="search-release-cover" style="position:relative">
+                                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
                                                     <template x-if="release.cover_url">
-                                                        <img :src="release.cover_url" :alt="release.title" loading="lazy">
-                                                    </template>
-                                                    <template x-if="!release.cover_url">
-                                                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
+                                                        <img class="artwork-image" :src="release.cover_url" alt="" aria-hidden="true" loading="lazy" @load="$event.currentTarget.classList.add('artwork-loaded')" @error="$event.currentTarget.classList.remove('artwork-loaded')">
                                                     </template>
                                                     <button class="card-info-btn" @click.stop="$store.library.openReleaseInfo(release)" :title="$store.library.releaseInfo(release)" aria-label="{{ t.player_release_info }}">
                                                         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
@@ -464,7 +491,8 @@
                                     <template x-for="(track, idx) in $store.library.searchResults.tracks" :key="track.id">
                                         <div class="track-row"
                                              :class="{ playing: $store.player.currentTrack && $store.player.currentTrack.id === track.id }"
-                                             @dblclick="$store.library.playSearchTrack(idx)">
+                                             :style="$store.library.similaritySearchLabel ? `order:${$store.library.similarityTrackOrder(track)}` : ''"
+                                             @dblclick="$store.library.similaritySearchLabel ? $store.library.playSimilarityResult(track) : $store.library.playSearchTrack(idx)">
                                             <span class="track-num" x-text="idx + 1"></span>
                                             <div class="track-info">
                                                 <div class="track-title" x-text="track.title"></div>
@@ -509,8 +537,9 @@
                                     </template>
                                 </div>
                             </template>
-                            <div class="search-section federation-search-section">
-                                <h2 class="search-section-title">
+                            <div class="search-section federation-search-section"
+                                 :class="{ 'similarity-federation-merged': $store.library.similaritySearchLabel }">
+                                <h2 class="search-section-title" x-show="!$store.library.similaritySearchLabel">
                                     Federation
                                     <span class="federation-live-badge"
                                           x-show="$store.library.federationSearch.loading"
@@ -520,11 +549,11 @@
                                     <div class="federation-search-status error"
                                          x-text="$store.library.federationSearch.error"></div>
                                 </template>
-                                <template x-if="$store.library.federationSearch.loading && $store.library.federationSearch.tracks.length === 0">
+                                <template x-if="!$store.library.similaritySearchLabel && $store.library.federationSearch.loading && $store.library.federationSearch.tracks.length === 0">
                                     <div class="federation-search-status">Searching peers…</div>
                                 </template>
                                 <div class="search-artists-row"
-                                     x-show="$store.library.federationSearch.artists.length > 0"
+                                     x-show="!$store.library.similaritySearchLabel && $store.library.federationSearch.artists.length > 0"
                                      x-cloak>
                                     <template x-for="artist in $store.library.federationSearch.artists"
                                               :key="artist.key.normalized_name">
@@ -532,10 +561,12 @@
                                              @click="$store.library.openFederatedArtist(artist)">
                                             <div class="search-artist-img">
                                                 <img x-show="$store.library.federationArtistImage(artist)"
+                                                     class="artwork-image"
                                                      :src="$store.library.federationArtistImage(artist)"
-                                                     :alt="artist.name"
+                                                     alt="" aria-hidden="true"
                                                      loading="lazy"
-                                                     @error="$event.currentTarget.style.display = 'none'">
+                                                     @load="$event.currentTarget.classList.add('artwork-loaded')"
+                                                     @error="$event.currentTarget.classList.remove('artwork-loaded'); $store.library.federationArtistImageFailed(artist)">
                                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
                                                     <circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/>
                                                 </svg>
@@ -547,18 +578,21 @@
                                     </template>
                                 </div>
                                 <div class="search-releases-row"
-                                     x-show="$store.library.federationSearch.releases.length > 0"
+                                     x-show="!$store.library.similaritySearchLabel && $store.library.federationSearch.releases.length > 0"
                                      x-cloak>
                                     <template x-for="release in $store.library.federationSearch.releases"
                                               :key="JSON.stringify(release.key)">
-                                        <div class="search-release-card federation-entity-card">
+                                        <div class="search-release-card federation-entity-card"
+                                             @click="$store.library.openFederatedRelease($store.library.hydrateFederationSearchRelease(release))">
                                             <div class="search-release-cover">
-                                                <img x-show="release.cover_url"
-                                                     :src="release.cover_url"
-                                                     :alt="release.title"
-                                                     loading="lazy">
-                                                <svg x-show="!release.cover_url"
-                                                     viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+                                                <img x-show="$store.library.federationReleaseCover(release)"
+                                                     class="artwork-image"
+                                                     :src="$store.library.federationReleaseCover(release)"
+                                                     alt="" aria-hidden="true"
+                                                     loading="lazy"
+                                                     @load="$event.currentTarget.classList.add('artwork-loaded')"
+                                                     @error="$event.currentTarget.classList.remove('artwork-loaded'); $store.library.federationReleaseCoverFailed(release, $event.currentTarget.getAttribute('src'))">
+                                                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
                                                     <rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/>
                                                 </svg>
                                             </div>
@@ -571,7 +605,8 @@
                                 <template x-for="(track, idx) in $store.library.federationSearch.tracks"
                                           :key="track.key.content_id">
                                     <div class="track-row federation-track-row"
-                                         @dblclick="$store.library.playFederatedTrack(track)">
+                                         :style="$store.library.similaritySearchLabel ? `order:${$store.library.similarityTrackOrder(track)}` : ''"
+                                         @dblclick="$store.library.similaritySearchLabel ? $store.library.playSimilarityResult($store.library.federationQueueTrack(track)) : $store.library.playFederatedTrack(track)">
                                         <span class="track-num federation-track-status">
                                             <template x-if="!$store.library.federationDownload(track.key.content_id) && !$store.library.federationFailure(track.key.content_id) && !$store.library.isTrackLocal(track)">
                                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
@@ -645,6 +680,12 @@
                                               x-text="formatTime(track.metadata.duration_seconds)"></span>
                                     </div>
                                 </template>
+                                <div class="similarity-search-inline-progress"
+                                     x-show="$store.library.similaritySearchLabel && $store.library.similaritySearchStats.loading"
+                                     x-cloak>
+                                    <span class="similarity-search-inline-spinner" aria-hidden="true"></span>
+                                    <span>Searching federation for more similar tracks…</span>
+                                </div>
                             </div>
                         </div>
                     </template>
@@ -666,7 +707,7 @@
                                 <div class="card" @click="$store.library.openArtist(artist.id)">
                                     <div class="card-img">
                                         <template x-if="artist.image_url">
-                                            <img :src="artist.image_url" :alt="artist.name" loading="lazy">
+                                            <img :src="artist.image_url" alt="" aria-hidden="true" loading="lazy">
                                         </template>
                                         <template x-if="!artist.image_url">
                                             <span class="placeholder-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 10-16 0"/></svg></span>
@@ -722,7 +763,7 @@
                         <div class="artist-img">
                             <template x-if="$store.library.currentArtist.image_url">
                                 <img :src="$store.library.currentArtist.image_url"
-                                     :alt="$store.library.currentArtist.name"
+                                     alt="" aria-hidden="true"
                                      @error="$store.library.currentArtist.image_url = null">
                             </template>
                             <template x-if="!$store.library.currentArtist.image_url">
@@ -805,7 +846,7 @@
                                                 :title="track.release_title"
                                                 aria-label="{{ t.player_release }}">
                                             <template x-if="track.cover_url">
-                                                <img :src="track.cover_url" :alt="track.release_title" loading="lazy">
+                                                <img :src="track.cover_url" alt="" aria-hidden="true" loading="lazy">
                                             </template>
                                             <template x-if="!track.cover_url">
                                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
@@ -868,7 +909,7 @@
                                     <div class="card" @click="$store.library.openRelease(release.id)">
                                         <div class="card-img">
                                             <template x-if="release.cover_url">
-                                                <img :src="release.cover_url" :alt="release.title"
+                                                <img :src="release.cover_url" alt="" aria-hidden="true"
                                                      loading="lazy" @error="release.cover_url = null">
                                             </template>
                                             <template x-if="!release.cover_url">
@@ -904,7 +945,7 @@
                                          @click="$store.library.openFederatedRelease(release)">
                                         <div class="card-img">
                                             <template x-if="release.cover_url">
-                                                <img :src="release.cover_url" :alt="release.title"
+                                                <img :src="release.cover_url" alt="" aria-hidden="true"
                                                      loading="lazy" @error="release.cover_url = null">
                                             </template>
                                             <template x-if="!release.cover_url">
@@ -1034,7 +1075,7 @@
                                                 :title="track.release_title"
                                                 aria-label="{{ t.player_release }}">
                                             <template x-if="track.cover_url">
-                                                <img :src="track.cover_url" :alt="track.release_title" loading="lazy">
+                                                <img :src="track.cover_url" alt="" aria-hidden="true" loading="lazy">
                                             </template>
                                             <template x-if="!track.cover_url">
                                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
@@ -1108,7 +1149,7 @@
                     <div class="release-header">
                         <div class="release-cover">
                             <template x-if="$store.library.currentRelease.cover_url">
-                                <img :src="$store.library.currentRelease.cover_url" :alt="$store.library.currentRelease.title">
+                                <img :src="$store.library.currentRelease.cover_url" alt="" aria-hidden="true">
                             </template>
                             <template x-if="!$store.library.currentRelease.cover_url">
                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
@@ -1486,11 +1527,9 @@
                             <svg viewBox="0 0 24 24" fill="currentColor"><circle cx="9" cy="6" r="1.5"/><circle cx="15" cy="6" r="1.5"/><circle cx="9" cy="12" r="1.5"/><circle cx="15" cy="12" r="1.5"/><circle cx="9" cy="18" r="1.5"/><circle cx="15" cy="18" r="1.5"/></svg>
                         </div>
                         <div class="queue-track-cover">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
                             <template x-if="item.track.cover_url">
-                                <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
-                            </template>
-                            <template x-if="!item.track.cover_url">
-                                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
+                                <img class="artwork-image" :src="item.track.cover_url" alt="" aria-hidden="true" loading="lazy" @load="$event.currentTarget.classList.add('artwork-loaded')" @error="$event.currentTarget.classList.remove('artwork-loaded')">
                             </template>
                             <span class="queue-federation-status federation-track-status"
                                   x-show="item.track.federation_pending"
@@ -1570,7 +1609,7 @@
                     <div class="player-cover"
                          @click.stop="$store.mobile.openPlayerFullscreen()">
                         <template x-if="$store.player.currentTrack.cover_url">
-                            <img :src="$store.player.currentTrack.cover_url" :alt="$store.player.currentTrack.title">
+                            <img :src="$store.player.currentTrack.cover_url" alt="" aria-hidden="true">
                         </template>
                         <template x-if="!$store.player.currentTrack.cover_url">
                             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
@@ -1868,11 +1907,9 @@
                         type="button"
                         @click="item.index >= 0 ? $store.queue.playFromIndex(item.index) : $store.player.play(item.track)">
                     <div class="mobile-expanded-queue-cover">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
                         <template x-if="item.track.cover_url">
-                            <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
-                        </template>
-                        <template x-if="!item.track.cover_url">
-                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
+                            <img class="artwork-image" :src="item.track.cover_url" alt="" aria-hidden="true" loading="lazy" @load="$event.currentTarget.classList.add('artwork-loaded')" @error="$event.currentTarget.classList.remove('artwork-loaded')">
                         </template>
                     </div>
                     <div class="mobile-expanded-queue-info">

templates/player/styles.html

@@ -450,22 +450,6 @@ button.user-stat:hover {
     letter-spacing: 0.3px;
 }
 
-.sidebar-bottom {
-    padding: 12px 16px;
-    border-top: 1px solid var(--border-color);
-}
-
-.sidebar-bottom a {
-    color: var(--text-subdued);
-    text-decoration: none;
-    font-size: 12px;
-    display: flex;
-    align-items: center;
-    gap: 6px;
-}
-
-.sidebar-bottom a:hover { color: var(--text-secondary); }
-
 /* Center Content */
 .center-content {
     flex: 1;
@@ -1411,7 +1395,7 @@ button.user-stat:hover {
     justify-content: center;
 }
 
-.queue-track-cover img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
+.queue-track-cover img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
 .queue-track-cover svg { width: 20px; height: 20px; color: var(--text-subdued); }
 
 .queue-track-cover .queue-federation-status {
@@ -2751,6 +2735,41 @@ button.user-stat:hover {
     border-top: 1px solid var(--border);
     padding-top: 18px;
 }
+.federation-search-section.similarity-federation-merged {
+    margin-top: -24px;
+    padding-top: 0;
+    border-top: 0;
+}
+.similarity-unified-results {
+    display: flex;
+    flex-direction: column;
+}
+.similarity-unified-results > .search-section {
+    display: contents;
+}
+.similarity-unified-results .search-section-title { order: -1000002; }
+.similarity-unified-results .track-list-header { order: -1000001; }
+.similarity-unified-results .federation-search-status { order: 1000001; }
+.similarity-search-inline-progress {
+    order: 1000000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 9px;
+    min-height: 42px;
+    margin-top: 4px;
+    border-top: 1px solid var(--border);
+    color: var(--text-muted);
+    font-size: 12px;
+}
+.similarity-search-inline-spinner {
+    width: 14px;
+    height: 14px;
+    border: 2px solid rgba(255, 255, 255, .16);
+    border-top-color: var(--accent);
+    border-radius: 999px;
+    animation: federation-progress-spin .8s linear infinite;
+}
 .federation-live-badge {
     margin-left: 8px;
     color: var(--accent);
@@ -2872,12 +2891,20 @@ button.user-stat:hover {
     margin-bottom: 12px;
 }
 
+.search-similarity-heading {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 18px;
+    margin: 0 0 20px;
+}
 .search-similarity-title {
     display: flex;
     flex-wrap: wrap;
     align-items: baseline;
     gap: 8px;
-    margin: 0 0 20px;
+    min-width: 0;
+    margin: 0;
     color: var(--text-muted);
     font-size: 16px;
     font-weight: 500;
@@ -2886,6 +2913,42 @@ button.user-stat:hover {
     color: var(--text);
     font-size: 20px;
 }
+.search-similarity-progress {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    min-height: 30px;
+    padding: 5px 10px;
+    border: 1px solid var(--border);
+    border-radius: 7px;
+    background: var(--bg-secondary);
+    color: var(--text-muted);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+.search-similarity-progress.loading { border-color: rgba(29, 185, 84, .38); }
+.search-progress-live {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    color: var(--accent);
+}
+.search-progress-live i {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    background: currentColor;
+    animation: similarity-search-pulse 1.1s ease-in-out infinite;
+}
+@keyframes similarity-search-pulse {
+    50% { opacity: .3; transform: scale(.75); }
+}
+@media (max-width: 720px) {
+    .search-similarity-heading { align-items: flex-start; flex-direction: column; }
+    .search-similarity-progress { max-width: 100%; flex-wrap: wrap; white-space: normal; }
+}
 
 .search-artists-row {
     display: flex;
@@ -2959,6 +3022,7 @@ button.user-stat:hover {
 .search-release-card:hover { background: var(--bg-elevated); }
 
 .search-release-cover {
+    position: relative;
     width: 100%;
     aspect-ratio: 1;
     border-radius: 6px;
@@ -2970,9 +3034,12 @@ button.user-stat:hover {
     justify-content: center;
 }
 
-.search-release-cover img { width: 100%; height: 100%; object-fit: cover; }
+.search-release-cover img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
 .search-release-cover svg { width: 40px; height: 40px; color: var(--text-subdued); }
 
+.artwork-image { z-index: 1; opacity: 0; }
+.artwork-image.artwork-loaded { opacity: 1; }
+
 /* Like button */
 .like-btn {
     background: none;
@@ -5585,6 +5652,7 @@ button.user-stat:hover {
     }
 
     .mobile-expanded-queue-cover {
+        position: relative;
         width: 42px;
         height: 42px;
         border-radius: 5px;
@@ -5596,6 +5664,8 @@ button.user-stat:hover {
     }
 
     .mobile-expanded-queue-cover img {
+        position: absolute;
+        inset: 0;
         width: 100%;
         height: 100%;
         object-fit: cover;