Forward xterm-paste events to the inferior shell

TTY Emacs running inside a host terminal that does bracketed paste
delivers clipboard pastes as a single `(xterm-paste TEXT)` event.
The default `xterm-paste' binding inserts TEXT into the current
buffer, which is useless in a ghostel buffer: the renderer owns
the buffer and wipes any plain-inserted text on the next redraw,
so the shell never sees the paste.

Bind `[xterm-paste]' in `ghostel-mode-map' (and
`ghostel-copy-mode-map') to a new `ghostel-xterm-paste' handler
that pulls the text out of the event and forwards it to the
subprocess via `ghostel--paste-text', the same bracketed-paste
path used by `ghostel-yank' and `ghostel-paste'.  When
`xterm-store-paste-on-kill-ring' is non-nil (stock default), also
push the text onto the kill ring for parity with `xterm-paste'.
If copy-mode is active, exit it first so the paste reaches the
prompt.

Covered by seven ERT tests under the existing paste/yank section:
happy path forwards payload to `ghostel--paste-text'; wrong event
type raises `user-error'; nil payload is a no-op; kill-ring is
populated/skipped per `xterm-store-paste-on-kill-ring'; copy-mode
is exited before forwarding; and [xterm-paste] is bound in both
keymaps.

Fixes #172.

Author: dakra

CHANGELOG.md

@@ -31,6 +31,11 @@ All notable changes to this project will be documented in this file.
   a sticky `ghostel--buffer-identity` set at creation time, and lookup
   matches on identity rather than current buffer name
   ([#168](https://github.com/dakra/ghostel/issues/168)).
+- Bind `[xterm-paste]` to a ghostel-aware handler so clipboard pastes
+  delivered by the host terminal (TTY Emacs with bracketed paste) reach
+  the inferior shell instead of being inserted into the renderer-owned
+  buffer and wiped on the next redraw
+  ([#172](https://github.com/dakra/ghostel/issues/172)).
 
 ## [0.17.0] — 2026-04-21
 

lisp/ghostel.el

@@ -1053,6 +1053,10 @@ is non-nil.")
     (define-key map (kbd "<XF86Paste>") #'ghostel-yank)
     (define-key map (kbd "<XF86Copy>")  #'kill-ring-save)
     (define-key map (kbd "M-y")       #'ghostel-yank-pop)
+    ;; Bracketed paste from the host terminal (TTY Emacs): forward the
+    ;; paste payload to the subprocess instead of letting the default
+    ;; `xterm-paste' insert it into the (renderer-owned) buffer.
+    (define-key map [xterm-paste]     #'ghostel-xterm-paste)
     ;; Terminal control via C-c prefix (pass through to Emacs, then handled here)
     (define-key map (kbd "C-c C-c")   #'ghostel-send-C-c)
     (define-key map (kbd "C-c C-z")   #'ghostel-send-C-z)
@@ -1445,6 +1449,26 @@ pastes the selected entry into the terminal."
                                        kill-ring nil t)))
       (ghostel--paste-text text))))
 
+(defun ghostel-xterm-paste (event)
+  "Forward an xterm-paste EVENT to the terminal via bracketed paste.
+The default `xterm-paste' command inserts into the current buffer,
+which is wrong for ghostel: the terminal renderer owns the buffer
+and wipes the inserted text on the next redraw, so the shell
+never sees it.  This handler extracts the pasted text from EVENT
+and pushes it to the subprocess through `ghostel--paste-text'
+instead.  When `xterm-store-paste-on-kill-ring' is non-nil (the
+stock default), the text is also pushed onto the kill ring for
+parity with `xterm-paste'."
+  (interactive "e")
+  (unless (eq (car-safe event) 'xterm-paste)
+    (error "This command must be bound to an xterm-paste event"))
+  (when ghostel--copy-mode-active
+    (ghostel-copy-mode-exit))
+  (when-let* ((text (nth 1 event)))
+    (when (bound-and-true-p xterm-store-paste-on-kill-ring)
+      (kill-new text))
+    (ghostel--paste-text text)))
+
 
 ;;; Drag and drop
 
@@ -1622,10 +1646,11 @@ Return non-nil if the event was forwarded (mouse tracking is active)."
     ;; Prompt navigation works in copy mode too
     (define-key map (kbd "C-c M-n") #'ghostel-next-prompt)
     (define-key map (kbd "C-c M-p") #'ghostel-previous-prompt)
-    (define-key map (kbd "M->")             #'ghostel-copy-mode-end-of-buffer)
-    (define-key map (kbd "C-e")             #'ghostel-copy-mode-end-of-line)
-    (define-key map (kbd "C-l")             #'ghostel-copy-mode-recenter)
-    (define-key map (kbd "C-c C-l")         #'ghostel-copy-mode-exit-and-clear)
+    (define-key map (kbd "M->")     #'ghostel-copy-mode-end-of-buffer)
+    (define-key map (kbd "C-e")     #'ghostel-copy-mode-end-of-line)
+    (define-key map (kbd "C-l")     #'ghostel-copy-mode-recenter)
+    (define-key map (kbd "C-c C-l") #'ghostel-copy-mode-exit-and-clear)
+    (define-key map [xterm-paste]   #'ghostel-xterm-paste)
     map)
   "Keymap for `ghostel-copy-mode'.
 Standard Emacs navigation works.

test/ghostel-test.el

@@ -6022,6 +6022,106 @@ but `this-command-keys-vector' retains the ESC prefix."
       (ghostel-yank-pop)
       (should (equal (car pasted) "alpha")))))
 
+;; -----------------------------------------------------------------------
+;; Test: ghostel-xterm-paste
+;; -----------------------------------------------------------------------
+
+;; Declared here so tests can let-bind it without byte-compile warnings
+;; when xterm.el hasn't been loaded in the batch environment.
+(defvar xterm-store-paste-on-kill-ring)
+
+(ert-deftest ghostel-test-xterm-paste-forwards-to-paste-text ()
+  "`ghostel-xterm-paste' forwards the event payload via `ghostel--paste-text'."
+  (let ((pasted nil)
+        (ghostel--copy-mode-active nil)
+        (xterm-store-paste-on-kill-ring nil))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (text) (push text pasted))))
+      (ghostel-xterm-paste '(xterm-paste "hello world"))
+      (should (equal pasted '("hello world"))))))
+
+(ert-deftest ghostel-test-xterm-paste-rejects-wrong-event ()
+  "`ghostel-xterm-paste' signals when the event isn't an xterm-paste."
+  (let ((ghostel--copy-mode-active nil))
+    (should-error (ghostel-xterm-paste '(mouse-1 "oops")))))
+
+(ert-deftest ghostel-test-xterm-paste-no-text-is-noop ()
+  "`ghostel-xterm-paste' with a nil payload does not forward or touch the kill ring."
+  (let ((called nil)
+        (kill-ring '("preexisting"))
+        (kill-ring-yank-pointer nil)
+        (ghostel--copy-mode-active nil)
+        (xterm-store-paste-on-kill-ring t))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (_text) (setq called t))))
+      (ghostel-xterm-paste '(xterm-paste nil))
+      (should-not called)
+      (should (equal kill-ring '("preexisting"))))))
+
+(ert-deftest ghostel-test-xterm-paste-stores-on-kill-ring ()
+  "When `xterm-store-paste-on-kill-ring' is non-nil, push the paste onto the kill ring."
+  (let ((pasted nil)
+        (kill-ring nil)
+        (kill-ring-yank-pointer nil)
+        (ghostel--copy-mode-active nil)
+        (xterm-store-paste-on-kill-ring t))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (text) (push text pasted))))
+      (ghostel-xterm-paste '(xterm-paste "clip"))
+      (should (equal pasted '("clip")))
+      (should (equal (car kill-ring) "clip")))))
+
+(ert-deftest ghostel-test-xterm-paste-skips-kill-ring-when-disabled ()
+  "When `xterm-store-paste-on-kill-ring' is nil, the kill ring is untouched."
+  (let ((pasted nil)
+        (kill-ring '("preexisting"))
+        (kill-ring-yank-pointer nil)
+        (ghostel--copy-mode-active nil)
+        (xterm-store-paste-on-kill-ring nil))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (text) (push text pasted))))
+      (ghostel-xterm-paste '(xterm-paste "clip"))
+      (should (equal pasted '("clip")))
+      (should (equal kill-ring '("preexisting"))))))
+
+(ert-deftest ghostel-test-xterm-paste-exits-copy-mode ()
+  "`ghostel-xterm-paste' exits copy mode before forwarding."
+  (let ((pasted nil)
+        (exit-called nil)
+        (ghostel--copy-mode-active t)
+        (xterm-store-paste-on-kill-ring nil))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (text) (push text pasted)))
+              ((symbol-function 'ghostel-copy-mode-exit)
+               (lambda () (setq exit-called t))))
+      (ghostel-xterm-paste '(xterm-paste "payload"))
+      (should exit-called)
+      (should (equal pasted '("payload"))))))
+
+(ert-deftest ghostel-test-xterm-paste-bound-in-keymaps ()
+  "`ghostel-xterm-paste' is bound to the [xterm-paste] event in both keymaps."
+  (should (eq (lookup-key ghostel-mode-map [xterm-paste])
+              #'ghostel-xterm-paste))
+  (should (eq (lookup-key ghostel-copy-mode-map [xterm-paste])
+              #'ghostel-xterm-paste)))
+
+(ert-deftest ghostel-test-xterm-paste-copy-mode-and-kill-ring ()
+  "All three side effects (exit copy mode, `kill-ring', forward) fire together."
+  (let ((pasted nil)
+        (exit-called nil)
+        (kill-ring nil)
+        (kill-ring-yank-pointer nil)
+        (ghostel--copy-mode-active t)
+        (xterm-store-paste-on-kill-ring t))
+    (cl-letf (((symbol-function 'ghostel--paste-text)
+               (lambda (text) (push text pasted)))
+              ((symbol-function 'ghostel-copy-mode-exit)
+               (lambda () (setq exit-called t))))
+      (ghostel-xterm-paste '(xterm-paste "combo"))
+      (should exit-called)
+      (should (equal pasted '("combo")))
+      (should (equal (car kill-ring) "combo")))))
+
 ;; -----------------------------------------------------------------------
 ;; Test: ghostel-copy-mode-recenter
 ;; -----------------------------------------------------------------------
@@ -7036,6 +7136,14 @@ while :; do sleep 0.1; done'\n")
     ghostel-test-send-event-tty-esc-prefix
     ghostel-test-yank-pop-after-yank
     ghostel-test-yank-pop-no-preceding-yank
+    ghostel-test-xterm-paste-forwards-to-paste-text
+    ghostel-test-xterm-paste-rejects-wrong-event
+    ghostel-test-xterm-paste-no-text-is-noop
+    ghostel-test-xterm-paste-stores-on-kill-ring
+    ghostel-test-xterm-paste-skips-kill-ring-when-disabled
+    ghostel-test-xterm-paste-exits-copy-mode
+    ghostel-test-xterm-paste-bound-in-keymaps
+    ghostel-test-xterm-paste-copy-mode-and-kill-ring
     ghostel-test-copy-mode-recenter
     ghostel-test-send-next-key-control-x
     ghostel-test-send-next-key-control-h