feat(windows): dock companion panels by a shared min-column rule

The F9 agent always docked as a right-side column on a landscape frame. On this 138-column frame that left ~68-column panes, too cramped to read code and the agent side by side. The F12 terminal and F10 playlist hardcoded a bottom split with no width-aware path.

I added cj/preferred-dock-direction and the cj/window-dock-min-columns defcustom (default 80) to the window-geometry lib: dock side-by-side only when the narrower pane keeps at least the minimum width, otherwise stack below. All three toggles now route through it. F9 drops its pixel-aspect rule. F12 and F10 gain a right-column width default and become adaptive. F10 keeps width and height size memory in separate vars so a resize on one axis doesn't leak to the other.

8 files changed, 269 insertions, 47 deletions

diff --git a/modules/ai-term.el b/modules/ai-term.el
index 49d44d25e..8dfd5e370 100644
--- a/modules/ai-term.el
+++ b/modules/ai-term.el
@@ -391,21 +391,17 @@ fallback when `cj/--ai-term-last-size' is nil."
   :type 'number
   :group 'ai-term)
 
-(defun cj/--ai-term-direction-for-aspect (pixel-width pixel-height)
-  "Return the space-conserving dock direction for a frame of PIXEL-WIDTH by
-PIXEL-HEIGHT.  `right' when the frame is wider than tall (dock from the right
-edge), `below' when it is square or taller (dock from the bottom)."
-  (if (> pixel-width pixel-height) 'right 'below))
-
 (defun cj/--ai-term-default-direction (&optional frame)
   "Return the default split direction for the agent window.
 
-Chosen at display time from FRAME's pixel aspect ratio (FRAME defaults to the
-selected frame): `right' on a landscape frame, `below' on a square or portrait
-one -- whichever edge conserves more screen space."
+Chosen at display time from FRAME's column width (FRAME defaults to the
+selected frame): `right' when a side-by-side split would leave both the
+agent and the main window at least `cj/window-dock-min-columns' wide,
+`below' otherwise.  The agent's share of the width is
+`cj/ai-term-desktop-width'.  See `cj/preferred-dock-direction'."
   (let ((frame (or frame (selected-frame))))
-    (cj/--ai-term-direction-for-aspect (frame-pixel-width frame)
-                                       (frame-pixel-height frame))))
+    (cj/preferred-dock-direction (frame-width frame)
+                                 cj/ai-term-desktop-width)))
 
 (defun cj/--ai-term-default-size ()
   "Return the default size fraction paired with the chosen direction.
diff --git a/modules/cj-window-geometry-lib.el b/modules/cj-window-geometry-lib.el
index 047fe7c45..4c0662124 100644
--- a/modules/cj-window-geometry-lib.el
+++ b/modules/cj-window-geometry-lib.el
@@ -129,5 +129,39 @@ the fraction at toggle-off, replay it on the next toggle-on."
           (hi (or max-frac 0.95)))
       (max lo (min hi (/ (float window-size) frame-size))))))
 
+(defcustom cj/window-dock-min-columns 80
+  "Minimum body columns each pane must keep for a side-by-side dock.
+
+`cj/preferred-dock-direction' docks a companion panel as a side-by-side
+column only when both the panel and the main window would stay at least
+this wide; otherwise it stacks the panel below.  80 is the classic
+terminal/code width."
+  :type 'integer
+  :group 'windows)
+
+(defun cj/preferred-dock-direction (frame-cols fraction &optional min-cols)
+  "Return the dock direction for a companion panel beside the main window.
+
+Returns `right' (a side-by-side column) when a split that gives the panel
+FRACTION of FRAME-COLS would leave both panes at least MIN-COLS columns
+wide; otherwise `below' (a stacked panel).  FRAME-COLS is the frame's
+total column count; FRACTION is the panel's share of the width, in the
+open interval (0, 1).  MIN-COLS defaults to `cj/window-dock-min-columns'.
+
+The narrower of the two resulting panes governs: the panel takes
+round(FRACTION * FRAME-COLS) columns, the main window takes the rest less
+one divider column, and `right' is returned only when the smaller of the
+two clears MIN-COLS.  Returns `below' for degenerate input (non-positive
+FRAME-COLS, or FRACTION outside (0, 1)) so a caller always gets a usable
+stacked fallback."
+  (let ((min-cols (or min-cols cj/window-dock-min-columns)))
+    (if (and (numberp frame-cols) (> frame-cols 0)
+             (numberp fraction) (< 0 fraction 1))
+        (let* ((panel (round (* fraction frame-cols)))
+               (main (- frame-cols panel 1))
+               (narrower (min panel main)))
+          (if (>= narrower min-cols) 'right 'below))
+      'below)))
+
 (provide 'cj-window-geometry-lib)
 ;;; cj-window-geometry-lib.el ends here
diff --git a/modules/music-config.el b/modules/music-config.el
index be836429b..55eb47d25 100644
--- a/modules/music-config.el
+++ b/modules/music-config.el
@@ -94,6 +94,7 @@
 (require 'subr-x)
 (require 'user-constants)
 (require 'keybindings)  ;; provides cj/custom-keymap
+(require 'cj-window-geometry-lib) ;; cj/preferred-dock-direction (F10 dock side)
 (require 'cj-window-toggle-lib)  ;; side-window size memory (F10 toggle)
 (require 'system-lib)            ;; cj/confirm-strong (overwrite confirms)
 
@@ -517,14 +518,38 @@ Intended for use on `emms-player-finished-hook'."
 
 (defvar cj/music-playlist-window-height 0.3
   "Default fraction of frame height for the F10 music playlist side window.
-Used until the playlist is resized and toggled off this session; after that,
-the toggled-off height is remembered in `cj/--music-playlist-height'.")
+Used when the playlist docks at the bottom and hasn't been resized and
+toggled off this session; after that, the toggled-off height is remembered
+in `cj/--music-playlist-height'.")
+
+(defvar cj/music-playlist-window-width 0.4
+  "Default fraction of frame width for the F10 music playlist side window.
+Used when the playlist docks as a right-side column (see
+`cj/--music-playlist-side') and hasn't been resized this session; after
+that the toggled-off width is remembered in `cj/--music-playlist-width'.")
 
 (defvar cj/--music-playlist-height nil
-  "Last height fraction the playlist side window was toggled off at.
+  "Last height fraction the playlist was toggled off at while docked bottom.
 nil means fall back to `cj/music-playlist-window-height'.  In-memory only --
 resets each Emacs session.")
 
+(defvar cj/--music-playlist-width nil
+  "Last width fraction the playlist was toggled off at while docked right.
+nil means fall back to `cj/music-playlist-window-width'.  In-memory only --
+resets each Emacs session.")
+
+(defun cj/--music-playlist-side ()
+  "Return the side the F10 playlist should dock on: `right' or `bottom'.
+Docks as a right-side column only when a side-by-side split would leave
+both panes at least `cj/window-dock-min-columns' wide (the playlist's
+share is `cj/music-playlist-window-width'); otherwise docks at the bottom.
+See `cj/preferred-dock-direction'."
+  (if (eq (cj/preferred-dock-direction (frame-width)
+                                       cj/music-playlist-window-width)
+          'right)
+      'right
+    'bottom))
+
 (defun cj/music-playlist-toggle ()
   "Toggle the EMMS playlist buffer in a bottom side window.
 The window opens at `cj/music-playlist-window-height'; if it has been
@@ -535,15 +560,28 @@ resized and toggled off this session, it reopens at that remembered height."
          (win (and buffer (get-buffer-window buffer))))
     (if win
         (progn
-          (cj/side-window-capture-size win 'bottom 'cj/--music-playlist-height)
+          ;; Capture the resized size into the var matching the window's
+          ;; actual side, so width and height memories stay independent.
+          ;; Guard the parameter lookup: a dead or non-window WIN (the
+          ;; capture helpers tolerate one) must not error here.
+          (let ((side (if (window-live-p win)
+                          (or (window-parameter win 'window-side) 'bottom)
+                        'bottom)))
+            (if (memq side '(left right))
+                (cj/side-window-capture-size win side 'cj/--music-playlist-width)
+              (cj/side-window-capture-size win 'bottom 'cj/--music-playlist-height)))
           (delete-window win)
           (message "Playlist window closed"))
       (progn
         (cj/emms--setup)
         (setq buffer (cj/music--ensure-playlist-buffer))
-        (setq win (cj/side-window-display
-                   buffer 'bottom 'cj/--music-playlist-height
-                   cj/music-playlist-window-height))
+        (let* ((side (cj/--music-playlist-side))
+               (right (eq side 'right)))
+          (setq win (cj/side-window-display
+                     buffer side
+                     (if right 'cj/--music-playlist-width 'cj/--music-playlist-height)
+                     (if right cj/music-playlist-window-width
+                       cj/music-playlist-window-height))))
         (select-window win)
         (with-current-buffer buffer
           (if (and (fboundp 'emms-playlist-current-selected-track)
diff --git a/modules/term-config.el b/modules/term-config.el
index fe2ead409..33f54d75a 100644
--- a/modules/term-config.el
+++ b/modules/term-config.el
@@ -279,10 +279,34 @@ run its own project-named tmux session instead of a bare, auto-named one.
 ;; which ai-term.el owns via F9.
 
 (defcustom cj/term-toggle-window-height 0.7
-  "Default fraction of frame height for the F12 terminal window."
+  "Default fraction of frame height for the F12 terminal window.
+Used as the size fallback when F12 docks the terminal as a bottom split."
   :type 'number
   :group 'term)
 
+(defcustom cj/term-toggle-window-width 0.5
+  "Default fraction of frame width for the F12 terminal window.
+Used as the size fallback when F12 docks the terminal as a right-side
+column (see `cj/--term-toggle-default-direction')."
+  :type 'number
+  :group 'term)
+
+(defun cj/--term-toggle-default-direction ()
+  "Return the default dock direction for the F12 terminal: `right' or `below'.
+Docks as a right-side column only when a side-by-side split would leave
+both panes at least `cj/window-dock-min-columns' wide (the terminal's
+share is `cj/term-toggle-window-width'); otherwise stacks below.  See
+`cj/preferred-dock-direction'."
+  (cj/preferred-dock-direction (frame-width) cj/term-toggle-window-width))
+
+(defun cj/--term-toggle-default-size (direction)
+  "Return the default size fraction paired with DIRECTION for the F12 terminal.
+`cj/term-toggle-window-width' for `right', `cj/term-toggle-window-height'
+otherwise."
+  (if (eq direction 'right)
+      cj/term-toggle-window-width
+    cj/term-toggle-window-height))
+
 (defvar cj/--term-toggle-last-direction nil
   "Last user-chosen direction for the F12 terminal display.
 Symbol: right, left, or below.  `above' is never stored.  nil means use the
@@ -321,9 +345,10 @@ FRAME defaults to the selected frame.  Minibuffer is excluded."
 
 (defun cj/--term-toggle-capture-state (window)
   "Capture WINDOW's direction + body size into module-level state.
-Default direction is `below' to match F12's traditional bottom split."
+The default direction (used when WINDOW fills its frame) is the
+column-rule choice from `cj/--term-toggle-default-direction'."
   (cj/window-toggle-capture-state
-   window 'below
+   window (cj/--term-toggle-default-direction)
    'cj/--term-toggle-last-direction
    'cj/--term-toggle-last-size
    '(right below left)))
@@ -331,11 +356,13 @@ Default direction is `below' to match F12's traditional bottom split."
 (defun cj/--term-toggle-display-saved (buffer alist)
   "Display-buffer action: split per saved direction and body size.
 Delegates to `cj/window-toggle-display-saved' against the F12 state vars,
-falling back to `below' and `cj/term-toggle-window-height'."
-  (cj/window-toggle-display-saved
-   buffer alist
-   'cj/--term-toggle-last-direction 'below
-   'cj/--term-toggle-last-size cj/term-toggle-window-height))
+falling back to the column-rule default direction
+\(`cj/--term-toggle-default-direction') and its paired size."
+  (let ((dir (cj/--term-toggle-default-direction)))
+    (cj/window-toggle-display-saved
+     buffer alist
+     'cj/--term-toggle-last-direction dir
+     'cj/--term-toggle-last-size (cj/--term-toggle-default-size dir))))
 
 (defun cj/--term-toggle-display-rule-list ()
   "Return the `display-buffer-alist' entry list installed by F12.
diff --git a/tests/test-ai-term--default-geometry.el b/tests/test-ai-term--default-geometry.el
index 91013862d..1180c1979 100644
--- a/tests/test-ai-term--default-geometry.el
+++ b/tests/test-ai-term--default-geometry.el
@@ -1,18 +1,20 @@
 ;;; test-ai-term--default-geometry.el --- Tests for host-aware display defaults -*- lexical-binding: t; -*-
 
 ;;; Commentary:
-;; ai-term's default display geometry is chosen from the frame's pixel aspect
-;; ratio: a landscape frame docks the agent from the right (a width fraction), a
-;; square or portrait frame docks it from the bottom (a height fraction).
-;; `cj/--ai-term-direction-for-aspect' is the pure decision;
-;; `cj/--ai-term-default-direction' reads the frame and delegates to it;
-;; `cj/--ai-term-default-size' pairs the size fraction with that direction.
-;; They feed the default fallbacks in `cj/--ai-term-capture-state' and
-;; `cj/--ai-term-display-saved'.
+;; ai-term's default display geometry is chosen from the frame's column
+;; width: the agent docks from the right (a width fraction) only when a
+;; side-by-side split would leave both panes at least
+;; `cj/window-dock-min-columns' wide, otherwise from the bottom (a height
+;; fraction).  `cj/--ai-term-default-direction' reads the frame width and
+;; delegates the decision to `cj/preferred-dock-direction' (tested in
+;; test-cj-window-geometry-lib.el); `cj/--ai-term-default-size' pairs the
+;; size fraction with that direction.  They feed the default fallbacks in
+;; `cj/--ai-term-capture-state' and `cj/--ai-term-display-saved'.
 ;;
-;; The direction is tested on the pure helper (no frame mocking, which would
-;; trip the native-comp trampoline trap on the frame-pixel-* subrs); the size
-;; helper is tested by stubbing the direction defun.
+;; The direction is tested by stubbing `cj/preferred-dock-direction' (an
+;; ordinary defun -- safe to `cl-letf', unlike the frame-* subrs, which
+;; would trip the native-comp trampoline trap); the size helper is tested
+;; by stubbing the direction defun.
 
 ;;; Code:
 
@@ -22,17 +24,26 @@
 (add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
 (require 'ai-term)
 
-(ert-deftest test-ai-term--direction-for-aspect-landscape-is-right ()
-  "Normal: a wider-than-tall frame docks from the right."
-  (should (eq (cj/--ai-term-direction-for-aspect 1920 1080) 'right)))
+(ert-deftest test-ai-term--default-direction-delegates-to-dock-rule ()
+  "Normal: default-direction passes the desktop-width fraction to the dock rule
+and returns its verdict."
+  (let ((cj/ai-term-desktop-width 0.5)
+        captured)
+    (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+               (lambda (cols frac &rest _)
+                 (setq captured (list cols frac))
+                 'below)))
+      (should (eq (cj/--ai-term-default-direction) 'below))
+      ;; the fraction passed is the agent's desktop-width
+      (should (= (nth 1 captured) 0.5))
+      ;; the first argument is a column count (the frame width)
+      (should (integerp (nth 0 captured))))))
 
-(ert-deftest test-ai-term--direction-for-aspect-portrait-is-below ()
-  "Normal: a taller-than-wide frame docks from the bottom."
-  (should (eq (cj/--ai-term-direction-for-aspect 1080 1920) 'below)))
-
-(ert-deftest test-ai-term--direction-for-aspect-square-is-below ()
-  "Boundary: a square frame docks from the bottom (the conserving tie-break)."
-  (should (eq (cj/--ai-term-direction-for-aspect 1000 1000) 'below)))
+(ert-deftest test-ai-term--default-direction-returns-right-when-rule-says ()
+  "Normal: when the dock rule returns `right', so does default-direction."
+  (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+             (lambda (&rest _) 'right)))
+    (should (eq (cj/--ai-term-default-direction) 'right))))
 
 (ert-deftest test-ai-term--default-size-pairs-width-with-right ()
   "Normal: when the direction is `right' the size is the width fraction."
diff --git a/tests/test-cj-window-geometry-lib.el b/tests/test-cj-window-geometry-lib.el
index 05ed95950..938749f21 100644
--- a/tests/test-cj-window-geometry-lib.el
+++ b/tests/test-cj-window-geometry-lib.el
@@ -197,5 +197,52 @@ window forms the full-height right half -> nil."
   (should (null (cj/window-size-fraction nil 40)))
   (should (null (cj/window-size-fraction 20 nil))))
 
+;; ----------------------------- preferred-dock-direction -----------------------------
+
+(ert-deftest test-cj-window-geometry-dock-wide-frame-is-right ()
+  "Normal: a frame wide enough for both panes to clear 80 docks right."
+  (should (eq (cj/preferred-dock-direction 200 0.5) 'right)))
+
+(ert-deftest test-cj-window-geometry-dock-narrow-frame-is-below ()
+  "Normal: an 0.5 split on a 138-col frame leaves ~68-col panes -> below."
+  (should (eq (cj/preferred-dock-direction 138 0.5) 'below)))
+
+(ert-deftest test-cj-window-geometry-dock-boundary-exactly-min-is-right ()
+  "Boundary: when the narrower pane lands exactly on 80, dock right."
+  ;; 161 cols, 0.5: panel 80, main 161-80-1 = 80, narrower 80 -> right.
+  (should (eq (cj/preferred-dock-direction 161 0.5) 'right)))
+
+(ert-deftest test-cj-window-geometry-dock-boundary-one-under-min-is-below ()
+  "Boundary: one column short of the floor stacks instead."
+  ;; 160 cols, 0.5: panel 80, main 160-80-1 = 79, narrower 79 -> below.
+  (should (eq (cj/preferred-dock-direction 160 0.5) 'below)))
+
+(ert-deftest test-cj-window-geometry-dock-narrow-panel-fraction-governs ()
+  "Normal: a slim panel fraction makes the panel the narrower pane."
+  ;; 200 cols, 0.3: panel 60 < 80 -> below, even though main (139) is wide.
+  (should (eq (cj/preferred-dock-direction 200 0.3) 'below))
+  ;; 300 cols, 0.3: panel 90, main 209 -> right.
+  (should (eq (cj/preferred-dock-direction 300 0.3) 'right)))
+
+(ert-deftest test-cj-window-geometry-dock-honors-explicit-min-cols ()
+  "Boundary: an explicit MIN-COLS overrides the default floor."
+  ;; 138 cols, 0.5 -> ~68-col panes: passes a 60-floor, fails the 80-default.
+  (should (eq (cj/preferred-dock-direction 138 0.5 60) 'right))
+  (should (eq (cj/preferred-dock-direction 138 0.5 80) 'below)))
+
+(ert-deftest test-cj-window-geometry-dock-honors-custom-default-var ()
+  "Boundary: the default floor reads `cj/window-dock-min-columns'."
+  (let ((cj/window-dock-min-columns 30))
+    (should (eq (cj/preferred-dock-direction 138 0.5) 'right))))
+
+(ert-deftest test-cj-window-geometry-dock-degenerate-input-is-below ()
+  "Error: non-positive cols or out-of-range fraction stacks (safe fallback)."
+  (should (eq (cj/preferred-dock-direction 0 0.5) 'below))
+  (should (eq (cj/preferred-dock-direction -10 0.5) 'below))
+  (should (eq (cj/preferred-dock-direction 200 0) 'below))
+  (should (eq (cj/preferred-dock-direction 200 1) 'below))
+  (should (eq (cj/preferred-dock-direction nil 0.5) 'below))
+  (should (eq (cj/preferred-dock-direction 200 nil) 'below)))
+
 (provide 'test-cj-window-geometry-lib)
 ;;; test-cj-window-geometry-lib.el ends here
diff --git a/tests/test-music-config--playlist-side.el b/tests/test-music-config--playlist-side.el
new file mode 100644
index 000000000..f49694690
--- /dev/null
+++ b/tests/test-music-config--playlist-side.el
@@ -0,0 +1,45 @@
+;;; test-music-config--playlist-side.el --- Tests for the F10 dock-side helper -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; `cj/--music-playlist-side' maps the shared dock rule's verdict to a
+;; `display-buffer-in-side-window' side: `right' stays `right', anything
+;; else becomes `bottom'.  The decision itself lives in
+;; `cj/preferred-dock-direction' (tested in test-cj-window-geometry-lib.el);
+;; here we stub it (an ordinary defun -- safe to `cl-letf', unlike the
+;; frame-* subrs) to prove the mapping and that the width fraction is
+;; passed through.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'music-config)
+
+(ert-deftest test-music-config--playlist-side-right-verdict-is-right ()
+  "Normal: a `right' verdict from the dock rule docks the playlist right."
+  (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+             (lambda (&rest _) 'right)))
+    (should (eq (cj/--music-playlist-side) 'right))))
+
+(ert-deftest test-music-config--playlist-side-below-verdict-is-bottom ()
+  "Normal: a `below' verdict maps to the `bottom' side window."
+  (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+             (lambda (&rest _) 'below)))
+    (should (eq (cj/--music-playlist-side) 'bottom))))
+
+(ert-deftest test-music-config--playlist-side-passes-width-fraction ()
+  "Normal: the playlist's width fraction reaches the dock rule."
+  (let ((cj/music-playlist-window-width 0.4)
+        captured)
+    (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+               (lambda (cols frac &rest _)
+                 (setq captured (list cols frac))
+                 'below)))
+      (cj/--music-playlist-side)
+      (should (= (nth 1 captured) 0.4))
+      (should (integerp (nth 0 captured))))))
+
+(provide 'test-music-config--playlist-side)
+;;; test-music-config--playlist-side.el ends here
diff --git a/tests/test-term-toggle--display.el b/tests/test-term-toggle--display.el
index 0943a4888..7fa7f0a98 100644
--- a/tests/test-term-toggle--display.el
+++ b/tests/test-term-toggle--display.el
@@ -83,5 +83,29 @@
                      received-alist)))
       (should (null wh-cells)))))
 
+(ert-deftest test-term-toggle--default-size-pairs-width-with-right ()
+  "Normal: the default size for `right' is the width fraction."
+  (let ((cj/term-toggle-window-width 0.5)
+        (cj/term-toggle-window-height 0.7))
+    (should (= (cj/--term-toggle-default-size 'right) 0.5))))
+
+(ert-deftest test-term-toggle--default-size-pairs-height-with-below ()
+  "Normal: the default size for `below' is the height fraction."
+  (let ((cj/term-toggle-window-width 0.5)
+        (cj/term-toggle-window-height 0.7))
+    (should (= (cj/--term-toggle-default-size 'below) 0.7))))
+
+(ert-deftest test-term-toggle--default-direction-delegates-to-dock-rule ()
+  "Normal: default-direction passes the width fraction to the dock rule."
+  (let ((cj/term-toggle-window-width 0.5)
+        captured)
+    (cl-letf (((symbol-function 'cj/preferred-dock-direction)
+               (lambda (cols frac &rest _)
+                 (setq captured (list cols frac))
+                 'right)))
+      (should (eq (cj/--term-toggle-default-direction) 'right))
+      (should (= (nth 1 captured) 0.5))
+      (should (integerp (nth 0 captured))))))
+
 (provide 'test-term-toggle--display)
 ;;; test-term-toggle--display.el ends here