From 1f2487554b9fd42118f9e99ee06eb558bbb2391f Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Tue, 21 Jul 2026 02:53:44 +0300 Subject: [PATCH] docs: explain Windows cursor and IME trade-off refs #1637 --- .../website/src/content/docs/ja/troubleshooting.mdx | 13 +++++++++++++ .../website/src/content/docs/ja/windows-beta.mdx | 11 ++++++++--- .../website/src/content/docs/troubleshooting.mdx | 13 +++++++++++++ docs/next/website/src/content/docs/windows-beta.mdx | 12 ++++++++---- .../src/content/docs/zh-cn/troubleshooting.mdx | 13 +++++++++++++ .../website/src/content/docs/zh-cn/windows-beta.mdx | 11 ++++++++--- website/src/content/docs/ja/troubleshooting.mdx | 13 +++++++++++++ website/src/content/docs/ja/windows-beta.mdx | 11 ++++++++--- website/src/content/docs/troubleshooting.mdx | 13 +++++++++++++ website/src/content/docs/windows-beta.mdx | 12 ++++++++---- website/src/content/docs/zh-cn/troubleshooting.mdx | 13 +++++++++++++ website/src/content/docs/zh-cn/windows-beta.mdx | 11 ++++++++--- 12 files changed, 126 insertions(+), 20 deletions(-) diff --git a/docs/next/website/src/content/docs/ja/troubleshooting.mdx b/docs/next/website/src/content/docs/ja/troubleshooting.mdx index 3b857512..d1769038 100644 --- a/docs/next/website/src/content/docs/ja/troubleshooting.mdx +++ b/docs/next/website/src/content/docs/ja/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status OS、外側のターミナル名とバージョン、ローカルまたはリモートのどちらか、tmux を使用しているかも記録してください。 +## Windows で CJK IME の UI 位置がずれる、またはカーソルがちらつく + +Herdr は、ConPTY ベースのマルチプレクサーによる画面再描画中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置を表示したりすることを避けるため、ネイティブ Windows と WSL ではデフォルトでセル描画カーソルを使います。セル描画カーソルは、韓国語、日本語、中国語 IME の変換中テキストや候補 UI が使用するネイティブカーソルの基準位置を提供できません。 + +IME の変換中テキストや候補ウィンドウが誤った位置に表示される場合は、ネイティブカーソルを有効にしてください: + +```toml +[ui] +host_cursor = "native" +``` + +ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソル表示が乱れることがあります。視覚的に安定したカーソルへ戻すには `host_cursor = "drawn"` を設定するか、設定を削除して Windows のデフォルトを使ってください。現在の制限については [Windows ベータ](/ja/docs/windows-beta/) を参照してください。 + ## Enter、Tab、Backspace が 2 回入力される 古いターミナルでは、アプリケーションが Kitty キーボードイベント報告を有効にすると、Enter、Tab、Backspace のリリースをプレスと同じバイトとして送ることがあります。送信後は Herdr から重複したバイトを区別できません。 diff --git a/docs/next/website/src/content/docs/ja/windows-beta.mdx b/docs/next/website/src/content/docs/ja/windows-beta.mdx index 8446d9a7..fa526872 100644 --- a/docs/next/website/src/content/docs/ja/windows-beta.mdx +++ b/docs/next/website/src/content/docs/ja/windows-beta.mdx @@ -48,8 +48,9 @@ Windows のエージェントプロセス検出は、ペインのシェルの子 | シェルで `cd` した後のライブ cwd | 部分的 | | シェルインテグレーション/OSC7 によるライブ cwd | ベータ | | エージェントへのクリップボード画像貼り付け | 未検証 | -| CJK の隠れカーソル表示 | ベータ | +| CJK IME の変換候補位置 | 部分的 | | Kitty graphics のレンダリング | 未検証 | +| ホストカーソル描画 | 部分的 | Herdr はペインを正しいディレクトリで起動でき、Herdr を起動したディレクトリから最初のワークスペースを作成できます。起動後の PowerShell のディレクトリ変更は別問題です: Herdr が調べられるプロセスのフィールドは、その後の論理的な `cd` の変化を確実には追跡しません。ライブ cwd の報告には Herdr インテグレーションかプロンプトのシェルインテグレーションを使ってください。 @@ -61,15 +62,19 @@ Kitty graphics は実験的なままで、まだ Windows でのサポートを ### カーソル描画 -Windows のターミナルは ConPTY 経由で Herdr を実行するため、フルスクリーン再描画中にネイティブの端末カーソルがちらついたり、ジャンプしたり、古い位置を一瞬表示したりすることがあります。Herdr のデフォルト `host_cursor = "auto"` は、ネイティブ Windows ビルドと WSL では Herdr のカーソルを端末セルの内容として描画し、それ以外の Linux と macOS ではネイティブの端末カーソルを使い続けます。Windows でのトレードオフは、外側ターミナルのネイティブな点滅、形状、カーソル色の代わりに、Herdr 内で安定した非点滅カーソルを表示することです。 +Herdr はネイティブ Windows のペインに ConPTY を使用します。現在の Windows のターミナルカーソル処理では、マルチプレクサーが画面を再描画している途中のカーソル位置が表示されることがあります。そのため、出力中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置に一瞬残ったりします。この挙動は他のネイティブ Windows ターミナルマルチプレクサーや、VT カーソル位置を直接連続更新するテストでも再現するため、ネイティブカーソルの挙動を維持したまま Herdr 側で完全に解消することはできません。 -ネイティブ Windows または WSL で外側ターミナルのカーソルに戻すには、次を設定してください: +視覚的な安定性を優先するため、デフォルトの `host_cursor = "auto"` はネイティブ Windows と WSL で Herdr のカーソルを端末セルの内容として描画します。それ以外の Linux と macOS クライアントでは、引き続きネイティブの端末カーソルを使います。Windows の描画カーソルは安定していて点滅しませんが、外側ターミナルのネイティブな点滅、形状、カーソル色は反映されません。 + +描画カーソルは、Windows が IME の変換中テキストや候補ウィンドウの位置決めに使う実際のカーソルではありません。そのため、韓国語、日本語、中国語 IME の UI が誤った位置に表示されることがあります。この問題が発生する場合は、外側ターミナルのカーソルを有効にしてください: ```toml [ui] host_cursor = "native" ``` +ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソルのちらつき、ジャンプ、古い位置の残像が再び発生することがあります。これは現在の Windows ベータにおける互換性上のトレードオフです。 + ### キーボードとマウス Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty ではマウス報告と `ctrl+j` を保持しますが、`shift+enter` は外側ターミナルが修飾付き Enter として区別して報告する場合にだけ動作します。Windows またはターミナルがそれを通常の Enter として報告する場合、Herdr は通常の Enter を転送します。 diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx index bbbf5db4..e0df4974 100644 --- a/docs/next/website/src/content/docs/troubleshooting.mdx +++ b/docs/next/website/src/content/docs/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status Also record your operating system, outer terminal name and version, whether the session is local or remote, and whether tmux is involved. +## The CJK IME window is misplaced or the cursor flickers on Windows + +Herdr defaults to a cell-drawn cursor on native Windows and WSL because native cursors can flicker, jump, or show stale positions while ConPTY-based multiplexers repaint the screen. A cell-drawn cursor cannot provide the native cursor anchor used by Korean, Japanese, and Chinese IME composition UI. + +If the IME composition or candidate window appears at the wrong location, enable the native cursor: + +```toml +[ui] +host_cursor = "native" +``` + +Native mode restores the IME anchor but may reintroduce occasional cursor movement artifacts during active output. Return to the visually stable cursor with `host_cursor = "drawn"`, or remove the setting to use the Windows default. See [Windows beta](/docs/windows-beta/) for the current limitation. + ## Enter, Tab, or Backspace fires twice Older terminal versions can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them. diff --git a/docs/next/website/src/content/docs/windows-beta.mdx b/docs/next/website/src/content/docs/windows-beta.mdx index abb9159a..696a77be 100644 --- a/docs/next/website/src/content/docs/windows-beta.mdx +++ b/docs/next/website/src/content/docs/windows-beta.mdx @@ -48,9 +48,9 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc | Live cwd after shell `cd` | partial | | Live cwd via shell integration/OSC7 | beta | | Clipboard image paste to agents | unverified | -| CJK hidden-cursor reveal | beta | +| CJK IME composition anchoring | partial | | Kitty graphics rendering | unverified | -| Host cursor rendering | beta | +| Host cursor rendering | partial | Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical `cd` changes. Use Herdr integrations or prompt shell integration for live cwd reporting. @@ -62,15 +62,19 @@ Kitty graphics remains experimental and is not claimed as Windows-supported yet. ### Cursor rendering -Windows terminals run Herdr through ConPTY, and native terminal cursors can flicker, jump, or briefly show stale positions during active full-screen redraws. Herdr's default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content for native Windows builds and WSL, while other Linux and macOS clients keep using the native terminal cursor. The Windows trade-off is a steady non-blinking cursor inside Herdr instead of the outer terminal's native blink, shape, and cursor color. +Herdr relies on ConPTY for native Windows panes. The current Windows terminal cursor path can expose intermediate cursor positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior. -To opt back into the outer terminal cursor on native Windows or WSL, set: +To prioritize visual stability, the default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal's native blink, shape, or cursor color. + +A drawn cursor is not the cursor that Windows uses to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor: ```toml [ui] host_cursor = "native" ``` +Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output. This is currently a compatibility trade-off in the Windows beta. + ### Keyboard and mouse Windows terminals do not all report modified keys in the same shape. Herdr preserves mouse reporting and `ctrl+j` in Windows Terminal and Alacritty on Windows, but `shift+enter` only works when the outer terminal reports it as a distinct modified Enter key. If Windows or the terminal reports it as plain Enter, Herdr forwards plain Enter. diff --git a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx index 39d23f75..60a41153 100644 --- a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx +++ b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status 同时记录操作系统、外层终端名称和版本、会话是本地还是远程，以及是否使用了 tmux。 +## Windows 上的 CJK 输入法窗口位置错误或光标闪烁 + +Herdr 在原生 Windows 和 WSL 上默认使用单元格绘制光标,因为 ConPTY 多路复用器重绘屏幕时,原生光标可能闪烁、跳动或显示旧位置。单元格绘制光标无法提供韩语、日语和中文输入法预编辑文本及候选窗口所需的原生光标定位。 + +如果输入法预编辑文本或候选窗口出现在错误位置,请启用原生光标: + +```toml +[ui] +host_cursor = "native" +``` + +原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标移动异常。要恢复视觉稳定的光标,请设置 `host_cursor = "drawn"`,或删除该设置以使用 Windows 默认值。当前限制详见 [Windows 测试版](/zh-cn/docs/windows-beta/)。 + ## Enter、Tab 或 Backspace 触发两次 旧版终端在应用启用 Kitty 键盘事件报告后，可能把 Enter、Tab 和 Backspace 的释放事件发送为与按下事件相同的字节。终端发送后，Herdr 无法区分这些重复字节。 diff --git a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx index 4c2adb89..5e922c3a 100644 --- a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx +++ b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx @@ -48,8 +48,9 @@ Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接 | shell `cd` 之后的实时 cwd | 部分支持 | | 通过 shell 集成/OSC7 的实时 cwd | 测试版 | | 向智能体粘贴剪贴板图像 | 未验证 | -| CJK 隐藏光标显示 | 测试版 | +| CJK 输入法候选窗口定位 | 部分支持 | | Kitty graphics 渲染 | 未验证 | +| 主机光标渲染 | 部分支持 | Herdr 可以在正确的目录中启动窗格,并能从你启动 Herdr 的目录创建初始工作区。启动之后 PowerShell 的目录变化则不同: Herdr 能检查的进程字段无法可靠跟踪后续的逻辑 `cd` 变化。实时 cwd 上报请使用 Herdr 集成或提示符 shell 集成。 @@ -61,15 +62,19 @@ Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专 ### 光标渲染 -Windows 终端通过 ConPTY 运行 Herdr,在活跃的全屏重绘期间,原生终端光标可能闪烁、跳动,或短暂显示旧位置。Herdr 默认的 `host_cursor = "auto"` 会在原生 Windows 构建和 WSL 上把 Herdr 光标绘制为终端单元格内容,而其他 Linux 和 macOS 客户端继续使用原生终端光标。Windows 上的取舍是:在 Herdr 内得到稳定的不闪烁光标,但不使用外层终端的原生闪烁、形状和光标颜色。 +Herdr 的原生 Windows 窗格依赖 ConPTY。当前 Windows 终端的光标处理可能会在多路复用器重绘屏幕时显示中间光标位置。因此,在持续输出期间,原生光标可能闪烁、跳动,或短暂留在旧位置。这个现象也能在其他 Windows 原生终端多路复用器以及直接连续更新 VT 光标位置的压力测试中复现,所以 Herdr 无法在保留原生光标行为的同时彻底消除它。 -要在原生 Windows 或 WSL 上改回外层终端光标,请设置: +为了优先保证视觉稳定性,默认的 `host_cursor = "auto"` 会在原生 Windows 和 WSL 上把 Herdr 光标绘制为终端单元格内容。其他 Linux 和 macOS 客户端仍使用原生终端光标。Windows 上的绘制光标稳定且不闪烁,但不会使用外层终端的原生闪烁、形状或光标颜色。 + +绘制光标并不是 Windows 用来定位输入法预编辑文本和候选窗口的真实光标。因此,韩语、日语或中文输入法 UI 可能显示在错误位置。如果遇到这个问题,请改用外层终端光标: ```toml [ui] host_cursor = "native" ``` +原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标闪烁、跳动或旧位置残影。这是当前 Windows 测试版中的兼容性取舍。 + ### 键盘和鼠标 Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。 diff --git a/website/src/content/docs/ja/troubleshooting.mdx b/website/src/content/docs/ja/troubleshooting.mdx index 3b857512..d1769038 100644 --- a/website/src/content/docs/ja/troubleshooting.mdx +++ b/website/src/content/docs/ja/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status OS、外側のターミナル名とバージョン、ローカルまたはリモートのどちらか、tmux を使用しているかも記録してください。 +## Windows で CJK IME の UI 位置がずれる、またはカーソルがちらつく + +Herdr は、ConPTY ベースのマルチプレクサーによる画面再描画中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置を表示したりすることを避けるため、ネイティブ Windows と WSL ではデフォルトでセル描画カーソルを使います。セル描画カーソルは、韓国語、日本語、中国語 IME の変換中テキストや候補 UI が使用するネイティブカーソルの基準位置を提供できません。 + +IME の変換中テキストや候補ウィンドウが誤った位置に表示される場合は、ネイティブカーソルを有効にしてください: + +```toml +[ui] +host_cursor = "native" +``` + +ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソル表示が乱れることがあります。視覚的に安定したカーソルへ戻すには `host_cursor = "drawn"` を設定するか、設定を削除して Windows のデフォルトを使ってください。現在の制限については [Windows ベータ](/ja/docs/windows-beta/) を参照してください。 + ## Enter、Tab、Backspace が 2 回入力される 古いターミナルでは、アプリケーションが Kitty キーボードイベント報告を有効にすると、Enter、Tab、Backspace のリリースをプレスと同じバイトとして送ることがあります。送信後は Herdr から重複したバイトを区別できません。 diff --git a/website/src/content/docs/ja/windows-beta.mdx b/website/src/content/docs/ja/windows-beta.mdx index 8446d9a7..fa526872 100644 --- a/website/src/content/docs/ja/windows-beta.mdx +++ b/website/src/content/docs/ja/windows-beta.mdx @@ -48,8 +48,9 @@ Windows のエージェントプロセス検出は、ペインのシェルの子 | シェルで `cd` した後のライブ cwd | 部分的 | | シェルインテグレーション/OSC7 によるライブ cwd | ベータ | | エージェントへのクリップボード画像貼り付け | 未検証 | -| CJK の隠れカーソル表示 | ベータ | +| CJK IME の変換候補位置 | 部分的 | | Kitty graphics のレンダリング | 未検証 | +| ホストカーソル描画 | 部分的 | Herdr はペインを正しいディレクトリで起動でき、Herdr を起動したディレクトリから最初のワークスペースを作成できます。起動後の PowerShell のディレクトリ変更は別問題です: Herdr が調べられるプロセスのフィールドは、その後の論理的な `cd` の変化を確実には追跡しません。ライブ cwd の報告には Herdr インテグレーションかプロンプトのシェルインテグレーションを使ってください。 @@ -61,15 +62,19 @@ Kitty graphics は実験的なままで、まだ Windows でのサポートを ### カーソル描画 -Windows のターミナルは ConPTY 経由で Herdr を実行するため、フルスクリーン再描画中にネイティブの端末カーソルがちらついたり、ジャンプしたり、古い位置を一瞬表示したりすることがあります。Herdr のデフォルト `host_cursor = "auto"` は、ネイティブ Windows ビルドと WSL では Herdr のカーソルを端末セルの内容として描画し、それ以外の Linux と macOS ではネイティブの端末カーソルを使い続けます。Windows でのトレードオフは、外側ターミナルのネイティブな点滅、形状、カーソル色の代わりに、Herdr 内で安定した非点滅カーソルを表示することです。 +Herdr はネイティブ Windows のペインに ConPTY を使用します。現在の Windows のターミナルカーソル処理では、マルチプレクサーが画面を再描画している途中のカーソル位置が表示されることがあります。そのため、出力中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置に一瞬残ったりします。この挙動は他のネイティブ Windows ターミナルマルチプレクサーや、VT カーソル位置を直接連続更新するテストでも再現するため、ネイティブカーソルの挙動を維持したまま Herdr 側で完全に解消することはできません。 -ネイティブ Windows または WSL で外側ターミナルのカーソルに戻すには、次を設定してください: +視覚的な安定性を優先するため、デフォルトの `host_cursor = "auto"` はネイティブ Windows と WSL で Herdr のカーソルを端末セルの内容として描画します。それ以外の Linux と macOS クライアントでは、引き続きネイティブの端末カーソルを使います。Windows の描画カーソルは安定していて点滅しませんが、外側ターミナルのネイティブな点滅、形状、カーソル色は反映されません。 + +描画カーソルは、Windows が IME の変換中テキストや候補ウィンドウの位置決めに使う実際のカーソルではありません。そのため、韓国語、日本語、中国語 IME の UI が誤った位置に表示されることがあります。この問題が発生する場合は、外側ターミナルのカーソルを有効にしてください: ```toml [ui] host_cursor = "native" ``` +ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソルのちらつき、ジャンプ、古い位置の残像が再び発生することがあります。これは現在の Windows ベータにおける互換性上のトレードオフです。 + ### キーボードとマウス Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty ではマウス報告と `ctrl+j` を保持しますが、`shift+enter` は外側ターミナルが修飾付き Enter として区別して報告する場合にだけ動作します。Windows またはターミナルがそれを通常の Enter として報告する場合、Herdr は通常の Enter を転送します。 diff --git a/website/src/content/docs/troubleshooting.mdx b/website/src/content/docs/troubleshooting.mdx index bbbf5db4..e0df4974 100644 --- a/website/src/content/docs/troubleshooting.mdx +++ b/website/src/content/docs/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status Also record your operating system, outer terminal name and version, whether the session is local or remote, and whether tmux is involved. +## The CJK IME window is misplaced or the cursor flickers on Windows + +Herdr defaults to a cell-drawn cursor on native Windows and WSL because native cursors can flicker, jump, or show stale positions while ConPTY-based multiplexers repaint the screen. A cell-drawn cursor cannot provide the native cursor anchor used by Korean, Japanese, and Chinese IME composition UI. + +If the IME composition or candidate window appears at the wrong location, enable the native cursor: + +```toml +[ui] +host_cursor = "native" +``` + +Native mode restores the IME anchor but may reintroduce occasional cursor movement artifacts during active output. Return to the visually stable cursor with `host_cursor = "drawn"`, or remove the setting to use the Windows default. See [Windows beta](/docs/windows-beta/) for the current limitation. + ## Enter, Tab, or Backspace fires twice Older terminal versions can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them. diff --git a/website/src/content/docs/windows-beta.mdx b/website/src/content/docs/windows-beta.mdx index abb9159a..696a77be 100644 --- a/website/src/content/docs/windows-beta.mdx +++ b/website/src/content/docs/windows-beta.mdx @@ -48,9 +48,9 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc | Live cwd after shell `cd` | partial | | Live cwd via shell integration/OSC7 | beta | | Clipboard image paste to agents | unverified | -| CJK hidden-cursor reveal | beta | +| CJK IME composition anchoring | partial | | Kitty graphics rendering | unverified | -| Host cursor rendering | beta | +| Host cursor rendering | partial | Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical `cd` changes. Use Herdr integrations or prompt shell integration for live cwd reporting. @@ -62,15 +62,19 @@ Kitty graphics remains experimental and is not claimed as Windows-supported yet. ### Cursor rendering -Windows terminals run Herdr through ConPTY, and native terminal cursors can flicker, jump, or briefly show stale positions during active full-screen redraws. Herdr's default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content for native Windows builds and WSL, while other Linux and macOS clients keep using the native terminal cursor. The Windows trade-off is a steady non-blinking cursor inside Herdr instead of the outer terminal's native blink, shape, and cursor color. +Herdr relies on ConPTY for native Windows panes. The current Windows terminal cursor path can expose intermediate cursor positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior. -To opt back into the outer terminal cursor on native Windows or WSL, set: +To prioritize visual stability, the default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal's native blink, shape, or cursor color. + +A drawn cursor is not the cursor that Windows uses to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor: ```toml [ui] host_cursor = "native" ``` +Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output. This is currently a compatibility trade-off in the Windows beta. + ### Keyboard and mouse Windows terminals do not all report modified keys in the same shape. Herdr preserves mouse reporting and `ctrl+j` in Windows Terminal and Alacritty on Windows, but `shift+enter` only works when the outer terminal reports it as a distinct modified Enter key. If Windows or the terminal reports it as plain Enter, Herdr forwards plain Enter. diff --git a/website/src/content/docs/zh-cn/troubleshooting.mdx b/website/src/content/docs/zh-cn/troubleshooting.mdx index 39d23f75..60a41153 100644 --- a/website/src/content/docs/zh-cn/troubleshooting.mdx +++ b/website/src/content/docs/zh-cn/troubleshooting.mdx @@ -12,6 +12,19 @@ herdr status 同时记录操作系统、外层终端名称和版本、会话是本地还是远程，以及是否使用了 tmux。 +## Windows 上的 CJK 输入法窗口位置错误或光标闪烁 + +Herdr 在原生 Windows 和 WSL 上默认使用单元格绘制光标,因为 ConPTY 多路复用器重绘屏幕时,原生光标可能闪烁、跳动或显示旧位置。单元格绘制光标无法提供韩语、日语和中文输入法预编辑文本及候选窗口所需的原生光标定位。 + +如果输入法预编辑文本或候选窗口出现在错误位置,请启用原生光标: + +```toml +[ui] +host_cursor = "native" +``` + +原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标移动异常。要恢复视觉稳定的光标,请设置 `host_cursor = "drawn"`,或删除该设置以使用 Windows 默认值。当前限制详见 [Windows 测试版](/zh-cn/docs/windows-beta/)。 + ## Enter、Tab 或 Backspace 触发两次 旧版终端在应用启用 Kitty 键盘事件报告后，可能把 Enter、Tab 和 Backspace 的释放事件发送为与按下事件相同的字节。终端发送后，Herdr 无法区分这些重复字节。 diff --git a/website/src/content/docs/zh-cn/windows-beta.mdx b/website/src/content/docs/zh-cn/windows-beta.mdx index 4c2adb89..5e922c3a 100644 --- a/website/src/content/docs/zh-cn/windows-beta.mdx +++ b/website/src/content/docs/zh-cn/windows-beta.mdx @@ -48,8 +48,9 @@ Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接 | shell `cd` 之后的实时 cwd | 部分支持 | | 通过 shell 集成/OSC7 的实时 cwd | 测试版 | | 向智能体粘贴剪贴板图像 | 未验证 | -| CJK 隐藏光标显示 | 测试版 | +| CJK 输入法候选窗口定位 | 部分支持 | | Kitty graphics 渲染 | 未验证 | +| 主机光标渲染 | 部分支持 | Herdr 可以在正确的目录中启动窗格,并能从你启动 Herdr 的目录创建初始工作区。启动之后 PowerShell 的目录变化则不同: Herdr 能检查的进程字段无法可靠跟踪后续的逻辑 `cd` 变化。实时 cwd 上报请使用 Herdr 集成或提示符 shell 集成。 @@ -61,15 +62,19 @@ Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专 ### 光标渲染 -Windows 终端通过 ConPTY 运行 Herdr,在活跃的全屏重绘期间,原生终端光标可能闪烁、跳动,或短暂显示旧位置。Herdr 默认的 `host_cursor = "auto"` 会在原生 Windows 构建和 WSL 上把 Herdr 光标绘制为终端单元格内容,而其他 Linux 和 macOS 客户端继续使用原生终端光标。Windows 上的取舍是:在 Herdr 内得到稳定的不闪烁光标,但不使用外层终端的原生闪烁、形状和光标颜色。 +Herdr 的原生 Windows 窗格依赖 ConPTY。当前 Windows 终端的光标处理可能会在多路复用器重绘屏幕时显示中间光标位置。因此,在持续输出期间,原生光标可能闪烁、跳动,或短暂留在旧位置。这个现象也能在其他 Windows 原生终端多路复用器以及直接连续更新 VT 光标位置的压力测试中复现,所以 Herdr 无法在保留原生光标行为的同时彻底消除它。 -要在原生 Windows 或 WSL 上改回外层终端光标,请设置: +为了优先保证视觉稳定性,默认的 `host_cursor = "auto"` 会在原生 Windows 和 WSL 上把 Herdr 光标绘制为终端单元格内容。其他 Linux 和 macOS 客户端仍使用原生终端光标。Windows 上的绘制光标稳定且不闪烁,但不会使用外层终端的原生闪烁、形状或光标颜色。 + +绘制光标并不是 Windows 用来定位输入法预编辑文本和候选窗口的真实光标。因此,韩语、日语或中文输入法 UI 可能显示在错误位置。如果遇到这个问题,请改用外层终端光标: ```toml [ui] host_cursor = "native" ``` +原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标闪烁、跳动或旧位置残影。这是当前 Windows 测试版中的兼容性取舍。 + ### 键盘和鼠标 Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。