Skip to content

Make evil-ghostel ESC routing discoverable#543

Open
dakra wants to merge 2 commits into
mainfrom
fix/escape-routing-discoverability
Open

Make evil-ghostel ESC routing discoverable#543
dakra wants to merge 2 commits into
mainfrom
fix/escape-routing-discoverability

Conversation

@dakra

@dakra dakra commented Jul 14, 2026

Copy link
Copy Markdown
Owner

Closes #539

New evil/Doom users starting a fullscreen TUI (e.g. Claude Code with /tui fullscreen) felt trapped: with the default auto routing, alt-screen ESC goes to the app, so normal state is unreachable via ESC, the leader key is dead in insert state, and nothing pointed at the escape hatch.

Discoverability (febcb6d)

  • One-time hint: the first time auto routing sends ESC to an alt-screen app, the echo area shows ESC sent to the terminal app (alt-screen); C-c C-r routes it to evil instead (once per session).
  • C-c C-r is bound to evil-ghostel-toggle-send-escape, now a two-state toggle: from auto it switches to whichever mode differs from auto's current effect (evil while an alt-screen app runs, terminal otherwise); from an explicit mode back to auto. Every press visibly changes the routing — previously, cycling autoterminal in an alt-screen app changed nothing observable, which is exactly what confused users in Need more visibility on evil-ghostel-toggle-send-esc #539. Numeric prefixes 1/2/3 still set a mode directly, and landing on auto messages the effective routing (auto (now → terminal)).
  • C-c <escape> runs evil-force-normal-state as a one-shot switch that leaves the routing untouched. It's bound on the <escape> function key, so it works on GUI frames and on ttys speaking the kitty keyboard protocol (via kkp.el); on legacy ttys the event never occurs, so it can't shadow the C-c M-… bindings.
  • Docs: new ESC routing section in the manual, a note in the main README, a new extensions/evil-ghostel/README.md, and an expanded package commentary.

Alt-screen detection cleanup (d206461)

Three different alt-screen checks existed: the native ghostel--alt-screen-p (reads the active screen), line-mode's 1049-or-1047 mode query, and evil-ghostel's 1049-only query. The mode queries miss alt screens entered via other DEC modes — e.g. auto ESC routing kept ESC in evil for a TUI using mode 1047.

A new public ghostel-alt-screen-p wraps the native check and is now used for line-mode pause/resume and all evil-ghostel alt-screen decisions; tests stub the native function instead of ghostel--mode-enabled. The extension .elc Make rule also gained a dependency on the core .elc files so parallel builds can't compile evil-ghostel against a stale ghostel.elc.

Testing

  • make -j8 all (build, elisp + native tests, lint) and make test-evil (130/130) pass.
  • Live-verified in real Emacs sessions (tty and GUI): the trapped-user journey from Need more visibility on evil-ghostel-toggle-send-esc #539, the hint, the toggle in and out of alt-screen, C-c <escape> on a GUI frame, and the mode-1047/47 coverage of the new predicate (where the old flag check provably returned nil).

dakra added 2 commits July 14, 2026 23:04
New evil users starting a fullscreen TUI (e.g. Claude Code) felt trapped:
with the default auto routing, alt-screen ESC goes to the app, so normal
state is unreachable via ESC and nothing pointed at the escape hatch.

- Show a one-time echo-area hint the first time auto routing sends ESC to
  an alt-screen app.
- Bind C-c C-r to evil-ghostel-toggle-send-escape and turn it into a
  two-state toggle: auto flips to whichever mode differs from auto's
  current effect (evil in alt-screen, terminal otherwise); explicit modes
  return to auto.  Every press now visibly changes the routing.
- Show the effective routing in the toggle's message when landing on auto.
- Bind C-c <escape> to evil-force-normal-state as a one-shot switch that
  leaves the routing untouched (function-key event: GUI frames, or ttys
  with the kitty keyboard protocol via kkp.el).
- Document ESC routing in the manual, the main README, a new
  extension README, and the package commentary.

Closes #539
Three different alt-screen checks existed: the native ghostel--alt-screen-p
(reads the active screen), line-mode's 1049-or-1047 mode query, and
evil-ghostel's 1049-only query.  The mode queries miss alt screens entered
via other DEC modes (47, 1047) — e.g. evil-ghostel's auto ESC routing kept
ESC in evil for a TUI using 1047.

Add ghostel-alt-screen-p, a public wrapper around the native check, and use
it for line-mode pause/resume and all evil-ghostel alt-screen decisions.
Tests stub the native ghostel--alt-screen-p instead of ghostel--mode-enabled.

Also give the extension .elc rule a dependency on the core .elc files so a
parallel build cannot compile evil-ghostel against a stale ghostel.elc that
predates a newly added core function.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Need more visibility on evil-ghostel-toggle-send-esc

1 participant