input-handling

TUI の入力処理、Raw モード、キーボード、マウス、貼り付け、フォーカス

TUI がキー入力を読み取る、ショートカットを処理する、マウスに対応する、テキストを編集する、フォーカスを管理する、または安全な貼り付け動作を必要とする場合に、このスキルを使用します。

入力の契約

• 対話型 TTY セッションでのみ、Raw モードまたは Cbreak モードに切り替えます。
• スクリプト、パイプ、CI には、対話型でない代替手段を用意します。
• 入力のデコードとアプリケーションのアクションを分離します。
• すべてのアクションをキーボードから実行できるようにします。
• マウスへの対応は、任意の段階的な機能強化として扱います。
• ユーザーが再割り当てできる場合を除き、想定されるターミナルのショートカットを維持します。

Raw モードのルール

Raw モードでは行編集が無効になり、シグナルの動作が変わります。処理を一元化し、確実に元の状態へ戻すようにします。Ctrl-C、対応環境での Ctrl-Z／サスペンド、EOF、リサイズ、ターミナルの終了、致命的な例外が発生した場合の動作を確認します。パスワードやトークンはエコーバックしないでください。

キーバインドの設計

優れたキーバインドは、見つけやすく、一貫性があり、競合を考慮しています。

• よく使うアクションのヘルプを常に表示します。
• ワークフロー上のリスクに見合う場合に限り、終了／キャンセルに q、Esc、または Ctrl-C を使用します。
• 破壊的なアクションには確認を求め、取り消せない操作にはより厳格な確認を求めます。
• 設定で変更可能にしない限り、ターミナル、シェル、エディター、マルチプレクサでよく使われるショートカットを横取りしないでください。
• 可能であれば、覚えやすいショートカットとナビゲーションキーの両方に対応します。
• グローバルなショートカットと、フォーカス中のウィジェットで使うショートカットを区別します。

フォーカスモデル

すべての対話要素には、以下が必要です。

• 安定した識別子。
• フォーカス可能かどうかのルール。
• 色だけに頼らない、目に見えるフォーカス表示。
• 適切な場合の Tab／Shift-Tab または矢印キーによる移動。
• 無効化、非表示、モーダル、ネストされたコントロールの明確な動作。
• アクションを実行する前にフォーカスを更新する、マウスクリック時の動作。

貼り付けとマウスの安全性

シェル、エディター、コマンドパレット、複数行入力では、ブラケット付き貼り付けを有効にします。貼り付け開始／終了マーカーを解析し、貼り付けられたテキストをコマンド列ではなくデータとして扱います。マウス入力では、現在のレイアウトに対して座標を検証し、リサイズ後の古いイベントを無視します。

障害の症状

症状	考えられる原因	修正方法
Esc の反応が遅い	パーサーが Alt のプレフィックスとの判別を待っている	タイムアウトを調整するか、フレームワークのプロトコルサポートを使用します
Ctrl-C で終了しない	Raw モードでシグナルが処理されなくなった	Ctrl-C を明示的に割り当て、ターミナルを元の状態に戻します
貼り付けでアクションが実行される	ブラケット付き貼り付けが無効、または貼り付けをキー入力として扱っている	貼り付けプロトコルを有効にし、テキストとして処理します
マウスクリックで違う行が選択される	リサイズやスクロール後にレイアウトが古くなっている	現在のビューポートに対して座標を検証します
フォーカスが消える	ウィジェットの削除後にフォーカス先が設定されていない	次にフォーカス可能な対象を決定します

リファレンスファイル

• references/input-protocols.md - キーボード、マウス、貼り付け、フォーカス、リサイズのイベントに関する詳細。
• references/keybinding-design.md - ショートカットの設計、競合の回避、フォーム／エディターに関する詳細。