Add public API for sending input to the terminal (#126)

Promote two thin wrappers — `ghostel-send-string' and `ghostel-send-key'
— so external packages (agent integrations, custom keymaps) can drive a
ghostel buffer without reaching into `ghostel--' internals.  Both signal
a `user-error' when called outside a ghostel-mode buffer.

Rename the internal `ghostel--send-key' to `ghostel--send-string' to
match what it does (writes raw bytes to the PTY) and avoid naming
confusion with the new public `ghostel-send-key' (which takes a key
name and mods and goes through the encoder).  The old internal name is
kept as an obsolete alias so third-party packages that reached into it
keep working.

Author: dakra

README.md

@@ -455,6 +455,23 @@ When `evil-ghostel-mode` is active:
 | `M-x ghostel-download-module`  | Download pre-built native module             |
 | `M-x ghostel-module-compile`   | Compile native module from source            |
 
+### Sending input from Lisp
+
+For packages that need to inject input into a running ghostel buffer
+(agent integrations, custom keymaps, Swerty-style bindings, …) two
+public functions are provided:
+
+```elisp
+(ghostel-send-string "ls -la\n")      ; send raw bytes, newline included
+(ghostel-send-key "return")           ; send a named key through the encoder
+(ghostel-send-key "a" "ctrl")         ; C-a — respects the current terminal mode
+(ghostel-send-key "up" "shift,ctrl")  ; modifiers are comma-separated
+```
+
+Both operate on the current buffer; wrap in `with-current-buffer`
+when driving another ghostel buffer.  Calling either outside a
+ghostel buffer signals a `user-error`.
+
 ### Project integration
 
 `ghostel-project` opens a terminal in the current project's root directory

ghostel-debug.el

@@ -52,7 +52,7 @@ Logs filter calls, key sends, resize events, redraw decisions
     (insert "=== Ghostel Debug Log ===\n\n"))
   ;; Data path
   (advice-add 'ghostel--filter :before #'ghostel-debug--log-filter)
-  (advice-add 'ghostel--send-key :before #'ghostel-debug--log-send)
+  (advice-add 'ghostel--send-string :before #'ghostel-debug--log-send)
   (advice-add 'ghostel--send-encoded :before #'ghostel-debug--log-encoded)
   ;; Render path
   (advice-add 'ghostel--delayed-redraw :around #'ghostel-debug--log-redraw)
@@ -66,7 +66,7 @@ Logs filter calls, key sends, resize events, redraw decisions
   "Stop logging."
   (interactive)
   (advice-remove 'ghostel--filter #'ghostel-debug--log-filter)
-  (advice-remove 'ghostel--send-key #'ghostel-debug--log-send)
+  (advice-remove 'ghostel--send-string #'ghostel-debug--log-send)
   (advice-remove 'ghostel--send-encoded #'ghostel-debug--log-encoded)
   (advice-remove 'ghostel--delayed-redraw #'ghostel-debug--log-redraw)
   (advice-remove 'ghostel--window-adjust-process-window-size
@@ -239,7 +239,7 @@ The latency breakdown shows:
       (erase-buffer)
       (insert "=== Ghostel Typing Latency Measurement ===\n")
       (insert (format "Type %d characters to collect measurements...\n\n" n)))
-    (advice-add 'ghostel--send-key :before #'ghostel-debug--latency-on-send)
+    (advice-add 'ghostel--send-string :before #'ghostel-debug--latency-on-send)
     (advice-add 'ghostel--filter :before #'ghostel-debug--latency-on-echo)
     (advice-add 'ghostel--delayed-redraw :after #'ghostel-debug--latency-on-render)
     (message "ghostel-debug: type %d characters to measure latency" n)))
@@ -275,7 +275,7 @@ The latency breakdown shows:
 
 (defun ghostel-debug--latency-report ()
   "Generate and display the latency report."
-  (advice-remove 'ghostel--send-key #'ghostel-debug--latency-on-send)
+  (advice-remove 'ghostel--send-string #'ghostel-debug--latency-on-send)
   (advice-remove 'ghostel--filter #'ghostel-debug--latency-on-echo)
   (advice-remove 'ghostel--delayed-redraw #'ghostel-debug--latency-on-render)
   (setq ghostel-debug--latency-active nil)

ghostel.el

@@ -151,7 +151,7 @@ Set to 0 to disable immediate redraws."
 
 (defcustom ghostel-immediate-redraw-interval 0.05
   "Maximum seconds since last keystroke for immediate redraw.
-Output arriving within this interval of a `ghostel--send-key'
+Output arriving within this interval of a `ghostel--send-string'
 call is considered interactive echo and redrawn immediately
 when the output size is below `ghostel-immediate-redraw-threshold'."
   :type 'number)
@@ -784,7 +784,7 @@ pixel-based trailing-space compensation is needed.")
 
 
 (defvar-local ghostel--last-send-time nil
-  "Time of the last `ghostel--send-key' call, for immediate-redraw detection.")
+  "Time of the last `ghostel--send-string' call, for immediate-redraw detection.")
 
 (defvar-local ghostel--input-buffer nil
   "Accumulated keystrokes waiting to be flushed to the PTY.")
@@ -917,7 +917,7 @@ is non-nil.")
             (define-key map (kbd key-str)
                         (let ((code (- c 96)))
                           (lambda () (interactive)
-                            (ghostel--send-key (string code)))))))))
+                            (ghostel--send-string (string code)))))))))
     ;; Meta keys — bind all M-<letter> so they reach the terminal
     ;; instead of running Emacs commands like forward-word.
     (dolist (c (number-sequence ?a ?z))
@@ -926,7 +926,7 @@ is non-nil.")
           (define-key map (kbd key-str) #'ghostel--send-event))))
     ;; C-@ (NUL, same as C-SPC) — used by programs like Emacs-in-terminal
     (define-key map (kbd "C-@")
-                (lambda () (interactive) (ghostel--send-key "\x00")))
+                (lambda () (interactive) (ghostel--send-string "\x00")))
     ;; C-y: yank from Emacs kill ring into the terminal
     (define-key map (kbd "C-y")       #'ghostel-yank)
     (when (eq system-type 'darwin)
@@ -978,13 +978,13 @@ of waiting for a continuation keystroke."
     (cond
      ;; Control character (C-@=0, C-a=1 through C-_=31)
      ((and (integerp event) (<= event 31))
-      (ghostel--send-key (string event)))
+      (ghostel--send-string (string event)))
      ;; ASCII (32-127)
      ((and (integerp event) (<= event 127))
-      (ghostel--send-key (string event)))
+      (ghostel--send-string (string event)))
      ;; Non-ASCII character without modifier bits — send as UTF-8
      ((and (integerp event) (< event #x400000))
-      (ghostel--send-key (encode-coding-string (string event) 'utf-8)))
+      (ghostel--send-string (encode-coding-string (string event) 'utf-8)))
      ;; Modified key (M-x, C-M-a, etc.) or function key — use encoder
      (t
       (let* ((base (event-basic-type event))
@@ -1015,17 +1015,17 @@ of waiting for a continuation keystroke."
             (ghostel--send-encoded key-name mod-str)
           (message "ghostel: unrecognized key %S" event)))))))
 
-(defun ghostel--send-key (key)
-  "Send KEY string to the terminal process.
+(defun ghostel--send-string (string)
+  "Send STRING as raw bytes to the terminal process.
 Records the send time for immediate-redraw detection and optionally
 coalesces rapid keystrokes when `ghostel-input-coalesce-delay' > 0."
   (when (and ghostel--process (process-live-p ghostel--process))
     (setq ghostel--last-send-time (current-time))
     (if (and (> ghostel-input-coalesce-delay 0)
-             (= (length key) 1))
+             (= (length string) 1))
         ;; Coalesce single-char keystrokes
         (progn
-          (push key ghostel--input-buffer)
+          (push string ghostel--input-buffer)
           (unless ghostel--input-timer
             (setq ghostel--input-timer
                   (run-with-timer ghostel-input-coalesce-delay nil
@@ -1039,7 +1039,10 @@ coalesces rapid keystrokes when `ghostel-input-coalesce-delay' > 0."
           (process-send-string ghostel--process
                                (apply #'concat (nreverse ghostel--input-buffer)))
           (setq ghostel--input-buffer nil)))
-      (process-send-string ghostel--process key))))
+      (process-send-string ghostel--process string))))
+
+(define-obsolete-function-alias 'ghostel--send-key
+  #'ghostel--send-string "0.16.0")
 
 (defun ghostel--flush-input (buffer)
   "Flush coalesced input in BUFFER to the PTY."
@@ -1064,7 +1067,7 @@ Falls back to raw escape sequences if the encoder doesn't produce output."
         ;; immediate-redraw detection (ghostel--flush-output doesn't do this).
         (setq ghostel--last-send-time (current-time))
       (let ((seq (ghostel--raw-key-sequence key-name mods)))
-        (when seq (ghostel--send-key seq))))))
+        (when seq (ghostel--send-string seq))))))
 
 (defun ghostel--raw-key-sequence (key-name mods)
   "Build a raw escape sequence for KEY-NAME with MODS.
@@ -1157,7 +1160,7 @@ paste, yank, drop."
          (str (if (and (characterp char) (< char 128))
                   (string char)
                 (encode-coding-string (string char) 'utf-8))))
-    (ghostel--send-key str)))
+    (ghostel--send-string str)))
 
 (defun ghostel--send-event ()
   "Send the current key event to the terminal via the key encoder.
@@ -1200,6 +1203,30 @@ modes (application cursor keys, Kitty keyboard protocol, etc.)."
       (ghostel--send-encoded key-name mod-str))))
 
 
+;;; Public input API
+
+(defun ghostel-send-string (string)
+  "Send STRING to the terminal process in the current ghostel buffer.
+Signals a `user-error' when called outside a ghostel buffer.  STRING
+is passed through unchanged, including any embedded control
+characters; callers are responsible for UTF-8 encoding if needed."
+  (unless (derived-mode-p 'ghostel-mode)
+    (user-error "Must be called from a ghostel buffer"))
+  (ghostel--send-string string))
+
+(defun ghostel-send-key (key-name &optional mods)
+  "Send KEY-NAME with optional MODS to the terminal's key encoder.
+KEY-NAME is a string like \"a\", \"return\", or \"up\".  MODS is a
+comma-separated modifier string like \"ctrl\" or \"shift,ctrl\", or
+nil for no modifiers.  The encoder respects the terminal's current
+mode (application cursor keys, Kitty keyboard protocol, etc.).
+
+Signals a `user-error' when called outside a ghostel buffer."
+  (unless (derived-mode-p 'ghostel-mode)
+    (user-error "Must be called from a ghostel buffer"))
+  (ghostel--send-encoded key-name (or mods "")))
+
+
 ;;; Terminal control commands (C-c prefix)
 
 (defun ghostel-send-C-c ()
@@ -1215,7 +1242,7 @@ modes (application cursor keys, Kitty keyboard protocol, etc.)."
 (defun ghostel-send-C-backslash ()
   "Send C-\\ (quit) to the terminal."
   (interactive)
-  (ghostel--send-key "\x1c"))
+  (ghostel--send-string "\x1c"))
 
 (defun ghostel-send-C-d ()
   "Send EOF to the terminal."
@@ -1228,7 +1255,7 @@ Clears `quit-flag' which Emacs sets when \\`C-g' is pressed with
 `inhibit-quit' non-nil."
   (interactive)
   (setq quit-flag nil)
-  (ghostel--send-key (string 7)))
+  (ghostel--send-string (string 7)))
 
 
 ;;; Paste / yank
@@ -1305,7 +1332,7 @@ pasted using bracketed paste."
         (let ((type (car arg))
               (objects (cddr arg)))
           (if (eq type 'file)
-              (ghostel--send-key
+              (ghostel--send-string
                (mapconcat #'shell-quote-argument objects " "))
             (ghostel--paste-text
              (mapconcat #'identity objects "\n"))))))))

test/ghostel-test.el

@@ -4361,7 +4361,7 @@ hand nil to the native module."
                    ;; Return a fake timer but call function for test
                    'fake-timer)))
         (setq ghostel--process 'fake)
-        (ghostel--send-key "a")
+        (ghostel--send-string "a")
         ;; Should be buffered, not sent
         (should (equal ghostel--input-buffer '("a")))
         (should-not sent)))))
@@ -4379,7 +4379,7 @@ hand nil to the native module."
                 ((symbol-function 'process-send-string)
                  (lambda (_proc str) (push str sent))))
         (setq ghostel--process 'fake)
-        (ghostel--send-key "a")
+        (ghostel--send-string "a")
         (should (member "a" sent))
         (should-not ghostel--input-buffer)))))
 
@@ -4447,7 +4447,7 @@ redraw and produce visible flicker, so point is left alone."
         (sent-key nil))
     (cl-letf (((symbol-function 'ghostel--scroll-bottom)
                (lambda (_term) (setq scroll-bottom-called t)))
-              ((symbol-function 'ghostel--send-key)
+              ((symbol-function 'ghostel--send-string)
                (lambda (str) (setq sent-key str))))
       (with-temp-buffer
         (insert "scrollback\nscrollback\nscrollback\n")
@@ -4488,7 +4488,7 @@ redraw and produce visible flicker, so point is left alone."
         (scroll-bottom-called nil))
     (cl-letf (((symbol-function 'ghostel--scroll-bottom)
                (lambda (_term) (setq scroll-bottom-called t)))
-              ((symbol-function 'ghostel--send-key)
+              ((symbol-function 'ghostel--send-string)
                (lambda (_str) nil)))
       (with-temp-buffer
         (insert "scrollback\nscrollback\nscrollback\n")
@@ -4796,7 +4796,7 @@ rather than the selected window's buffer."
 (ert-deftest ghostel-test-send-next-key-control-x ()
   "Send-next-key sends the prefix key as raw byte 24 (not intercepted by Emacs)."
   (let (sent-key)
-    (cl-letf (((symbol-function 'ghostel--send-key)
+    (cl-letf (((symbol-function 'ghostel--send-string)
                (lambda (str) (setq sent-key str))))
       (let ((unread-command-events (list ?\C-x)))
         (ghostel-send-next-key))
@@ -4805,7 +4805,7 @@ rather than the selected window's buffer."
 (ert-deftest ghostel-test-send-next-key-control-h ()
   "Send-next-key sends the help key as raw byte 8."
   (let (sent-key)
-    (cl-letf (((symbol-function 'ghostel--send-key)
+    (cl-letf (((symbol-function 'ghostel--send-string)
                (lambda (str) (setq sent-key str))))
       (let ((unread-command-events (list ?\C-h)))
         (ghostel-send-next-key))
@@ -4814,7 +4814,7 @@ rather than the selected window's buffer."
 (ert-deftest ghostel-test-send-next-key-regular-char ()
   "Send-next-key sends a regular character as-is."
   (let (sent-key)
-    (cl-letf (((symbol-function 'ghostel--send-key)
+    (cl-letf (((symbol-function 'ghostel--send-string)
                (lambda (str) (setq sent-key str))))
       (let ((unread-command-events (list ?a)))
         (ghostel-send-next-key))
@@ -4844,6 +4844,63 @@ rather than the selected window's buffer."
       (should (equal "up" captured-key))
       (should (equal "" captured-mods)))))
 
+;; -----------------------------------------------------------------------
+;; Test: public send-string / send-key API
+;; -----------------------------------------------------------------------
+
+(ert-deftest ghostel-test-send-string-routes-to-send-string ()
+  "`ghostel-send-string' forwards its argument to `ghostel--send-string'."
+  (with-temp-buffer
+    (ghostel-mode)
+    (let (sent)
+      (cl-letf (((symbol-function 'ghostel--send-string)
+                 (lambda (str) (setq sent str))))
+        (ghostel-send-string "hello")
+        (should (equal sent "hello"))))))
+
+(ert-deftest ghostel-test-send-string-errors-outside-ghostel-buffer ()
+  "`ghostel-send-string' signals `user-error' when not in a ghostel buffer."
+  (with-temp-buffer
+    (should-error (ghostel-send-string "x") :type 'user-error)))
+
+(ert-deftest ghostel-test-send-key-routes-to-send-encoded ()
+  "`ghostel-send-key' forwards key-name and mods to `ghostel--send-encoded'."
+  (with-temp-buffer
+    (ghostel-mode)
+    (let (captured-key captured-mods)
+      (cl-letf (((symbol-function 'ghostel--send-encoded)
+                 (lambda (key mods &optional _utf8)
+                   (setq captured-key key captured-mods mods))))
+        (ghostel-send-key "return" "ctrl")
+        (should (equal captured-key "return"))
+        (should (equal captured-mods "ctrl"))))))
+
+(ert-deftest ghostel-test-send-key-nil-mods-becomes-empty-string ()
+  "`ghostel-send-key' passes an empty string when MODS is omitted."
+  (with-temp-buffer
+    (ghostel-mode)
+    (let (captured-mods)
+      (cl-letf (((symbol-function 'ghostel--send-encoded)
+                 (lambda (_key mods &optional _utf8)
+                   (setq captured-mods mods))))
+        (ghostel-send-key "up")
+        (should (equal captured-mods ""))))))
+
+(ert-deftest ghostel-test-send-key-errors-outside-ghostel-buffer ()
+  "`ghostel-send-key' signals `user-error' when not in a ghostel buffer."
+  (with-temp-buffer
+    (should-error (ghostel-send-key "a") :type 'user-error)))
+
+(ert-deftest ghostel-test-send-key-obsolete-alias-still-works ()
+  "The obsolete `ghostel--send-key' alias routes to `ghostel--send-string'.
+External packages may still call the old internal name."
+  (let (sent)
+    (cl-letf (((symbol-function 'ghostel--send-string)
+               (lambda (str) (setq sent str))))
+      (with-no-warnings
+        (ghostel--send-key "payload"))
+      (should (equal sent "payload")))))
+
 ;; -----------------------------------------------------------------------
 ;; Test: TRAMP integration
 ;; -----------------------------------------------------------------------
@@ -5342,6 +5399,12 @@ while :; do sleep 0.1; done'\n")
     ghostel-test-send-next-key-regular-char
     ghostel-test-send-next-key-meta-x
     ghostel-test-send-next-key-function-key
+    ghostel-test-send-string-routes-to-send-string
+    ghostel-test-send-key-obsolete-alias-still-works
+    ghostel-test-send-string-errors-outside-ghostel-buffer
+    ghostel-test-send-key-routes-to-send-encoded
+    ghostel-test-send-key-nil-mods-becomes-empty-string
+    ghostel-test-send-key-errors-outside-ghostel-buffer
     ghostel-test-local-host-p
     ghostel-test-update-directory-remote
     ghostel-test-get-shell-local