platform-compatibility

プラットフォーム、エミュレーター、マルチプレクサー、リモート環境との互換性

TUI がオペレーティングシステム、ターミナルエミュレーター、マルチプレクサー、SSH セッション、コンテナ、CI、埋め込み型の擬似ターミナルホストで正しく動作する必要がある場合に、このスキルを使用します。

互換性に対する考え方

ターミナルの機能は、アプリケーションライブラリ、OS コンソールまたは PTY、シェル、マルチプレクサー、SSH トランスポート、ターミナルエミュレーター、フォント、テーマ、ユーザー設定という連鎖で成り立っています。各要素が機能を維持できる場合に限り、その機能は信頼できます。アプリケーションが環境全体を管理している場合を除き、高度なプロトコルはすべてオプションとして扱ってください。

定義すべきサポートマトリクス

本番環境向けの TUI では、以下を文書化してテストします。

• OS：Linux、macOS、Windows Terminal、サポート対象の場合は従来の conhost、WSL、コンテナ。
• ターミナルエミュレーター：Terminal.app、iTerm2、Kitty、Alacritty、WezTerm、foot、GNOME Terminal/VTE、Konsole、Windows Terminal。
• マルチプレクサー：tmux、GNU screen、Zellij。
• リモート環境：SSH、mosh のような接続、シリアル接続／低速接続、踏み台ホスト、エージェント転送ポリシー。
• シェルとロケール：UTF-8 ロケール、Windows のコードページ、TERM と terminfo の利用可否。
• 制約：最小サイズ、色レベル、Unicode／ASCII モード、マウス／貼り付けのサポート。

プラットフォームのルール

• Windows では、Windows Terminal/ConPTY と従来のコンソールホストを区別します。低レベルのコンソール API を使用する場合は仮想端末処理を有効にし、UTF-8 を優先してください。該当する場合は、ConPTY を介した子プロセスのホストもテストします。
• Unix 系システムでは、PTY の動作、SIGWINCH、termios の raw/cbreak モードからの復元、プロセスシグナル、ロケールに依存するエンコーディングに対応します。
• macOS では、Terminal.app と iTerm2 で独自プロトコル、Option キーの動作、クリップボード／画像機能、デフォルトの色／テーマ設定が異なります。

マルチプレクサーのルール

• tmux/screen/Zellij は TERM を書き換え、OSC/DCS をフィルタリングし、マウスイベントを変換し、代替画面を仲介することがあります。また、クリップボード、画像、トゥルーカラー、キーボードプロトコルにはパススルー用のラッパーが必要な場合があります。
• 対応を表明するすべてのバージョンについて、マルチプレクサー内外で必ずテストします。
• OSC 52、OSC 8、Kitty graphics、iTerm2 images、フォーカスイベント、拡張キーボードプロトコルに強く依存するのではなく、テキストによる代替手段を優先します。

リモート環境のルール

• SSH 経由での書き込み量とカーソルの移動を最小限に抑えます。
• リサイズの集中発生や高頻度のメトリクス更新をまとめます。
• クリップボード、ローカルファイルパス、画像プロトコル、エージェント転送が利用可能または許可されているとは想定しません。
• 低帯域幅、マウスなし、アニメーションなし、プレーン、バッチの各モードを用意します。

参考ファイル

• references/emulator-platform-matrix.md - OS、エミュレーター、PTY、機能の互換性に関するガイダンス。
• references/multiplexer-remote.md - tmux/screen/Zellij、SSH、レイテンシー、パススルー、リサイズに関する実践方法。