rendering-layout-performance

TUI の描画、レイアウト、パフォーマンス、代替画面のライフサイクル

TUI の描画が正しくない、ちらつく、CPU を無駄に消費する、サイズ変更を適切に処理できない、スクロールバックが破損する、または堅牢な描画アーキテクチャが必要な場合に、このスキルを使用します。

描画の原則

1. 状態から描画します。 ビューは、現在の状態とターミナルのサイズを純粋に反映したものにします。
2. 書き込みをまとめます。 フレームを構築し、更新を差分化またはキューに追加してから、一度だけフラッシュします。小さな書き込みを何度も行わないでください。
3. ターミナル制御の頻繁な変更を最小限に抑えます。 スタイルのリセット、カーソル移動、画面全体のクリアを繰り返すと、負荷が大きく、リモート接続では目に見える遅延が発生します。
4. 高頻度の入力元を間引きます。 ログ、メトリクス、マウスの移動、サイズ変更の集中、進捗状況の更新を集約します。
5. フレームの所有者を明確にします。 全画面レンダラーが有効な間は画面を占有し、バックグラウンドの出力は別の場所に送ります。

レイアウトのルール

• フレームごと、またはサイズ変更イベントごとに、width と height からレイアウトを計算します。
• 使用可能な最小サイズを定め、そのしきい値を下回った場合は、小さな画面であることを明示するメッセージを表示します。
• 固定座標の代わりに、制約、フレックス、グリッド、分割、またはフレームワークのレイアウト機能を使用します。
• フォーカス、選択状態、ビューポートのオフセット、カーソル位置を UI の状態として保持します。
• 幅が狭い場合、広い場合、高い場合、極端に小さい場合、特殊なサイズの場合をテストします。

代替画面のライフサイクル

終了後に元のスクロールバックへ戻れるようにする場合は、全画面アプリで代替画面を使用します。コマンドの結果を表示したままにする単純な出力では使用しないでください。

終了処理では、次の状態を復元する必要があります。

• 代替画面。
• Raw/cbreak モード。
• マウス追跡。
• ブラケット付きペースト。
• フォーカスモードと拡張キーボードモード。
• カーソルの表示状態とスタイル。
• 変更した場合は、ターミナルのタイトルやパレット。

パフォーマンスのチェックリスト

• UI ループがネットワーク、ディスク、子プロセス、API 呼び出しによってブロックされないこと。
• 時間のかかる処理の進捗状況は、メッセージ、チャネル、タスクを通じて通知すること。
• 特にダッシュボードでは、人が認識できる範囲で描画レートを制限すること。
• 負荷の高い再計算を行う前に、サイズ変更イベントを集約すること。
• 大規模なデータセットを扱うテーブルやリストでは、仮想化またはページ分割を行うこと。
• TUI が画面を占有している間は、ログを stdout/stderr に書き込まないこと。
• サポートする場合は、リモートターミナルや SSH の遅延もテストに含めること。

失敗のパターン

症状	考えられる原因	対処法
ちらつき	画面全体のクリア、または頻繁なフラッシュ	差分化・書き込みの一括処理を行い、画面全体のクリアを避ける
アイドル時の CPU 使用率が高い	無条件の再描画ループ	イベント発生時、または上限を設けた間隔で描画する
クラッシュ後にシェルが破損する	panic/例外時のクリーンアップ漏れ	ターミナルガードを一元化し、finally/defer/drop でクリーンアップする
レイアウトの重なり	絶対座標、または古いサイズ情報	サイズ変更後に制約を再計算する
UI 内にログが表示される	代替画面が有効な間に stdout/stderr へログを書き込んでいる	ファイル出力先、アプリ内ログパネル、またはバッファー付きログを使用する

参考ファイル

• references/render-loop-patterns.md - フレームバッファー、ダーティリージョン、間引き、イベントループ。
• references/alternate-screen-lifecycle.md - セットアップ／終了処理のチェックリストとクラッシュからの復旧。