fix(tui): gate the search and copy keys on what they need

Author: LargeModGames

CHANGELOG.md

@@ -10,7 +10,7 @@
 
 ### Fixed
 
-- **The sidebar, the help menu and Settings only offer what your source can do**: without a Spotify session the Library panel used to be hidden under every other source, which also hid Friends and Stats even though neither needs Spotify, while under the Spotify scope it kept offering Liked Songs, Albums, Artists, Podcasts, Discover and Recently Played, each ending in the "Spotify not connected" message. The panel is now drawn under every source with the rows that work: Friends and Stats always, Local Files and AI DJ when built in, and the six Spotify rows only with a Spotify session; a mouse click on the panel lands on the row you see. The help menu (`?`) applies the same rule: a rebindable key that needs Spotify or another source stays listed with a `(needs Spotify)` / `(not for Local Files)` / `(Internet Radio only)` suffix, and a fixed key of a screen your source cannot reach is left out. Settings hides the Spotify-only behavior rows (the playback poll, the liked and episode icons, the saved-library sort orders, the community pin) without a session, marks the Spotify-only key rows the same way, offers only `home` and `stats` as startup routes without a session instead of five screens that would open empty, and names the `d` row "Switch Music Source" to match the help menu. The copy-song-URL and copy-album-URL keys now follow the track that plays, not the browse scope: a Spotify track playing under another source still copies, and with nothing playing both keys say so instead of doing nothing.
+- **The sidebar, the help menu and Settings only offer what your source can do**: without a Spotify session the Library panel used to be hidden under every other source, which also hid Friends and Stats even though neither needs Spotify, while under the Spotify scope it kept offering Liked Songs, Albums, Artists, Podcasts, Discover and Recently Played, each ending in the "Spotify not connected" message. The panel is now drawn under every source with the rows that work: Friends and Stats always, Local Files and AI DJ when built in, and the six Spotify rows only with a Spotify session; a mouse click on the panel lands on the row you see. The help menu (`?`) applies the same rule: a rebindable key that needs Spotify or another source stays listed with a `(needs Spotify)` / `(not for Local Files)` / `(Internet Radio only)` suffix, and a fixed key of a screen your source cannot reach is left out. Settings hides the Spotify-only behavior rows (the playback poll, the liked and episode icons, the saved-library sort orders, the community pin) without a session, marks the Spotify-only key rows the same way, offers only `home` and `stats` as startup routes without a session instead of five screens that would open empty, and names the `d` row "Switch Music Source" to match the help menu. The copy-song-URL and copy-album-URL keys now follow the track that plays, not the browse scope: a Spotify track playing under another source still copies, and with nothing playing both keys say so instead of doing nothing. The search key without a Spotify session says so too, instead of opening an input that cannot search.
 
 - **Disconnecting headphones no longer freezes spotatui**: with a decoded source playing (Local Files, Subsonic, Internet Radio, YouTube, Qobuz), unplugging the output device — Bluetooth headphones disconnecting, a USB DAC pulled — left the audio engine waiting on an audio callback that would never run again. Because that wait happens on the same serial queue every other request goes through, the whole app stopped responding: playback was silent *and* searches, browsing, and playback controls stopped working until restart. The engine now notices the device is gone - both when it is unplugged and when the system simply moves its default output elsewhere, which nothing reports - and refuses those calls instead of waiting, then rebuilds the output on the new default device and puts the track back where it was. Unplugging pauses it there, the same thing macOS does when AirPods come out; plugging something in keeps it playing, now through the device you just connected. Radio stops instead (a live stream has no position to return to), and a track playing from the queue resumes at the next queued item ([#496](https://github.com/LargeModGames/spotatui/issues/496)).
 

src/core/app/construction.rs

@@ -244,14 +244,28 @@ impl Default for App {
 impl App {
   /// `App::default()` with a Spotify session, for tests that need one without
   /// an `IoEvent` channel.
-  #[cfg(all(test, feature = "tui"))]
+  #[cfg(test)]
   pub(crate) fn default_connected() -> App {
     App {
       spotify_connected: true,
       ..App::default()
     }
   }
 
+  /// This app under a browse scope, for tests.
+  #[cfg(all(test, feature = "tui"))]
+  pub(crate) fn under_source(mut self, source: Source) -> App {
+    self.active_source = source;
+    self
+  }
+
+  /// This app with a Spotify playback context, for tests.
+  #[cfg(all(test, feature = "tui"))]
+  pub(crate) fn with_playback(mut self, context: CurrentPlaybackContext) -> App {
+    self.current_playback_context = Some(context);
+    self
+  }
+
   #[cfg(test)]
   pub fn new(
     io_tx: Sender<IoEvent>,

src/core/driver/mod.rs

@@ -154,6 +154,22 @@ pub struct Driver {
   radio_stream_started: bool,
 }
 
+/// The startup route's data fetch, gated on what the route needs.
+fn fetch_startup_route(app: &mut App) {
+  let route = app.get_current_route().id.clone();
+  if !app.availability(route.startup_requirement()).is_available() {
+    return;
+  }
+  match route {
+    RouteId::RecentlyPlayed => app.dispatch(IoEvent::GetRecentlyPlayed),
+    RouteId::AlbumList => app.dispatch(IoEvent::GetCurrentUserSavedAlbums(None)),
+    RouteId::Artists => app.dispatch(IoEvent::GetFollowedArtists(None)),
+    RouteId::Podcasts => app.dispatch(IoEvent::GetCurrentUserSavedShows(None)),
+    RouteId::Stats => app.reload_stats(),
+    _ => {}
+  }
+}
+
 impl Driver {
   pub fn new(
     shared_position: Option<Arc<AtomicU64>>,
@@ -867,18 +883,7 @@ impl Driver {
     // handlers that normally fetch a screen's data on navigation — kick
     // off that fetch here or the screen renders empty until re-entered.
     // (Home needs nothing extra; Discover fetches from within its menu.)
-    // The fetch is gated on the route's startup requirement.
-    let needs = app.get_current_route().id.startup_requirement();
-    if app.availability(needs).is_available() {
-      match app.get_current_route().id {
-        RouteId::RecentlyPlayed => app.dispatch(IoEvent::GetRecentlyPlayed),
-        RouteId::AlbumList => app.dispatch(IoEvent::GetCurrentUserSavedAlbums(None)),
-        RouteId::Artists => app.dispatch(IoEvent::GetFollowedArtists(None)),
-        RouteId::Podcasts => app.dispatch(IoEvent::GetCurrentUserSavedShows(None)),
-        RouteId::Stats => app.reload_stats(),
-        _ => {}
-      }
-    }
+    fetch_startup_route(app);
     // A persisted non-Spotify active source needs its sidebar data loaded
     // too (all of these are inert no-ops when the feature is off).
     app.load_source_sidebar(app.active_source);
@@ -939,3 +944,53 @@ impl Driver {
     }
   }
 }
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use crate::core::app::ActiveBlock;
+  use crate::core::user_config::UserConfig;
+  use std::sync::mpsc::{channel, Receiver};
+  use std::time::SystemTime;
+
+  fn app_on(route: RouteId, block: ActiveBlock, connected: bool) -> (App, Receiver<IoEvent>) {
+    let (tx, rx) = channel();
+    let mut app = App::new(tx, UserConfig::new(), connected.then(SystemTime::now));
+    app.push_navigation_stack(route, block);
+    (app, rx)
+  }
+
+  #[test]
+  fn a_spotify_startup_route_fetches_nothing_without_a_session() {
+    let (mut app, rx) = app_on(RouteId::AlbumList, ActiveBlock::AlbumList, false);
+
+    fetch_startup_route(&mut app);
+
+    assert!(!rx
+      .try_iter()
+      .any(|event| matches!(event, IoEvent::GetCurrentUserSavedAlbums(_))));
+  }
+
+  #[test]
+  fn a_spotify_startup_route_fetches_its_data_with_a_session() {
+    let (mut app, rx) = app_on(RouteId::AlbumList, ActiveBlock::AlbumList, true);
+
+    fetch_startup_route(&mut app);
+
+    assert!(rx
+      .try_iter()
+      .any(|event| matches!(event, IoEvent::GetCurrentUserSavedAlbums(_))));
+  }
+
+  #[test]
+  fn the_stats_startup_route_loads_without_a_session() {
+    let (mut app, rx) = app_on(RouteId::Stats, ActiveBlock::Stats, false);
+
+    fetch_startup_route(&mut app);
+
+    assert!(app.stats_loading);
+    assert!(rx
+      .try_iter()
+      .any(|event| matches!(event, IoEvent::LoadListeningStats(_))));
+  }
+}

src/tui/handlers/empty.rs

@@ -74,6 +74,20 @@ pub fn handler(key: Key, app: &mut App) {
 mod tests {
   use super::*;
   use crate::core::app::RouteId;
+  use crate::core::source::Source;
+
+  #[test]
+  fn up_and_left_reach_the_library_under_a_free_source() {
+    let mut app = App::default().under_source(Source::Local);
+    app.set_current_route_state(Some(ActiveBlock::Empty), Some(ActiveBlock::MyPlaylists));
+
+    handler(Key::Up, &mut app);
+    assert_eq!(app.get_current_route().hovered_block, ActiveBlock::Library);
+
+    app.set_current_route_state(None, Some(ActiveBlock::AlbumTracks));
+    handler(Key::Left, &mut app);
+    assert_eq!(app.get_current_route().hovered_block, ActiveBlock::Library);
+  }
 
   #[test]
   fn on_enter() {

src/tui/handlers/mod.rs

@@ -47,6 +47,7 @@ use crate::core::app::{
   ActiveBlock, App, ArtistBlock, InputContext, PlaybackOwner, RouteId, SearchResultBlock,
   NOTHING_PLAYING_STATUS,
 };
+use crate::core::requirement::{Availability, Capability, Requirement};
 use crate::core::source::Source;
 use crate::tui::event::Key;
 
@@ -399,25 +400,40 @@ pub(super) fn focus_global_search(app: &mut App) {
   app.set_current_route_state(Some(ActiveBlock::Input), Some(ActiveBlock::Input));
 }
 
-/// Focuses the search input, or reports why the active source has none.
+/// Focuses the search input, or reports why the key does nothing now.
 pub(super) fn open_global_search(app: &mut App) -> bool {
-  if app.active_source.supports_search() {
-    focus_global_search(app);
-    true
-  } else {
-    app.set_status_message(
-      format!("Search isn't available for {}", app.active_source.label()),
-      4,
-    );
-    false
+  match app.availability(Requirement::Capability(Capability::Search)) {
+    Availability::Available => {
+      focus_global_search(app);
+      true
+    }
+    Availability::NeedsSpotify => {
+      app.set_status_message("Search needs a Spotify session", 4);
+      false
+    }
+    Availability::NotForSource(_) | Availability::OnlyForSource(_) => {
+      app.set_status_message(
+        format!("Search isn't available for {}", app.active_source.label()),
+        4,
+      );
+      false
+    }
   }
 }
 
-/// The copy keys read the Spotify playback, so they need Spotify to own it.
+/// The copy keys read the Spotify playback, so Spotify must own it and have an item.
 fn copy_url(app: &mut App, copy: Action) {
   match app.playback_owner() {
     PlaybackOwner::Spotify | PlaybackOwner::NativeSpotify => {
-      app.apply(copy);
+      let has_item = app
+        .current_playback_context
+        .as_ref()
+        .is_some_and(|context| context.item.is_some());
+      if has_item {
+        app.apply(copy);
+      } else {
+        app.set_status_message(NOTHING_PLAYING_STATUS, 4);
+      }
     }
     PlaybackOwner::None => app.set_status_message(NOTHING_PLAYING_STATUS, 4),
     PlaybackOwner::Queue | PlaybackOwner::Decoded => {
@@ -685,7 +701,7 @@ mod tests {
 
   #[test]
   fn search_key_on_the_error_page_dismisses_the_error_first() {
-    let mut app = App::default();
+    let mut app = App::default_connected();
     app.handle_error(anyhow::anyhow!("boom"));
     assert_eq!(app.get_current_route().id, RouteId::Error);
 
@@ -952,7 +968,7 @@ mod tests {
 
   #[test]
   fn search_key_in_playlist_track_table_opens_global_search_input() {
-    let mut app = App::default();
+    let mut app = App::default_connected();
     let playlist_id = PlaylistId::from_id("37i9dQZF1DX4WYpdgoIcn6")
       .unwrap()
       .into_static();
@@ -968,7 +984,7 @@ mod tests {
 
   #[test]
   fn search_key_outside_playlist_track_table_opens_global_search_input() {
-    let mut app = App::default();
+    let mut app = App::default_connected();
     app.track_table.context = Some(TrackTableContext::SavedTracks);
     app.push_navigation_stack(RouteId::TrackTable, ActiveBlock::TrackTable);
 
@@ -1094,10 +1110,35 @@ mod tests {
     );
   }
 
+  fn spotify_track_context() -> CurrentPlaybackContext {
+    CurrentPlaybackContext {
+      device: Device {
+        id: Some("device-1".to_string()),
+        is_active: true,
+        is_private_session: false,
+        is_restricted: false,
+        name: "Desk Speaker".to_string(),
+        _type: DeviceType::Computer,
+        volume_percent: Some(42),
+      },
+      repeat_state: RepeatState::Off,
+      shuffle_state: false,
+      context: None,
+      timestamp: Utc::now(),
+      progress: None,
+      is_playing: true,
+      item: Some(PlayableItem::Track(full_track(
+        "0000000000000000000001",
+        "Track 1",
+      ))),
+      currently_playing_type: CurrentlyPlayingType::Track,
+      actions: Actions::default(),
+    }
+  }
+
   #[test]
   fn copy_url_keys_follow_the_playback_owner_not_the_browse_scope() {
-    let mut app = App::default();
-    app.active_source = Source::Local;
+    let mut app = App::default().under_source(Source::Local);
     app.set_current_route_state(Some(ActiveBlock::Empty), Some(ActiveBlock::Library));
 
     handle_app(app.user_config.keys.copy_song_url, &mut app);
@@ -1107,14 +1148,36 @@ mod tests {
     handle_app(app.user_config.keys.copy_album_url, &mut app);
     assert_eq!(app.status_message.as_deref(), Some("Nothing is playing"));
 
-    // A session under the Local scope still owns the Spotify playback.
-    let mut app = App::default_connected();
-    app.active_source = Source::Local;
+    // An idle session is not a playing track.
+    let mut app = App::default_connected().under_source(Source::Local);
+    app.set_current_route_state(Some(ActiveBlock::Empty), Some(ActiveBlock::Library));
+    handle_app(app.user_config.keys.copy_album_url, &mut app);
+    assert_eq!(app.status_message.as_deref(), Some("Nothing is playing"));
+
+    // A Spotify track playing under the Local scope still copies; with no
+    // clipboard in a test App the copy exits without a message.
+    let mut app = App::default_connected()
+      .under_source(Source::Local)
+      .with_playback(spotify_track_context());
     app.set_current_route_state(Some(ActiveBlock::Empty), Some(ActiveBlock::Library));
     handle_app(app.user_config.keys.copy_album_url, &mut app);
     assert_eq!(app.status_message, None);
   }
 
+  #[test]
+  fn the_search_key_without_a_session_says_so_instead_of_opening_the_input() {
+    let mut app = App::default();
+    app.set_current_route_state(Some(ActiveBlock::Empty), Some(ActiveBlock::Library));
+
+    handle_app(app.user_config.keys.search, &mut app);
+
+    assert_ne!(app.get_current_route().active_block, ActiveBlock::Input);
+    assert_eq!(
+      app.status_message.as_deref(),
+      Some("Search needs a Spotify session")
+    );
+  }
+
   /// The DJ's own tests all call `ai_dj::handler` directly, which is the branch
   /// taken once the DJ screen already has focus (`handle_app` returns early for
   /// `ActiveBlock::AiDj`). That leaves the `dj_pick_model` arm of the global match

src/tui/handlers/mouse.rs

@@ -1144,7 +1144,7 @@ mod tests {
 
   #[test]
   fn click_search_input_focuses_input() {
-    let mut app = App::default();
+    let mut app = App::default_connected();
     app.view.size = Viewport {
       width: 160,
       height: 50,

tools/gates.count

@@ -7,10 +7,10 @@
 # the two adoption counters may only rise.
 
 crate_tui_refs_outside_tui = 2         # target 0
-app_field_writes_in_tui_handlers = 317 # target 0 (writes into app.view do not count)
+app_field_writes_in_tui_handlers = 315 # target 0 (writes into app.view do not count)
 ioevent_refs_in_tui = 51               # target 0
 synthetic_keys_in_mouse_handler = 3    # target 0 (the content-table re-entries through handle_block_events)
 wildcard_arms_in_action_tree = 0       # target 0, must stay 0
 view_writes_outside_tui = 12           # target 0 (producers outside tui/ and core/app/ writing App::view)
 action_refs_in_tui_handlers = 173      # adoption: may only rise
-test_attribute_total = 1795            # adoption: may only rise
+test_attribute_total = 1800            # adoption: may only rise