From 554b32db5da9630fa24fb2abf3f93f21b03ff7a0 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 9 May 2026 11:58:52 -0500 Subject: 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. --- modules/eshell-vterm-config.el | 236 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 217 insertions(+), 19 deletions(-) (limited to 'modules/eshell-vterm-config.el') 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 - ("" . vterm-toggle) :config - (setq vterm-toggle-fullscreen-p nil) - ;; This rule covers F12 toggle-shells only. AI-vterm buffers are named - ;; "claude []" 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 "" #'cj/vterm-toggle) (provide 'eshell-vterm-config) ;;; eshell-vterm-config.el ends here. -- cgit v1.2.3