docs: explain Windows cursor and IME trade-off

refs #1637

2 files changed, 21 insertions, 3 deletions

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 を転送します。