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.

4 files changed, 494 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.
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