From 6172275252f5f724d874163462f5394800f8d55b Mon Sep 17 00:00:00 2001
From: ChihGodlee <61595521+ChihGodlee@users.noreply.github.com>
Date: Wed, 20 May 2026 20:05:38 +0800
Subject: feat(experimental): add reveal_hidden_cursor_for_cjk_ime opt-in for
 CJK IME tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the focused pane requests ?25l (cursor hidden) but paints its own
cursor — common in TUIs like Claude Code, pi, and codex — macOS native
input methods stop tracking the candidate-window position. CJK users
(Chinese / Japanese / Korean) cannot see candidate windows follow as
they type. Setting [experimental] reveal_hidden_cursor_for_cjk_ime = true
exposes the focused pane's cursor anchor to the outer terminal regardless
of the pane's hidden-cursor request, restoring IME tracking for CJK input.

[experimental] cjk_ime_agents is an optional allow-list. When empty,
the reveal applies to any focused pane. When non-empty (e.g.
["claude", "codex"]), the reveal only applies if the focused pane's
detected agent matches one of the listed names. This lets users enable
the workaround only for AI-agent TUIs that paint their own cursor,
leaving plain shells and other programs untouched. Accepted names: pi,
claude, codex, gemini, cursor, cline, opencode, copilot, kimi, kiro,
droid, amp, grok, hermes. Unknown names are ignored.

When the pane reports no cursor position (cursor_state returns None for
some TUIs), the anchor falls back to the pane's top-left so a stable
IME hint is always available.

[experimental] cjk_ime_cursor_shape (default "steady_block") controls
the DECSCUSR shape rendered for the revealed cursor; six variants are
accepted: block, steady_block, underline, steady_underline, bar,
steady_bar.

Trade-off when enabled: a hardware cursor will be visible in the outer
terminal for apps that hide the cursor without painting a replacement.
Default false preserves the behavior set in 2c95071. Pair the reveal
with cjk_ime_agents to scope it to specific TUIs.

Manually verified on macOS 26.5 aarch64 with system Pinyin IME against
Claude Code: candidate window tracks cursor with flag enabled, returns
to anchored-at-start behavior with flag disabled.

refs #149
---
 src/main.rs | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'src/main.rs')

diff --git a/src/main.rs b/src/main.rs
index bbf04df2..440a87a5 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -202,6 +202,19 @@ const DEFAULT_CONFIG: &str = r##"# herdr configuration
 # Experimental local Kitty graphics rendering for attached clients.
 # Requires a Kitty graphics-compatible outer terminal.
 # kitty_graphics = false
+# Expose the focused pane's cursor to the outer terminal so macOS input
+# methods keep tracking the candidate window when TUIs paint their own
+# cursor (Claude Code, pi, codex). Trade-off: extra cursor visible for
+# apps that hide it without painting a replacement (vim normal mode, etc.).
+# reveal_hidden_cursor_for_cjk_ime = false
+# Optional allow-list: only reveal for focused panes whose detected agent
+# matches one of these names. Empty means apply to any focused pane.
+# Accepted: pi, claude, codex, gemini, cursor, cline, opencode, copilot,
+# kimi, kiro, droid, amp, grok, hermes.
+# cjk_ime_agents = []
+# Cursor shape rendered when reveal_hidden_cursor_for_cjk_ime is true.
+# Values: block, steady_block (default), underline, steady_underline, bar, steady_bar.
+# cjk_ime_cursor_shape = "steady_block"
 
 [advanced]
 # Maximum scrollback buffer size in bytes retained per pane terminal.
-- 
cgit v1.2.3