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.

3 files changed, 277 insertions, 0 deletions

diff --git a/tests/test-vterm-toggle--buffer-filter.el b/tests/test-vterm-toggle--buffer-filter.el
new file mode 100644
index 00000000..8deb9066
--- /dev/null
+++ b/tests/test-vterm-toggle--buffer-filter.el
@@ -0,0 +1,103 @@
+;;; test-vterm-toggle--buffer-filter.el --- Tests for F12's buffer filter -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Three closely-related helpers determine which vterm buffers F12
+;; manages: the predicate `cj/--vterm-toggle-buffer-p', the MRU list
+;; `cj/--vterm-toggle-buffers', and the per-frame window finder
+;; `cj/--vterm-toggle-displayed-window'.  All three exclude claude-
+;; prefixed buffers so claude has its own F9 surface.
+
+;;; Code:
+
+(require 'ert)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'eshell-vterm-config)
+
+(defun test-vterm-toggle--cleanup ()
+  "Kill any test-prefixed vterm-style buffers left behind."
+  (dolist (b (buffer-list))
+    (let ((name (buffer-name b)))
+      (when (or (string-prefix-p "*test-vterm" name)
+                (string-prefix-p "claude [" name))
+        (kill-buffer b)))))
+
+(defun test-vterm-toggle--make-vterm-buffer (name)
+  "Create BUFFER with vterm-mode for testing.
+Avoids actually launching a vterm process by manually setting major-mode."
+  (let ((buf (get-buffer-create name)))
+    (with-current-buffer buf
+      (setq-local major-mode 'vterm-mode))
+    buf))
+
+(ert-deftest test-vterm-toggle--buffer-p-accepts-vterm-mode ()
+  "Normal: a vterm-mode buffer with non-claude name qualifies."
+  (test-vterm-toggle--cleanup)
+  (let ((buf (test-vterm-toggle--make-vterm-buffer "*test-vterm-1*")))
+    (unwind-protect
+        (should (cj/--vterm-toggle-buffer-p buf))
+      (kill-buffer buf))))
+
+(ert-deftest test-vterm-toggle--buffer-p-rejects-claude ()
+  "Boundary: claude-prefixed vterm buffers are excluded from F12's set."
+  (test-vterm-toggle--cleanup)
+  (let ((buf (test-vterm-toggle--make-vterm-buffer "claude [project-a]")))
+    (unwind-protect
+        (should-not (cj/--vterm-toggle-buffer-p buf))
+      (kill-buffer buf))))
+
+(ert-deftest test-vterm-toggle--buffer-p-rejects-non-vterm ()
+  "Boundary: a regular buffer (not vterm-mode, no vterm name prefix) -> nil."
+  (test-vterm-toggle--cleanup)
+  (let ((buf (get-buffer-create "*test-vterm-regular*")))
+    (unwind-protect
+        (should-not (cj/--vterm-toggle-buffer-p buf))
+      (kill-buffer buf))))
+
+(ert-deftest test-vterm-toggle--buffer-p-rejects-dead-buffer ()
+  "Boundary: nil and dead buffers -> nil."
+  (should-not (cj/--vterm-toggle-buffer-p nil))
+  (let ((buf (test-vterm-toggle--make-vterm-buffer "*test-vterm-dead*")))
+    (kill-buffer buf)
+    (should-not (cj/--vterm-toggle-buffer-p buf))))
+
+(ert-deftest test-vterm-toggle--buffers-filters-claude ()
+  "Normal: returns vterm buffers but excludes claude-prefixed ones."
+  (test-vterm-toggle--cleanup)
+  (let ((normal (test-vterm-toggle--make-vterm-buffer "*test-vterm-normal*"))
+        (claude (test-vterm-toggle--make-vterm-buffer "claude [for-test]")))
+    (unwind-protect
+        (let ((result (cj/--vterm-toggle-buffers)))
+          (should (memq normal result))
+          (should-not (memq claude result)))
+      (kill-buffer normal)
+      (kill-buffer claude))))
+
+(ert-deftest test-vterm-toggle--displayed-window-finds-vterm ()
+  "Normal: vterm in a window -> returns that window."
+  (test-vterm-toggle--cleanup)
+  (let ((vt (test-vterm-toggle--make-vterm-buffer "*test-vterm-shown*")))
+    (unwind-protect
+        (save-window-excursion
+          (delete-other-windows)
+          (let ((win (split-window-right)))
+            (set-window-buffer win vt)
+            (let ((result (cj/--vterm-toggle-displayed-window)))
+              (should (windowp result))
+              (should (eq (window-buffer result) vt)))))
+      (kill-buffer vt))))
+
+(ert-deftest test-vterm-toggle--displayed-window-skips-claude ()
+  "Boundary: only a claude vterm is displayed -> nil (claude not F12-managed)."
+  (test-vterm-toggle--cleanup)
+  (let ((claude (test-vterm-toggle--make-vterm-buffer "claude [skip-test]")))
+    (unwind-protect
+        (save-window-excursion
+          (delete-other-windows)
+          (let ((win (split-window-right)))
+            (set-window-buffer win claude)
+            (should-not (cj/--vterm-toggle-displayed-window))))
+      (kill-buffer claude))))
+
+(provide 'test-vterm-toggle--buffer-filter)
+;;; test-vterm-toggle--buffer-filter.el ends here
diff --git a/tests/test-vterm-toggle--dispatch.el b/tests/test-vterm-toggle--dispatch.el
new file mode 100644
index 00000000..d63b3d35
--- /dev/null
+++ b/tests/test-vterm-toggle--dispatch.el
@@ -0,0 +1,58 @@
+;;; test-vterm-toggle--dispatch.el --- Tests for cj/--vterm-toggle-dispatch -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Pure decision helper for F12.  Returns one of (toggle-off . WIN),
+;; (show-recent . BUFFER), or (create-new) based on whether a vterm
+;; window is currently displayed and whether any vterm buffers are
+;; alive.  Mocking the underlying helpers keeps the dispatch logic
+;; exercisable without touching real windows.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'eshell-vterm-config)
+
+(defun test-vterm-toggle--dispatch-cleanup ()
+  "Kill any leftover test buffers."
+  (dolist (b (buffer-list))
+    (let ((name (buffer-name b)))
+      (when (string-prefix-p "*test-vterm" name)
+        (kill-buffer b)))))
+
+(ert-deftest test-vterm-toggle--dispatch-window-displayed-returns-toggle-off ()
+  "Normal: displayed vterm window -> (toggle-off . WIN)."
+  (let ((sentinel-win 'fake-window))
+    (cl-letf (((symbol-function 'cj/--vterm-toggle-displayed-window)
+               (lambda (&optional _frame) sentinel-win)))
+      (should (equal (cj/--vterm-toggle-dispatch)
+                     (cons 'toggle-off sentinel-win))))))
+
+(ert-deftest test-vterm-toggle--dispatch-no-window-buffer-alive-returns-show-recent ()
+  "Normal: no displayed vterm, at least one alive -> show-recent + first."
+  (test-vterm-toggle--dispatch-cleanup)
+  (let ((b1 (get-buffer-create "*test-vterm-mru-1*"))
+        (b2 (get-buffer-create "*test-vterm-mru-2*")))
+    (unwind-protect
+        (cl-letf (((symbol-function 'cj/--vterm-toggle-displayed-window)
+                   (lambda (&optional _frame) nil))
+                  ((symbol-function 'cj/--vterm-toggle-buffers)
+                   (lambda () (list b1 b2))))
+          (should (equal (cj/--vterm-toggle-dispatch)
+                         (cons 'show-recent b1))))
+      (kill-buffer b1)
+      (kill-buffer b2))))
+
+(ert-deftest test-vterm-toggle--dispatch-no-window-no-buffer-returns-create-new ()
+  "Boundary: nothing displayed, no alive vterms -> create-new."
+  (test-vterm-toggle--dispatch-cleanup)
+  (cl-letf (((symbol-function 'cj/--vterm-toggle-displayed-window)
+             (lambda (&optional _frame) nil))
+            ((symbol-function 'cj/--vterm-toggle-buffers)
+             (lambda () nil)))
+    (should (equal (cj/--vterm-toggle-dispatch) '(create-new)))))
+
+(provide 'test-vterm-toggle--dispatch)
+;;; test-vterm-toggle--dispatch.el ends here
diff --git a/tests/test-vterm-toggle--display.el b/tests/test-vterm-toggle--display.el
new file mode 100644
index 00000000..70fa61ac
--- /dev/null
+++ b/tests/test-vterm-toggle--display.el
@@ -0,0 +1,116 @@
+;;; test-vterm-toggle--display.el --- Tests for the F12 display-saved action -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Covers the F12-side equivalents of the ai-vterm display tests:
+;; geometry capture (window-direction, window-size with 'below
+;; default), capture-state writing module-level vars, and the custom
+;; display action mapping cardinal -> edge directions.  Tests stub
+;; `display-buffer-in-direction' to capture the alist that would
+;; have reached it.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'eshell-vterm-config)
+
+(ert-deftest test-vterm-toggle--window-direction-single-window-defaults-to-below ()
+  "Boundary: full-frame window -> default 'below for F12."
+  (save-window-excursion
+    (delete-other-windows)
+    (should (eq (cj/--vterm-toggle-window-direction (selected-window))
+                'below))))
+
+(ert-deftest test-vterm-toggle--window-direction-below-split ()
+  "Normal: bottom window of horizontal split -> 'below."
+  (save-window-excursion
+    (delete-other-windows)
+    (let ((below (split-window (selected-window) nil 'below)))
+      (should (eq (cj/--vterm-toggle-window-direction below) 'below)))))
+
+(ert-deftest test-vterm-toggle--window-direction-right-split ()
+  "Normal: right window of vertical split -> 'right."
+  (save-window-excursion
+    (delete-other-windows)
+    (let ((right (split-window (selected-window) nil 'right)))
+      (should (eq (cj/--vterm-toggle-window-direction right) 'right)))))
+
+(ert-deftest test-vterm-toggle--window-size-returns-body ()
+  "Normal: returns body-width for right/left, body-height for below/above."
+  (save-window-excursion
+    (delete-other-windows)
+    (let ((below (split-window (selected-window) nil 'below)))
+      (should (= (cj/--vterm-toggle-window-size below 'below)
+                 (window-body-height below))))))
+
+(ert-deftest test-vterm-toggle--capture-state-records-direction-and-size ()
+  "Normal: capture-state writes direction and integer body size."
+  (save-window-excursion
+    (delete-other-windows)
+    (let ((below (split-window (selected-window) nil 'below))
+          (cj/--vterm-toggle-last-direction nil)
+          (cj/--vterm-toggle-last-size nil))
+      (cj/--vterm-toggle-capture-state below)
+      (should (eq cj/--vterm-toggle-last-direction 'below))
+      (should (integerp cj/--vterm-toggle-last-size))
+      (should (= cj/--vterm-toggle-last-size (window-body-height below))))))
+
+(ert-deftest test-vterm-toggle--capture-state-noop-on-dead-window ()
+  "Boundary: nil window -> state remains unchanged."
+  (let ((cj/--vterm-toggle-last-direction 'sentinel)
+        (cj/--vterm-toggle-last-size 0.123))
+    (cj/--vterm-toggle-capture-state nil)
+    (should (eq cj/--vterm-toggle-last-direction 'sentinel))
+    (should (= cj/--vterm-toggle-last-size 0.123))))
+
+(ert-deftest test-vterm-toggle--display-saved-defaults-when-state-nil ()
+  "Normal: nil state -> direction=bottom, size=cj/vterm-toggle-window-height."
+  (let (received-alist
+        (cj/--vterm-toggle-last-direction nil)
+        (cj/--vterm-toggle-last-size nil)
+        (cj/vterm-toggle-window-height 0.7))
+    (cl-letf (((symbol-function 'display-buffer-in-direction)
+               (lambda (_b a) (setq received-alist a) 'fake-window)))
+      (cj/--vterm-toggle-display-saved 'fake-buf '((inhibit-same-window . t))))
+    (should (eq (cdr (assq 'direction received-alist)) 'bottom))
+    (should (= (cdr (assq 'window-height received-alist)) 0.7))
+    (should (eq (cdr (assq 'inhibit-same-window received-alist)) t))))
+
+(ert-deftest test-vterm-toggle--display-saved-maps-cardinal-to-edge ()
+  "Normal: saved 'below maps to bottom edge; integer size wraps in body-lines."
+  (let (received-alist
+        (cj/--vterm-toggle-last-direction 'below)
+        (cj/--vterm-toggle-last-size 12))
+    (cl-letf (((symbol-function 'display-buffer-in-direction)
+               (lambda (_b a) (setq received-alist a) 'fake-window)))
+      (cj/--vterm-toggle-display-saved 'fake-buf nil))
+    (should (eq (cdr (assq 'direction received-alist)) 'bottom))
+    (should (equal (cdr (assq 'window-height received-alist))
+                   '(body-lines . 12)))
+    (should-not (assq 'window-width received-alist))))
+
+(ert-deftest test-vterm-toggle--display-saved-strips-conflicting-alist-entries ()
+  "Boundary: caller-supplied direction/size are stripped, saved values win."
+  (let (received-alist
+        (cj/--vterm-toggle-last-direction 'right)
+        (cj/--vterm-toggle-last-size 30))
+    (cl-letf (((symbol-function 'display-buffer-in-direction)
+               (lambda (_b a) (setq received-alist a) 'fake-window)))
+      (cj/--vterm-toggle-display-saved
+       'fake-buf
+       '((direction . above)
+         (window-width . 0.2)
+         (window-height . 0.3)
+         (inhibit-same-window . t))))
+    (should (eq (cdr (assq 'direction received-alist)) 'rightmost))
+    (should (equal (cdr (assq 'window-width received-alist))
+                   '(body-columns . 30)))
+    (let ((wh-cells (cl-remove-if-not
+                     (lambda (cell) (eq (car-safe cell) 'window-height))
+                     received-alist)))
+      (should (null wh-cells)))))
+
+(provide 'test-vterm-toggle--display)
+;;; test-vterm-toggle--display.el ends here