feat(music): freeze the playlist header while the track list scrolls

The header block (playlist name, now-playing hero, key legend) is an overlay string anchored at buffer position 1, so scrolling the list carried it off the top, key legend included. A handler on the buffer-local window-scroll-functions re-anchors the overlay at the window's display start on every scroll, so the block stays pinned at the top of the window. The header refresh timer now anchors at the same position instead of the buffer top, so the once-a-second update can't yank a scrolled header back.

2 files changed, 87 insertions, 3 deletions

diff --git a/modules/music-config.el b/modules/music-config.el
index 10aa1019..e9095838 100644
--- a/modules/music-config.el
+++ b/modules/music-config.el
@@ -471,7 +471,10 @@ inserts or kills into one renumber pass."
       ;; motion walks the header's screen lines, which all map back to the
       ;; same buffer position, so arrows look dead).  Rows are one logical
       ;; line each; visual movement buys nothing here.
-      (setq-local line-move-visual nil))
+      (setq-local line-move-visual nil)
+      ;; Sticky header: re-anchor the header block at the window start on
+      ;; every scroll, so it stays frozen while the list scrolls under it.
+      (add-hook 'window-scroll-functions #'cj/music--stick-header nil t))
     (cj/music--renumber-rows buffer)
     ;; Set this as the current EMMS playlist buffer
     (setq emms-playlist-buffer buffer)
@@ -1392,14 +1395,45 @@ the controls."
       (cj/music--fancy-header)
     (cj/music--text-header)))
 
+(defun cj/music--header-anchor-position ()
+  "Return the position the header overlay should anchor at right now.
+The start of the displaying window when the playlist is shown (so the
+header stays at the top of the window while the list scrolls under it),
+else the top of the buffer.  Searches all frames -- the refresh timer can
+run with any frame selected, and missing a window on another frame would
+anchor at the buffer top and yank a scrolled header back."
+  (if-let ((win (get-buffer-window (current-buffer) t)))
+      (max (point-min) (min (window-start win) (point-max)))
+    (point-min)))
+
+(defun cj/music--stick-header (win start)
+  "Re-anchor the header overlay at START, WIN's new display start.
+Runs on the buffer-local `window-scroll-functions', so every scroll pins
+the header block to the top of the window and the track list scrolls
+beneath it.  Converges: an already-anchored header is a no-op, so the
+redisplay this move triggers doesn't loop.  Always returns nil."
+  (with-current-buffer (window-buffer win)
+    (when (and (overlayp cj/music--header-overlay)
+               (overlay-buffer cj/music--header-overlay)
+               (integer-or-marker-p start))
+      (let ((pos (max (point-min) (min start (point-max)))))
+        (unless (= (overlay-start cj/music--header-overlay) pos)
+          (move-overlay cj/music--header-overlay pos pos))))
+    nil))
+
 (defun cj/music--update-header ()
-  "Insert or update the multi-line header overlay in the playlist buffer."
+  "Insert or update the multi-line header overlay in the playlist buffer.
+Anchors at the displaying window's start (see
+`cj/music--header-anchor-position') -- the refresh timer calls this every
+second, and re-anchoring at the buffer top would yank the sticky header
+away whenever the list is scrolled."
   (when-let ((buf (get-buffer cj/music-playlist-buffer-name)))
     (with-current-buffer buf
       (unless cj/music--header-overlay
         (setq cj/music--header-overlay (make-overlay (point-min) (point-min)))
         (overlay-put cj/music--header-overlay 'priority 100))
-      (move-overlay cj/music--header-overlay (point-min) (point-min))
+      (let ((pos (cj/music--header-anchor-position)))
+        (move-overlay cj/music--header-overlay pos pos))
       (overlay-put cj/music--header-overlay 'before-string
                    (cj/music--header-text)))))
 
diff --git a/tests/test-music-config--renumber-rows.el b/tests/test-music-config--renumber-rows.el
index a5304606..d5bc5141 100644
--- a/tests/test-music-config--renumber-rows.el
+++ b/tests/test-music-config--renumber-rows.el
@@ -165,6 +165,56 @@ selected -- the dock is glanced at from other windows constantly."
             (should (buffer-local-value 'hl-line-sticky-flag created)))
         (when (buffer-live-p created) (kill-buffer created))))))
 
+;;; Sticky header
+
+(ert-deftest test-music-stick-header-moves-overlay-to-window-start ()
+  "Normal: a scroll re-anchors the header overlay at the new window start,
+so the header block stays at the top of the window while the list scrolls."
+  (with-temp-buffer
+    (insert "track one\ntrack two\ntrack three\ntrack four\n")
+    (setq cj/music--header-overlay (make-overlay (point-min) (point-min)))
+    (save-window-excursion
+      (set-window-buffer (selected-window) (current-buffer))
+      (let ((start (save-excursion (goto-char (point-min)) (forward-line 2) (point))))
+        (cj/music--stick-header (selected-window) start)
+        (should (= (overlay-start cj/music--header-overlay) start))
+        ;; Converges: the same start again is a no-op, not a loop.
+        (cj/music--stick-header (selected-window) start)
+        (should (= (overlay-start cj/music--header-overlay) start))))))
+
+(ert-deftest test-music-stick-header-no-overlay-noop ()
+  "Boundary: no header overlay yet -- the scroll handler is a silent no-op."
+  (with-temp-buffer
+    (insert "track one\n")
+    (setq cj/music--header-overlay nil)
+    (save-window-excursion
+      (set-window-buffer (selected-window) (current-buffer))
+      (should-not (cj/music--stick-header (selected-window) (point-min))))))
+
+(ert-deftest test-music-header-anchor-position-displayed-vs-not ()
+  "Normal: the header anchors at the displaying window's start; an
+undisplayed buffer anchors at the top."
+  (with-temp-buffer
+    (insert "track one\ntrack two\ntrack three\ntrack four\n")
+    (save-window-excursion
+      (set-window-buffer (selected-window) (current-buffer))
+      (let ((start (save-excursion (goto-char (point-min)) (forward-line 2) (point))))
+        (set-window-start (selected-window) start)
+        (should (= (cj/music--header-anchor-position) start))))
+    ;; Not displayed after the excursion restores the old config.
+    (should (= (cj/music--header-anchor-position) (point-min)))))
+
+(ert-deftest test-music-ensure-playlist-buffer-wires-scroll-hook ()
+  "Normal: the playlist buffer re-sticks its header on every window scroll."
+  (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--stick-header window-scroll-functions))))
+        (when (buffer-live-p created) (kill-buffer created))))))
+
 ;;; Hook wiring
 
 (ert-deftest test-music-renumber-ensure-playlist-buffer-wires-hook ()