Broaden anchor-window clamp to cover CUP-park on empty trailing row

ad8536e narrowed the `ghostel--anchor-window' clamp to fire only when
libghostty reports pending-wrap, which fixed the #146 regression but
reopened a variant of #138 for TUIs that move their cursor to the
bottom of the screen via absolute positioning (CUP) rather than via
writing-then-wrapping.  In that case `pt' equals `point-max' and the
cursor sits on the last viewport row, but pending-wrap is nil — so the
clamp doesn't fire and Emacs shifts `window-start' by one row to make
`pt' "visible," fighting the viewport pin.

Expose a second terminal-side predicate `ghostel--cursor-on-empty-row-p'
backed by a new `render.isRowEmptyAt' helper, and widen the clamp guard
to `(or pending-wrap cursor-on-empty-row)'.  The predicate returns t iff
the row containing the cursor has no written cells and no cells with
non-default styling — exactly the condition under which `buildRowContent'
produces `byte_len == 0'.  Wide-spacer-tail cells are skipped to mirror
`buildRowContent' (defensive — in practice spacer tails always follow a
wide grapheme).

Source `cy' from `RS_DATA_CURSOR_VIEWPORT_Y' gated by `...HAS_VALUE' so
the coordinate space matches the viewport row iterator that
`isRowEmptyAt' walks, and the predicate returns nil when the cursor
isn't visible in the current viewport.  Caller owns the
`ghostty_render_state_update' refresh so it only happens once per call.

An earlier draft (#158) tried `pos-visible-in-window-p' but it reflects
the previous redisplay rather than the just-pinned `window-start', and
breaks in batch.  The terminal-side predicate answers the real
question — is there anything on this row to anchor `pt' to? — without
consulting Emacs redisplay state.

Bump module version to 0.16.3 (new exported function).

Test changes:
- `ghostel-test-cursor-on-empty-row-p' covers the predicate across
  fresh-terminal / post-write / post-CRLF / post-CUP cursor positions.
- `ghostel-test-anchor-window-clamps-on-empty-row' is the #157
  regression test: feeds "foo\r\nbar\r\n" to park the cursor on an
  empty last row, asserts PT lands at `point-max', pending-wrap is nil,
  empty-row is t, and the clamp fires.
- `ghostel-test-anchor-window-no-clamp-on-populated-last-row'
  complements #146: cursor at `point-max' on a last row that does have
  content (e.g. a shell prompt) must NOT be clamped regardless of which
  predicate is consulted.

Closes #157.

Author: dakra

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .ghostel,
-    .version = "0.16.2",
+    .version = "0.16.3",
     .paths = .{""},
     .fingerprint = 0x5a44bdd1198a0f4b,
     .dependencies = .{

evil-ghostel.el

@@ -4,7 +4,7 @@
 
 ;; Author: Daniel Kraus <daniel@kraus.my>
 ;; URL: https://github.com/dakra/ghostel
-;; Version: 0.16.2
+;; Version: 0.16.3
 ;; Package-Requires: ((emacs "28.1") (evil "1.0") (ghostel "0.8.0"))
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 

ghostel.el

@@ -4,7 +4,7 @@
 
 ;; Author: Daniel Kraus <daniel@kraus.my>
 ;; URL: https://github.com/dakra/ghostel
-;; Version: 0.16.2
+;; Version: 0.16.3
 ;; Keywords: terminals
 ;; Package-Requires: ((emacs "28.1"))
 ;; SPDX-License-Identifier: GPL-3.0-or-later
@@ -524,7 +524,7 @@ before sending the input."
 Customize this when downloading pre-built modules from a fork or mirror."
   :type 'string)
 
-(defconst ghostel--minimum-module-version "0.16.2"
+(defconst ghostel--minimum-module-version "0.16.3"
   "Minimum native module version required by this Elisp version.
 Bump this only when the Elisp code requires a newer native module
 \(e.g. new Zig-exported function or changed calling convention).")
@@ -534,6 +534,7 @@ Bump this only when the Elisp code requires a newer native module
 
 (declare-function ghostel--cursor-position "ghostel-module")
 (declare-function ghostel--cursor-pending-wrap-p "ghostel-module")
+(declare-function ghostel--cursor-on-empty-row-p "ghostel-module")
 (declare-function ghostel--encode-key "ghostel-module")
 (declare-function ghostel--focus-event "ghostel-module")
 (declare-function ghostel--mode-enabled "ghostel-module")
@@ -3052,12 +3053,20 @@ No-op when `ghostel--snap-requested' (user input overrides)."
 Also resets pixel vscroll (pixel-scroll-precision-mode may leave a
 partial offset that would clip the top line after a redraw).
 
-When the TUI cursor is in pending-wrap state on the last visible row,
-PT equals `point-max' (one past the last character).  Emacs redisplay
-then classifies it as off-screen, and `scroll-conservatively' shifts
-`window-start' up by one row to make it visible — which fights the
-viewport pin and makes the block cursor disappear.  Clamp
-`window-point' back by one only in that case so it sits inside the
+Two terminal-side configurations land PT at `point-max' on the last
+visible row in a position Emacs redisplay treats as off-screen — which
+makes `scroll-conservatively' shift `window-start' up by one row,
+fighting the viewport pin and hiding the block cursor:
+
+ 1. Pending-wrap: the last printed character filled the rightmost
+    column and the next print will soft-wrap (issue #138).
+
+ 2. CUP park onto an empty trailing row, no pending-wrap: the TUI
+    moved the cursor via absolute positioning to a row that has no
+    written cells, so the row renders to an empty buffer line and PT
+    lands at `point-max' (issue #157).
+
+Clamp `window-point' back by one in either case so it sits inside the
 viewport; buffer-point is unaffected and subsequent redraws recapture
 the real cursor.  We must NOT clamp for a plain shell prompt where the
 cursor is legitimately at `point-max' after typing — doing so would
@@ -3068,8 +3077,10 @@ draw the block cursor on the last character instead of after it
   (set-window-point win (if (and (= pt (point-max))
                                  (> pt (point-min))
                                  ghostel--term
-                                 (ghostel--cursor-pending-wrap-p
-                                  ghostel--term))
+                                 (or (ghostel--cursor-pending-wrap-p
+                                      ghostel--term)
+                                     (ghostel--cursor-on-empty-row-p
+                                      ghostel--term)))
                             (1- pt)
                           pt)))
 

src/module.zig

@@ -13,7 +13,7 @@ const input = @import("input.zig");
 const c = emacs.c;
 
 /// Module version — keep in sync with ghostel.el and build.zig.zon.
-const version = "0.16.2";
+const version = "0.16.3";
 
 // ---------------------------------------------------------------------------
 // Module entry point
@@ -45,6 +45,7 @@ export fn emacs_module_init(runtime: *c.struct_emacs_runtime) callconv(.c) c_int
     env.bindFunction("ghostel--alt-screen-p", 1, 1, &fnAltScreen, "Return t if terminal is on the alternate screen buffer.\n\n(ghostel--alt-screen-p TERM)");
     env.bindFunction("ghostel--cursor-position", 1, 1, &fnCursorPosition, "Return terminal cursor position as (COL . ROW), 0-indexed.\n\n(ghostel--cursor-position TERM)");
     env.bindFunction("ghostel--cursor-pending-wrap-p", 1, 1, &fnCursorPendingWrap, "Return t if the cursor is in pending-wrap state.\n\n(ghostel--cursor-pending-wrap-p TERM)");
+    env.bindFunction("ghostel--cursor-on-empty-row-p", 1, 1, &fnCursorOnEmptyRow, "Return t if the cursor row has no written cells or styled cells.\n\n(ghostel--cursor-on-empty-row-p TERM)");
     env.bindFunction("ghostel--debug-state", 1, 1, &fnDebugState, "Return debug info about terminal/render state.\n\n(ghostel--debug-state TERM)");
     env.bindFunction("ghostel--debug-feed", 2, 2, &fnDebugFeed, "Feed STR to terminal and return first row + cursor.\n\n(ghostel--debug-feed TERM STR)");
     env.bindFunction("ghostel--copy-all-text", 1, 1, &fnCopyAllText, "Return entire scrollback as plain text string.\n\n(ghostel--copy-all-text TERM)");
@@ -1046,6 +1047,34 @@ fn fnCursorPendingWrap(raw_env: ?*c.emacs_env, _: isize, args: [*c]c.emacs_value
     return if (pending) env.t() else env.nil();
 }
 
+/// (ghostel--cursor-on-empty-row-p TERM)
+/// Return t if the row containing the active cursor has no written
+/// cells and no cells with non-default style — i.e. the row renders to
+/// an empty Emacs buffer line.  Used alongside pending-wrap by
+/// `ghostel--anchor-window' to detect TUI CUP parks onto a trailing
+/// empty row, which also land `point' at `point-max' on the last
+/// visible row and would otherwise provoke a redisplay-induced scroll.
+fn fnCursorOnEmptyRow(raw_env: ?*c.emacs_env, _: isize, args: [*c]c.emacs_value, _: ?*anyopaque) callconv(.c) c.emacs_value {
+    const env = emacs.Env.init(raw_env.?);
+    const term = env.getUserPtr(Terminal, args[0]) orelse return env.nil();
+
+    if (gt.c.ghostty_render_state_update(term.render_state, term.terminal) != gt.SUCCESS) return env.nil();
+
+    // Use viewport-relative cursor Y so the row index matches the
+    // viewport iterator `isRowEmptyAt' walks. Falls back to nil when
+    // the cursor isn't visible in the current viewport (e.g. scrolled
+    // into scrollback), which is also the safe answer for the clamp.
+    var has_value: bool = false;
+    _ = gt.c.ghostty_render_state_get(term.render_state, gt.RS_DATA_CURSOR_VIEWPORT_HAS_VALUE, @ptrCast(&has_value));
+    if (!has_value) return env.nil();
+
+    var cy: u16 = 0;
+    if (gt.c.ghostty_render_state_get(term.render_state, gt.RS_DATA_CURSOR_VIEWPORT_Y, @ptrCast(&cy)) != gt.SUCCESS) {
+        return env.nil();
+    }
+    return if (render.isRowEmptyAt(term, cy)) env.t() else env.nil();
+}
+
 /// (ghostel--copy-all-text TERM)
 /// Return the entire scrollback as a plain text string using the formatter API.
 fn fnCopyAllText(raw_env: ?*c.emacs_env, _: isize, args: [*c]c.emacs_value, _: ?*anyopaque) callconv(.c) c.emacs_value {

src/render.zig

@@ -425,6 +425,45 @@ fn isRowPrompt(term: *Terminal) bool {
     return semantic != 0;
 }
 
+/// Return true if row `cy` (0-indexed, viewport-relative) renders to an
+/// empty Emacs buffer line — no cell has a grapheme and no cell has
+/// non-default styling.  Matches `buildRowContent`'s trim rules: a row
+/// for which this returns true produces `byte_len == 0`.
+///
+/// Assumes the caller has refreshed the render state (via
+/// `ghostty_render_state_update`).  Drives the row iterator, so callers
+/// must not rely on iterator position after this call.
+pub fn isRowEmptyAt(term: *Terminal, cy: u16) bool {
+    if (gt.c.ghostty_render_state_get(term.render_state, gt.RS_DATA_ROW_ITERATOR, @ptrCast(&term.row_iterator)) != gt.SUCCESS) return false;
+
+    var ri: u16 = 0;
+    while (ri <= cy) : (ri += 1) {
+        if (!gt.c.ghostty_render_state_row_iterator_next(term.row_iterator)) return false;
+    }
+
+    if (gt.c.ghostty_render_state_row_get(term.row_iterator, gt.RS_ROW_DATA_CELLS, @ptrCast(&term.row_cells)) != gt.SUCCESS) {
+        return false;
+    }
+
+    while (gt.c.ghostty_render_state_row_cells_next(term.row_cells)) {
+        var graphemes_len: u32 = 0;
+        if (gt.c.ghostty_render_state_row_cells_get(term.row_cells, gt.RS_CELLS_DATA_GRAPHEMES_LEN, @ptrCast(&graphemes_len)) == gt.SUCCESS and graphemes_len > 0) {
+            return false;
+        }
+        // Mirror `buildRowContent`: wide-spacer-tail cells are skipped
+        // outright and never contribute to buffer content, even when
+        // they carry non-default styling.
+        var raw_cell: gt.c.GhosttyCell = undefined;
+        if (gt.c.ghostty_render_state_row_cells_get(term.row_cells, gt.c.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW, @ptrCast(&raw_cell)) == gt.SUCCESS) {
+            var wide: c_int = gt.c.GHOSTTY_CELL_WIDE_NARROW;
+            _ = gt.c.ghostty_cell_get(raw_cell, gt.c.GHOSTTY_CELL_DATA_WIDE, @ptrCast(&wide));
+            if (wide == gt.c.GHOSTTY_CELL_WIDE_SPACER_TAIL) continue;
+        }
+        if (!readCellStyle(term.row_cells).isDefault()) return false;
+    }
+    return true;
+}
+
 /// Hash the first ~16 cells of libghostty's first scrollback row using
 /// FNV-1a. Returns 0 if there is no scrollback or if anything fails.
 ///

test/ghostel-test.el

@@ -4022,6 +4022,88 @@ skip the clamp entirely regardless of where PT sits."
     (ghostel--write-input term "XYZXY")
     (should (ghostel--cursor-pending-wrap-p term))))
 
+(ert-deftest ghostel-test-cursor-on-empty-row-p ()
+  "`ghostel--cursor-on-empty-row-p' tracks whether the cursor row is blank."
+  (let ((term (ghostel--new 3 10 100)))
+    ;; Fresh terminal: all rows empty, cursor at (0,0).
+    (should (ghostel--cursor-on-empty-row-p term))
+    ;; Write a character: cursor row 0 now has a grapheme.
+    (ghostel--write-input term "x")
+    (should-not (ghostel--cursor-on-empty-row-p term))
+    ;; CRLF twice: cursor now at (0,2) on an empty row.
+    (ghostel--write-input term "\r\n\r\n")
+    (should (ghostel--cursor-on-empty-row-p term))
+    ;; CUP back to row 0 (1-indexed: row 1).
+    (ghostel--write-input term "\e[1;1H")
+    (should-not (ghostel--cursor-on-empty-row-p term))))
+
+(ert-deftest ghostel-test-anchor-window-clamps-on-empty-row ()
+  "`ghostel--anchor-window' clamps when cursor is CUP-parked on an empty row.
+Regression test for #157: after `ad8536e' narrowed the clamp to
+pending-wrap only, TUIs that move the cursor via CUP to a trailing
+empty row (e.g. Claude Code on focus loss) again produced the #138
+symptom — PT at `point-max', pending-wrap nil, Emacs redisplay shifts
+`window-start' by one row.  The clamp must also fire on an empty
+cursor row, not just on pending-wrap."
+  (let ((buf (generate-new-buffer " *ghostel-test-anchor-empty-row*"))
+        (orig-buf (window-buffer (selected-window))))
+    (unwind-protect
+        (with-current-buffer buf
+          (ghostel-mode)
+          (let* ((term (ghostel--new 3 10 100))
+                 (ghostel--term term)
+                 (ghostel--term-rows 3)
+                 (inhibit-read-only t))
+            (set-window-buffer (selected-window) buf)
+            ;; Fill rows 0 and 1, then CR/LF to land on empty row 2.
+            (ghostel--write-input term "foo\r\nbar\r\n")
+            (should-not (ghostel--cursor-pending-wrap-p term))
+            (should (ghostel--cursor-on-empty-row-p term))
+            (ghostel--redraw term t)
+            (let ((win (selected-window))
+                  (pmax (point-max)))
+              ;; Precondition: PT really does land at point-max on the
+              ;; empty last row.
+              (should (= pmax (point)))
+              (ghostel--anchor-window win (point-min) pmax)
+              ;; Clamp fires: window-point pulled back by one.
+              (should (= (1- pmax) (window-point win))))))
+      (when (buffer-live-p orig-buf)
+        (set-window-buffer (selected-window) orig-buf))
+      (kill-buffer buf))))
+
+(ert-deftest ghostel-test-anchor-window-no-clamp-on-populated-last-row ()
+  "`ghostel--anchor-window' must NOT clamp when the cursor row has content.
+Complements the #157 regression: when the cursor sits at `point-max' on
+the last visible row but that row has a written grapheme (e.g. a shell
+prompt after typing), neither predicate fires and the block cursor must
+stay at PT so it renders after the last character (#146 contract)."
+  (let ((buf (generate-new-buffer " *ghostel-test-anchor-populated-last*"))
+        (orig-buf (window-buffer (selected-window))))
+    (unwind-protect
+        (with-current-buffer buf
+          (ghostel-mode)
+          (let* ((term (ghostel--new 3 10 100))
+                 (ghostel--term term)
+                 (ghostel--term-rows 3)
+                 (inhibit-read-only t))
+            (set-window-buffer (selected-window) buf)
+            ;; Walk to the last row and type a short prompt — cursor ends
+            ;; mid-row on content, well short of pending-wrap.
+            (ghostel--write-input term "\r\n\r\n$ ls")
+            (should-not (ghostel--cursor-pending-wrap-p term))
+            (should-not (ghostel--cursor-on-empty-row-p term))
+            (ghostel--redraw term t)
+            (let ((win (selected-window))
+                  (pmax (point-max)))
+              (should (= pmax (point)))
+              (ghostel--anchor-window win (point-min) pmax)
+              ;; No clamp: window-point stays at PT.
+              (should (= pmax (window-point win))))))
+      (when (buffer-live-p orig-buf)
+        (set-window-buffer (selected-window) orig-buf))
+      (kill-buffer buf))))
+
 (ert-deftest ghostel-test-anchor-window-clamps-on-pending-wrap ()
   "`ghostel--anchor-window' clamps `window-point' only in pending-wrap state.
 Regression test for #138 (clamp must fire) and #146 (clamp must NOT fire