feat: cross-playlist favorites virtual playlist

cmd/playlist_ops_test.go

@@ -61,8 +61,9 @@ func TestPlaylistListEmpty(t *testing.T) {
 	if err != nil {
 		t.Fatalf("PlaylistList: %v", err)
 	}
-	if !strings.Contains(out, "No playlists") {
-		t.Errorf("output = %q, want 'No playlists...'", out)
+	// Favorites always appears as a virtual playlist even when empty.
+	if !strings.Contains(out, "Favorites") {
+		t.Errorf("output = %q, want Favorites virtual playlist to appear", out)
 	}
 }
 

docs/keybindings.md

@@ -75,6 +75,7 @@ active when the picker opened. While typing a filter, `Enter` finishes it and
 | Key | Action |
 |---|---|
 | `f` | Toggle bookmark ★ on selected track (or favorite radio station in radio browser) |
+| `n` | Toggle favorite ♥ on selected track (cross-playlist; favorited tracks appear in the "Favorites" virtual playlist) |
 | `Ctrl+F` | Search — active provider's native search (Spotify, Qobuz, Tidal, Navidrome, Lyrion, Jellyfin, Emby, Plex, Audiobookshelf, Mixcloud, NetEase, Local) or YouTube fallback. Available from playlist and provider-browser views. |
 | `u` | Load URL (stream/playlist) |
 | `y` | Show or close lyrics |

docs/playlists.md

@@ -368,7 +368,7 @@ title = "My Radio"
 | `s` | Sort tracks, cycling supported sort keys (tracks screen) |
 | `w` | Write marked/highlighted tracks, or the current queue from the list screen, to another playlist |
 | `o` | Add files to the open playlist (tracks screen) |
-| `D` | Open the directory-sources screen for the open playlist (tracks screen) |
+| `D` | List: open the file browser to add `[[dir]]` sources to the highlighted playlist. Tracks: open the directory-sources screen for the open playlist |
 | `[` `]` | Move track up/down and save (tracks screen) |
 | `d` | Delete playlist (confirms; `Recently Played` cannot be deleted) / Remove marked tracks, or highlighted track if none are marked |
 | `u` | Undo the last playlist-manager edit |
@@ -387,8 +387,26 @@ The playlist list flags playlists that reference `[[dir]]` sources with a
 | `r` | Toggle `recursive` on the highlighted source (re-scans immediately) |
 | `←` / `Backspace` / `Esc` | Back to the tracks screen |
 
-From the file browser (opened with `a` above, or with `o` from the tracks
-screen), press `D` to add all selected directories — or the highlighted
-directory, or the directory you are currently browsing when neither applies —
-as live `[[dir]]` sources instead of expanding them into explicit tracks.
-Directories already referenced are skipped and reported.
+From the file browser (opened with `a` above, with `o` from the tracks
+screen, or with `D` from the list screen), press `D` to add all selected
+directories — or the highlighted directory, or the directory you are currently
+browsing when neither applies — as live `[[dir]]` sources instead of expanding
+them into explicit tracks. Directories already referenced are skipped and
+reported.
+
+## Favorites
+
+Press `n` on any track in the track list to toggle it as a
+favorite. Favorited tracks are collected into a virtual **"Favorites"**
+playlist that always appears at the top of the playlist list — regardless of
+which playlist the track was favorited from, and even when empty.
+
+Favorites are cross-playlist: a track favorited while browsing "gym" shows up
+in "Favorites" and vice versa. The "Favorites" playlist is backed by
+`~/.config/cliamp/favorites.toml` and behaves like "Recently Played" — it is
+a virtual playlist that cannot be renamed, deleted, or modified via the
+playlist manager. Use `n` again to unfavorite a track.
+
+Favorited tracks display a small red `♥` marker in the track list. The bookmark
+system (`f` key, `★` marker) is separate — bookmarks are per-playlist,
+while favorites span all playlists.

external/local/dirs_test.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/bjarneo/cliamp/favorites"
 	"github.com/bjarneo/cliamp/history"
 	"github.com/bjarneo/cliamp/playlist"
 )
@@ -199,6 +200,14 @@ func TestCreateDirPlaylist(t *testing.T) {
 	if len(dirs) != 1 || dirs[0].Path != audio || !dirs[0].Recursive {
 		t.Fatalf("dirs = %+v", dirs)
 	}
+
+	// Virtual playlists have no directory sources: both reserved names must
+	// be rejected so the manager never opens the dirs screen for them.
+	for _, name := range []string{history.PlaylistName, favorites.PlaylistName} {
+		if dirs, err := p.DirSources(name); err == nil {
+			t.Fatalf("DirSources(%q) = %+v, want reserved-name error", name, dirs)
+		}
+	}
 	// Reject duplicate create.
 	if err := p.CreateDirPlaylist("music", []string{audio}); err == nil {
 		t.Fatal("duplicate create should fail")
@@ -1005,3 +1014,58 @@ func TestRestorePlaylistDocumentRejectsHistory(t *testing.T) {
 		t.Fatal("expected an error restoring over the reserved history name")
 	}
 }
+
+func TestPlaylistsMigratesLegacyFavoritesToml(t *testing.T) {
+	p := newTestProvider(t)
+	src := filepath.Join(p.dir, "Favorites.toml")
+	if err := os.WriteFile(src, []byte("[[track]]\npath = \"/a.mp3\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	lists, err := p.Playlists()
+	if err != nil {
+		t.Fatalf("Playlists: %v", err)
+	}
+
+	// Original must be gone.
+	if _, err := os.Stat(src); !errors.Is(err, fs.ErrNotExist) {
+		t.Fatal("Favorites.toml should have been migrated away")
+	}
+
+	// Renamed file must appear.
+	dst := filepath.Join(p.dir, favoritesLegacyName+".toml")
+	if _, err := os.Stat(dst); err != nil {
+		t.Fatalf("migrated file missing: %v", err)
+	}
+
+	found := false
+	for _, l := range lists {
+		if l.ID == favoritesLegacyName {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("migrated playlist not listed; got %v", lists)
+	}
+}
+
+func TestPlaylistsSkipsMigrationWhenDestExists(t *testing.T) {
+	p := newTestProvider(t)
+	src := filepath.Join(p.dir, "Favorites.toml")
+	dst := filepath.Join(p.dir, favoritesLegacyName+".toml")
+	if err := os.WriteFile(src, []byte("[[track]]\npath = \"/a.mp3\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(dst, []byte("[[track]]\npath = \"/b.mp3\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := p.Playlists(); err != nil {
+		t.Fatalf("Playlists: %v", err)
+	}
+	// Source must NOT be clobbered when destination already exists.
+	if _, err := os.Stat(src); err != nil {
+		t.Fatalf("Favorites.toml should remain when dest already exists: %v", err)
+	}
+}