Function: ghostel--init-buffer

ghostel--init-buffer is a natively compiled function defined in ghostel.el.

Signature

(ghostel--init-buffer BUFFER &optional ROWS COLS)

Documentation

Initialize BUFFER as a ghostel terminal.

This is the invariant boundary between an Emacs buffer and its native terminal handle: BUFFER is made empty, renderer-coupled buffer-local state is reset, and the newly created terminal is attached immediately as BUFFER's buffer-local ghostel--term. It intentionally does not reset unrelated buffer-local state such as manual rename/identity bookkeeping.

Optional ROWS and COLS override size detection. Otherwise terminal dimensions come from BUFFER's displayed window when one exists, otherwise from the selected window. Height uses window-screen-lines, the metric the standard adjust-window-size-function path also uses, not window-body-height. The former divides the window's pixel height by the buffer's default-line-height, which respects face-remapping-alist and :height on the default face; the latter divides by frame char height. When a theme remaps default — nano-light / nano-dark do this — the two metrics disagree, and using window-body-height would size the terminal to N rows only to have the standard adjust-fn immediately resize to N-K, sending a startup SIGWINCH that some TUI apps (Claude Code's /tui fullscreen) handle imperfectly (issue #192).

This function does not start a process; callers decide what program to spawn after initialization.

Source Code

;; Defined in /nix/store/1252krff0gb2kisjcpp45m50cpdskfrl-emacs-packages-deps/share/emacs/site-lisp/ghostel.el
;;; Entry point

(defun ghostel--init-buffer (buffer &optional rows cols)
  "Initialize BUFFER as a ghostel terminal.
This is the invariant boundary between an Emacs buffer and its native
terminal handle: BUFFER is made empty, renderer-coupled buffer-local
state is reset, and the newly created terminal is attached immediately
as BUFFER's buffer-local `ghostel--term'.  It intentionally does not
reset unrelated buffer-local state such as manual rename/identity bookkeeping.

Optional ROWS and COLS override size detection.  Otherwise terminal
dimensions come from BUFFER's displayed window when one exists,
otherwise from the selected window.  Height uses `window-screen-lines',
the metric the standard `adjust-window-size-function' path also uses,
not `window-body-height'.  The former divides the window's pixel height
by the buffer's `default-line-height', which respects
`face-remapping-alist' and `:height' on the default face; the latter
divides by frame char height.  When a theme remaps default —
`nano-light' / `nano-dark' do this — the two metrics disagree, and
using `window-body-height' would size the terminal to N rows only to
have the standard adjust-fn immediately resize to N-K, sending a
startup SIGWINCH that some TUI apps (Claude Code's /tui fullscreen)
handle imperfectly (issue #192).

This function does not start a process; callers decide what program to
spawn after initialization."
  (unless (buffer-live-p buffer)
    (user-error "Cannot initialize dead buffer as ghostel terminal"))
  (unless (eq (null rows) (null cols))
    (user-error "ROWS and COLS must be provided together"))
  (with-current-buffer buffer
    ;; A local child's chdir failure would only surface as an immediate
    ;; exit; TRAMP reports remote ones itself.
    (unless (or (file-remote-p default-directory)
                (file-directory-p default-directory))
      (user-error "Ghostel: directory %s does not exist" default-directory))
    (when (process-live-p ghostel--process)
      (user-error "Buffer %s already has a running ghostel process"
                  (buffer-name buffer)))
    (unless (derived-mode-p 'ghostel-mode)
      (ghostel-mode))
    (when ghostel--redraw-timer
      (cancel-timer ghostel--redraw-timer))
    (when ghostel--plain-link-detection-timer
      (cancel-timer ghostel--plain-link-detection-timer))
    (ghostel--clear-plain-link-detection-bounds)
    ;; Reinitialization may reuse an existing ghostel buffer that was in
    ;; line mode; reset it to the renderer-owned default before erasing.
    (setq buffer-read-only t)
    (let ((inhibit-read-only t))
      (erase-buffer))
    (setq ghostel--input-mode 'semi-char
          ghostel--term nil
          ghostel--term-rows nil
          ghostel--term-cols nil
          ghostel--process nil
          ghostel--pid nil
          ghostel--last-directory nil
          ghostel-title nil
          ghostel--command-running nil
          ghostel--event-buf nil
          ghostel--redraw-timer nil
          ghostel--pending-redraw nil
          ghostel--plain-link-detection-timer nil
          ghostel--force-next-redraw nil
          ghostel--cursor-pos nil
          ghostel--cursor-char-pos nil
          ghostel--repainted-region nil)
    (ghostel--top-pad-set 0)
    ;; Reused buffers hold the previous session's title; drop it from
    ;; the mode line along with the buffer-local reset above.
    (ghostel--buffer-identification-update)
    (let* ((w (or (get-buffer-window buffer t) (selected-window)))
           (height (max 1 (or rows
                              (if (window-live-p w)
                                  (with-selected-window w
                                    (floor (window-screen-lines)))
                                24))))
           (width  (max 1 (or cols
                              (if (window-live-p w)
                                  (window-max-chars-per-line w)
                                80)))))
      (setq ghostel--term
            (ghostel--new height width
                          ghostel-max-scrollback
                          ghostel-kitty-graphics-storage-limit
                          (ghostel--kitty-mediums-bits)))
      ;; Seed libghostty's cell dimensions before the process starts —
      ;; otherwise kitty graphics placements arriving in the very first
      ;; output (e.g. timg's transmit-and-place) compute grid_rows=0
      ;; and the terminal advances the cursor zero rows, leaving the
      ;; next prompt on top of the image.
      (ghostel--set-size-with-cell-dims ghostel--term height width)
      (ghostel--apply-palette ghostel--term)
      (ghostel--apply-bold-config ghostel--term))
    buffer))