feat(vterm): F12 toggle that excludes claude and preserves geometry

vterm-toggle picked the most-recently-selected vterm buffer as F12's toggle target. After using F9 on a claude vterm, the most-recent vterm IS claude, so F12 ended up toggling claude, which has its own F9 / C-F9 / M-F9 surface in ai-vterm.el and shouldn't be affected. The display rule also had a hard-coded `(window-height . 0.7)` that overrode mouse-resize and orientation flips on every toggle.

I replaced the F12 binding with `cj/vterm-toggle` in `eshell-vterm-config.el`, mirroring the pattern shipped in ai-vterm.el:

- `cj/--vterm-toggle-buffer-p` excludes claude-prefixed buffers from F12's candidate set.
- `cj/--vterm-toggle-capture-state` records direction + body size at toggle-off.
- `cj/--vterm-toggle-display-saved` replays via `(body-columns . N)` / `(body-lines . N)` cons forms with the cardinal direction mapped to its frame-edge variant (`right` -> `rightmost`, `below` -> `bottom`, etc.) so vterm always lands at the captured edge regardless of selected window.
- `cj/vterm-toggle` uses `delete-window` (with `one-window-p` guard) on toggle-off so buffer-move scenarios don't leak ghost windows.

Default direction is `'below` to match F12's traditional bottom split. The vterm-toggle package stays installed so `M-x vterm-toggle` still works. Only the F12 binding changes.

19 new tests across three files: buffer-filter, dispatch, display. Full make test green.

Tradeoff: ~150 lines of geometry helpers and capture/display action logic are duplicated from ai-vterm.el. Worth extracting into a shared module now that two consumers exist. I filed it as a follow-up rather than blocking this ship.

1 files changed, 217 insertions, 19 deletions

diff --git a/modules/eshell-vterm-config.el b/modules/eshell-vterm-config.el
index 31c3a96e..ed257893 100644
--- a/modules/eshell-vterm-config.el
+++ b/modules/eshell-vterm-config.el
@@ -231,28 +231,226 @@ ai-vterm.el is loaded."
   :config
   (setq vterm-timer-delay nil))
 
+;; vterm-toggle is kept installed so `M-x vterm-toggle' still works,
+;; but F12 below is bound to a custom toggle (`cj/vterm-toggle') that
+;; excludes claude-prefixed buffers from its candidate set.
 (use-package vterm-toggle
   :defer .5
-  :bind
-  ("<f12>" . vterm-toggle)
   :config
-  (setq vterm-toggle-fullscreen-p nil)
-  ;; This rule covers F12 toggle-shells only.  AI-vterm buffers are named
-  ;; "claude [<repo>]" and have their own display rule in `ai-vterm.el'
-  ;; that puts them in a right-direction window without dedication.  The
-  ;; explicit "claude [" exclusion stops this rule from claiming them
-  ;; first when `:defer' makes vterm-toggle's :config run last.
-  (add-to-list 'display-buffer-alist
-			   '((lambda (buffer-or-name _)
-				   (let ((buffer (get-buffer buffer-or-name)))
-					 (with-current-buffer buffer
-					   (and (or (equal major-mode 'vterm-mode)
-								(string-prefix-p vterm-buffer-name (buffer-name buffer)))
-							(not (string-prefix-p "claude [" (buffer-name buffer)))))))
-				 (display-buffer-reuse-window display-buffer-at-bottom)
-				 (dedicated . t) ;dedicated is supported in Emacs 27+
-				 (reusable-frames . visible)
-				 (window-height . 0.7))))
+  (setq vterm-toggle-fullscreen-p nil))
+
+;; ----------------------- F12 toggle (custom) -----------------------
+;;
+;; Replacement for `vterm-toggle' on F12.  Two reasons to roll our own:
+;;
+;; 1. claude exclusion.  vterm-toggle picks the most-recently-selected
+;;    vterm buffer as the toggle target.  When the user just used F9
+;;    on a claude vterm, the most-recent vterm IS claude, so F12 ends
+;;    up toggling claude -- which has its own F9 / C-F9 / M-F9 surface
+;;    in `ai-vterm.el' and shouldn't be affected by F12.  The claude
+;;    exclusion lives in the candidate filter (`cj/--vterm-toggle-buffer-p').
+;;
+;; 2. user-modified geometry.  vterm-toggle's display rule had a
+;;    hard-coded `(window-height . 0.7)' that overrode any mouse-resize
+;;    or M-S-t orientation flip on the next toggle.  This module mirrors
+;;    the geometry-preservation pattern shipped in ai-vterm.el: capture
+;;    direction + body size at toggle-off, replay them via a custom
+;;    display action (`cj/--vterm-toggle-display-saved') that uses
+;;    frame-edge directions and `(body-columns . N)' / `(body-lines . N)'
+;;    so the result is divider-independent and layout-stable.
+
+(require 'cl-lib)
+(require 'seq)
+
+(defcustom cj/vterm-toggle-window-height 0.7
+  "Default fraction of frame height for the F12 vterm window.
+Used as the size fallback when `cj/--vterm-toggle-last-size' is nil
+(i.e. the user hasn't toggled off a vterm yet this session)."
+  :type 'number
+  :group 'vterm)
+
+(defvar cj/--vterm-toggle-last-direction nil
+  "Last user-chosen direction for the F12 vterm display.
+Symbol: right, left, below, above.  nil means use the default
+'below for F12's traditional bottom split.")
+
+(defvar cj/--vterm-toggle-last-size nil
+  "Last user-chosen body size for the F12 vterm display.
+Positive integer: body-cols (right/left) or body-lines (below/above).
+nil means fall back to `cj/vterm-toggle-window-height' as a fraction.")
+
+(defun cj/--vterm-toggle-buffer-p (buffer)
+  "Return non-nil when BUFFER is a vterm buffer F12 should manage.
+
+Qualifies when BUFFER is alive, has `vterm-mode' (or its name starts
+with the vterm-toggle prefix), AND its name does NOT start with the
+claude prefix used by ai-vterm.el.  The claude exclusion keeps F12
+from grabbing buffers that ai-vterm.el's F9 dispatch owns."
+  (and (bufferp buffer)
+       (buffer-live-p buffer)
+       (with-current-buffer buffer
+         (and (or (eq major-mode 'vterm-mode)
+                  (string-prefix-p (or (bound-and-true-p vterm-buffer-name)
+                                       "*vterm*")
+                                   (buffer-name buffer)))
+              (not (string-prefix-p "claude [" (buffer-name buffer)))))))
+
+(defun cj/--vterm-toggle-buffers ()
+  "Return live F12-managed vterm buffers in `buffer-list' (MRU) order."
+  (seq-filter #'cj/--vterm-toggle-buffer-p (buffer-list)))
+
+(defun cj/--vterm-toggle-displayed-window (&optional frame)
+  "Return a window in FRAME currently displaying an F12 vterm buffer, or nil.
+FRAME defaults to the selected frame.  Minibuffer is excluded."
+  (seq-find (lambda (w)
+              (cj/--vterm-toggle-buffer-p (window-buffer w)))
+            (window-list (or frame (selected-frame)) 'never)))
+
+(defun cj/--vterm-toggle-window-direction (window)
+  "Return the side WINDOW occupies in its frame.
+
+Returns one of right, below, left, above.  Falls back to 'below
+(F12's traditional bottom split) when WINDOW fills its frame's
+root area.  Comparison uses `frame-root-window' edges so the
+minibuffer doesn't make every full-area window look like it
+fails to span the full height."
+  (let* ((root (frame-root-window (window-frame window)))
+         (edges (window-edges window))
+         (root-edges (window-edges root))
+         (left (nth 0 edges))
+         (top (nth 1 edges))
+         (right (nth 2 edges))
+         (bottom (nth 3 edges))
+         (root-left (nth 0 root-edges))
+         (root-top (nth 1 root-edges))
+         (root-right (nth 2 root-edges))
+         (root-bottom (nth 3 root-edges))
+         (spans-full-width (and (= left root-left) (= right root-right)))
+         (spans-full-height (and (= top root-top) (= bottom root-bottom))))
+    (cond
+     ((not spans-full-width) (if (= left root-left) 'left 'right))
+     ((not spans-full-height) (if (= top root-top) 'above 'below))
+     (t 'below))))
+
+(defun cj/--vterm-toggle-window-size (window direction)
+  "Return WINDOW's body size in cols (right/left) or lines (below/above)."
+  (if (memq direction '(right left))
+      (window-body-width window)
+    (window-body-height window)))
+
+(defun cj/--vterm-toggle-capture-state (window)
+  "Capture WINDOW's direction + body size into module-level state."
+  (when (window-live-p window)
+    (let* ((dir (cj/--vterm-toggle-window-direction window))
+           (size (cj/--vterm-toggle-window-size window dir)))
+      (setq cj/--vterm-toggle-last-direction dir
+            cj/--vterm-toggle-last-size size))))
+
+(defun cj/--vterm-toggle-display-saved (buffer alist)
+  "Display-buffer action: split per saved direction and body size.
+
+Reads `cj/--vterm-toggle-last-direction' and
+`cj/--vterm-toggle-last-size', falling back to 'below and
+`cj/vterm-toggle-window-height' when nil.  The cardinal direction
+is mapped to its frame-edge variant (`right' -> `rightmost', etc.)
+so the new vterm always lands at the same frame edge it came from
+regardless of which window is selected.  An integer size is wrapped
+in a `(body-columns . N)' / `(body-lines . N)' cons so the body
+width or height is set explicitly, divider-independent.  A float
+size passes through as a fraction of the new window's parent."
+  (let* ((direction (or cj/--vterm-toggle-last-direction 'below))
+         (edge-direction (pcase direction
+                           ('right 'rightmost)
+                           ('left 'leftmost)
+                           ('below 'bottom)
+                           ('above 'top)
+                           (_ 'bottom)))
+         (size (or cj/--vterm-toggle-last-size cj/vterm-toggle-window-height))
+         (size-key (if (memq direction '(right left))
+                       'window-width
+                     'window-height))
+         (body-tag (if (memq direction '(right left))
+                       'body-columns
+                     'body-lines))
+         (size-value (if (integerp size)
+                         (cons body-tag size)
+                       size))
+         (filtered (cl-remove-if
+                    (lambda (cell)
+                      (memq (car-safe cell)
+                            '(direction window-width window-height)))
+                    alist))
+         (effective (append
+                     (list (cons 'direction edge-direction)
+                           (cons size-key size-value))
+                     filtered)))
+    (display-buffer-in-direction buffer effective)))
+
+(defun cj/--vterm-toggle-display-rule-list ()
+  "Return the `display-buffer-alist' entry list installed by F12.
+
+Routes any vterm buffer that satisfies `cj/--vterm-toggle-buffer-p'
+through two actions: reuse-window (for visible vterm windows) then
+the saved-geometry display action.  Excludes claude buffers via the
+predicate -- those are handled by ai-vterm.el's display rule."
+  '(((lambda (buffer-or-name _)
+       (cj/--vterm-toggle-buffer-p (get-buffer buffer-or-name)))
+     (display-buffer-reuse-window
+      cj/--vterm-toggle-display-saved)
+     (inhibit-same-window . t))))
+
+(dolist (entry (cj/--vterm-toggle-display-rule-list))
+  (add-to-list 'display-buffer-alist entry))
+
+(defun cj/--vterm-toggle-dispatch ()
+  "Compute the F12 (`cj/vterm-toggle') action without performing it.
+
+Returns one of:
+- (toggle-off . WINDOW)        -- vterm displayed in WINDOW; hide it.
+- (show-recent . BUFFER)       -- vterm alive but not shown; redisplay.
+- (create-new)                 -- no vterm buffer alive; create one."
+  (let ((win (cj/--vterm-toggle-displayed-window)))
+    (cond
+     (win (cons 'toggle-off win))
+     (t
+      (let ((buffers (cj/--vterm-toggle-buffers)))
+        (cond
+         (buffers (cons 'show-recent (car buffers)))
+         (t '(create-new))))))))
+
+(declare-function vterm "vterm" (&optional buffer-name))
+
+(defun cj/vterm-toggle ()
+  "Toggle a normal (non-claude) vterm buffer.
+
+- If an F12-managed vterm is currently displayed in this frame,
+  capture its geometry and delete its window (toggle off).  Falls
+  back to burying the buffer when the vterm is the only window in
+  the frame.
+- Otherwise, if any F12-managed vterm buffer is alive, display the
+  most-recent one via the saved-geometry action.
+- Otherwise, create a new vterm via `(vterm)' which routes through
+  the same display action.
+
+Excludes claude-prefixed vterm buffers; those have their own F9 /
+C-F9 / M-F9 dispatch via `cj/ai-vterm'."
+  (interactive)
+  (pcase (cj/--vterm-toggle-dispatch)
+    (`(toggle-off . ,win)
+     (cj/--vterm-toggle-capture-state win)
+     (if (one-window-p)
+         (bury-buffer (window-buffer win))
+       (delete-window win))
+     nil)
+    (`(show-recent . ,buf)
+     (display-buffer buf)
+     (let ((w (get-buffer-window buf)))
+       (when w (select-window w)))
+     buf)
+    (`(create-new)
+     (vterm))))
+
+(keymap-global-set "<f12>" #'cj/vterm-toggle)
 
 (provide 'eshell-vterm-config)
 ;;; eshell-vterm-config.el ends here.