feat(music): tag completion, aligned listings, numbered playlist rows

The radio tag search now completes over popular tags from radio-browser's /json/tags endpoint (station-count order, capped at 500, cached per session), so the prompt offers real tags instead of a blind guess. Free-form input still works, and a failed fetch degrades to plain input.

Station listings align into columns: the votes field pads to a fixed width, and each annotation pads out to the widest candidate name.

Playlist rows carry a numeric overlay prefix, rebuilt after every change by a debounced after-change hook, so the cursor stays visible on cover-art thumbnails and each row's position is readable. Overlays leave the buffer text to EMMS.

Also fixed: the search now trims queries before they hit the API (a trailing space used to reach it as %20 and match nothing).

3 files changed, 228 insertions, 0 deletions

diff --git a/tests/test-music-config--radio-tags.el b/tests/test-music-config--radio-tags.el
new file mode 100644
index 00000000..60e1c9d8
--- /dev/null
+++ b/tests/test-music-config--radio-tags.el
@@ -0,0 +1,79 @@
+;;; test-music-config--radio-tags.el --- Tests for radio-browser tag pre-population -*- coding: utf-8; lexical-binding: t; -*-
+;;
+;; Author: Craig Jennings <c@cjennings.net>
+;;
+;;; Commentary:
+;; The tag-search prompt completes over the popular tags fetched from
+;; radio-browser's /json/tags endpoint (cached per session).  These tests cover
+;; the pure pieces: the endpoint URL, the parse (trim + drop-empty + dedupe,
+;; since the source data is user-generated and dirty), and the session cache.
+;; The network GET is mocked at the boundary.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(defvar cj/custom-keymap (make-sparse-keymap)
+  "Stub keymap for testing.")
+
+(require 'music-config)
+
+(defconst test-music-radio-tags--fixture
+  (concat "[{\"name\":\"jazz \",\"stationcount\":300},"
+          "{\"name\":\" jazz\",\"stationcount\":5},"
+          "{\"name\":\"\",\"stationcount\":2},"
+          "{\"name\":\"rock\",\"stationcount\":100}]")
+  "A recorded /json/tags response with whitespace, empty, and duplicate names.")
+
+;;; Normal Cases
+
+(ert-deftest test-music-radio-tags-url-shape ()
+  "Normal: the tags URL targets /json/tags ordered by station count with the limit."
+  (let* ((cj/music-radio-tag-limit 500)
+         (u (cj/music-radio--tags-url "de1.api.radio-browser.info")))
+    (should (string-match-p "/json/tags" u))
+    (should (string-match-p "order=stationcount" u))
+    (should (string-match-p "limit=500" u))))
+
+(ert-deftest test-music-radio-parse-tags-trims-dedupes-drops-empty ()
+  "Normal: tag names come back trimmed, deduped, and without empties."
+  (should (equal (cj/music-radio--parse-tags test-music-radio-tags--fixture)
+                 '("jazz" "rock"))))
+
+(ert-deftest test-music-radio-available-tags-caches-per-session ()
+  "Normal: the fetch runs once; later calls serve the cache."
+  (let ((cj/music-radio--tags-cache nil)
+        (calls 0))
+    (cl-letf (((symbol-function 'cj/music-radio--http-get)
+               (lambda (_url) (cl-incf calls) test-music-radio-tags--fixture)))
+      (should (equal (cj/music-radio--available-tags) '("jazz" "rock")))
+      (should (equal (cj/music-radio--available-tags) '("jazz" "rock")))
+      (should (= calls 1)))))
+
+;;; Boundary Cases
+
+(ert-deftest test-music-radio-parse-tags-empty-array ()
+  "Boundary: an empty tag array parses to nil."
+  (should-not (cj/music-radio--parse-tags "[]")))
+
+;;; Error Cases
+
+(ert-deftest test-music-radio-available-tags-fetch-failure-returns-nil-and-retries ()
+  "Error: a failed fetch yields nil, leaves the cache empty, and retries next call."
+  (let ((cj/music-radio--tags-cache nil)
+        (calls 0))
+    (cl-letf (((symbol-function 'cj/music-radio--http-get)
+               (lambda (_url) (cl-incf calls) nil)))
+      (should-not (cj/music-radio--available-tags))
+      (should-not cj/music-radio--tags-cache)
+      (should-not (cj/music-radio--available-tags))
+      (should (= calls 2)))))
+
+(ert-deftest test-music-radio-parse-tags-malformed-user-errors ()
+  "Error: a non-JSON body signals user-error, not a raw parse error."
+  (should-error (cj/music-radio--parse-tags "<html>502</html>")
+                :type 'user-error))
+
+(provide 'test-music-config--radio-tags)
+;;; test-music-config--radio-tags.el ends here
diff --git a/tests/test-music-config--radio.el b/tests/test-music-config--radio.el
index 3923a599..db917a03 100644
--- a/tests/test-music-config--radio.el
+++ b/tests/test-music-config--radio.el
@@ -134,5 +134,64 @@
     (should (= (length cands) 2))
     (should (= (length (delete-dups (copy-sequence keys))) 2))))
 
+;;; --------------------------- query whitespace --------------------------------
+
+(ert-deftest test-music-radio-search-and-play-trims-query ()
+  "Normal: surrounding whitespace on the query is stripped before the search.
+A trailing space in the minibuffer otherwise reaches the API as %20 and
+matches nothing."
+  (let (captured)
+    (cl-letf (((symbol-function 'cj/emms--setup) #'ignore)
+              ((symbol-function 'cj/music-radio--search)
+               (lambda (query _field) (setq captured query) nil)))
+      (should-error (cj/music-radio--search-and-play "  jazz  " "tag")
+                    :type 'user-error))
+    (should (equal captured "jazz"))))
+
+(ert-deftest test-music-radio-search-and-play-whitespace-only-no-search ()
+  "Error: a whitespace-only query errors out before any network search."
+  (let (searched)
+    (cl-letf (((symbol-function 'cj/emms--setup) #'ignore)
+              ((symbol-function 'cj/music-radio--search)
+               (lambda (&rest _) (setq searched t) nil)))
+      (should-error (cj/music-radio--search-and-play "   " "tag")
+                    :type 'user-error))
+    (should-not searched)))
+
+;;; --------------------------- column alignment --------------------------------
+
+(ert-deftest test-music-radio-format-candidate-votes-column-fixed-width ()
+  "Normal: the votes field pads to a fixed width so the tags column aligns
+across stations with different vote counts."
+  (let* ((low (cj/music-radio--format-candidate
+               '(:codec "MP3" :bitrate 128 :countrycode "US" :votes 7 :tags "jazz")))
+         (high (cj/music-radio--format-candidate
+                '(:codec "MP3" :bitrate 128 :countrycode "US" :votes 174208 :tags "jazz"))))
+    (should (= (string-match "jazz" low) (string-match "jazz" high)))))
+
+(ert-deftest test-music-radio-affixate-aligns-annotation-column ()
+  "Normal: every annotation starts at the same display column regardless of
+how long the station name is."
+  (let* ((candidates '(("Short" . (:codec "MP3" :bitrate 128 :countrycode "US"
+                                   :votes 5 :tags "a"))
+                       ("A Much Longer Station Name" . (:codec "AAC" :bitrate 64
+                                                        :countrycode "FR" :votes 9 :tags "b"))))
+         (triples (cj/music-radio--affixate (mapcar #'car candidates) candidates))
+         (cols (mapcar (lambda (triple)
+                         (let ((cand (nth 0 triple))
+                               (suffix (nth 2 triple)))
+                           (string-match "[^ ]" suffix)
+                           (+ (string-width cand) (match-beginning 0))))
+                       triples)))
+    (should (= (length triples) 2))
+    (should (apply #'= cols))))
+
+(ert-deftest test-music-radio-affixate-done-sentinel-no-annotation ()
+  "Boundary: the [done] sentinel has no station and gets an empty suffix."
+  (let* ((candidates '(("[done]") ("Station" . (:codec "MP3" :bitrate 128
+                                                :countrycode "US" :votes 1 :tags "x"))))
+         (triples (cj/music-radio--affixate (mapcar #'car candidates) candidates)))
+    (should (equal (nth 2 (car triples)) ""))))
+
 (provide 'test-music-config--radio)
 ;;; test-music-config--radio.el ends here
diff --git a/tests/test-music-config--renumber-rows.el b/tests/test-music-config--renumber-rows.el
new file mode 100644
index 00000000..8abe1704
--- /dev/null
+++ b/tests/test-music-config--renumber-rows.el
@@ -0,0 +1,90 @@
+;;; test-music-config--renumber-rows.el --- Tests for playlist row numbering -*- coding: utf-8; lexical-binding: t; -*-
+;;
+;; Author: Craig Jennings <c@cjennings.net>
+;;
+;;; Commentary:
+;; Playlist rows carry a numeric overlay prefix so the cursor stays visible
+;; when it sits on a cover-art thumbnail and each row's position in the list
+;; is readable.  The renumber walks the buffer and rebuilds the overlays; a
+;; buffer-local after-change hook debounces it behind an idle timer.  Overlays
+;; leave the buffer text untouched (EMMS owns it), so these tests drive plain
+;; temp buffers.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(defvar cj/custom-keymap (make-sparse-keymap)
+  "Stub keymap for testing.")
+
+(require 'music-config)
+
+(defun test-music-renumber--numbers (buffer)
+  "Return the overlay number strings in BUFFER, in position order."
+  (with-current-buffer buffer
+    (mapcar (lambda (ov) (overlay-get ov 'before-string))
+            (sort (seq-filter (lambda (ov) (overlay-get ov 'cj-music-row-number))
+                              (overlays-in (point-min) (point-max)))
+                  (lambda (a b) (< (overlay-start a) (overlay-start b)))))))
+
+;;; Normal Cases
+
+(ert-deftest test-music-renumber-rows-numbers-each-line ()
+  "Normal: every non-blank line gets a sequential number overlay."
+  (with-temp-buffer
+    (insert "track one\ntrack two\ntrack three\n")
+    (cj/music--renumber-rows (current-buffer))
+    (should (equal (mapcar #'substring-no-properties
+                           (test-music-renumber--numbers (current-buffer)))
+                   '("  1 " "  2 " "  3 ")))))
+
+(ert-deftest test-music-renumber-rows-idempotent ()
+  "Normal: renumbering twice leaves one overlay per line, not two."
+  (with-temp-buffer
+    (insert "track one\ntrack two\n")
+    (cj/music--renumber-rows (current-buffer))
+    (cj/music--renumber-rows (current-buffer))
+    (should (= 2 (length (test-music-renumber--numbers (current-buffer)))))))
+
+;;; Boundary Cases
+
+(ert-deftest test-music-renumber-rows-skips-blank-lines ()
+  "Boundary: blank lines are not numbered and don't advance the count."
+  (with-temp-buffer
+    (insert "track one\n\ntrack two\n")
+    (cj/music--renumber-rows (current-buffer))
+    (should (equal (mapcar #'substring-no-properties
+                           (test-music-renumber--numbers (current-buffer)))
+                   '("  1 " "  2 ")))))
+
+(ert-deftest test-music-renumber-rows-empty-buffer-no-overlays ()
+  "Boundary: an empty buffer gets no overlays and no error."
+  (with-temp-buffer
+    (cj/music--renumber-rows (current-buffer))
+    (should-not (test-music-renumber--numbers (current-buffer)))))
+
+;;; Error Cases
+
+(ert-deftest test-music-renumber-rows-dead-buffer-noop ()
+  "Error: renumbering a killed buffer is a silent no-op (the debounce timer
+can fire after the playlist buffer is gone)."
+  (let ((buf (generate-new-buffer " *test-renumber-dead*")))
+    (kill-buffer buf)
+    (should-not (cj/music--renumber-rows buf))))
+
+;;; Hook wiring
+
+(ert-deftest test-music-renumber-ensure-playlist-buffer-wires-hook ()
+  "Normal: the playlist buffer gets the debounced renumber on after-change."
+  (let (created)
+    (cl-letf (((symbol-function 'emms-playlist-mode) #'ignore))
+      (unwind-protect
+          (progn
+            (setq created (cj/music--ensure-playlist-buffer))
+            (with-current-buffer created
+              (should (member #'cj/music--schedule-renumber after-change-functions))))
+        (when (buffer-live-p created) (kill-buffer created))))))
+
+(provide 'test-music-config--renumber-rows)
+;;; test-music-config--renumber-rows.el ends here