wasix/tui: WASIX 端末制御と TUI 描画補助ライブラリ

目的もくてき:

• WASIX の tty_get / tty_set を使って端末状態を取得・更新します。
• ANSI エスケープシーケンスを用いたカーソル移動・色制御を提供します。
• 行バッファを使った差分レンダリング機能を提供し、再描画コストを削減します。

実装じっそう:

• 端末状態は WASIX ABI の Tty 構造体レイアウトに合わせてメモリ上で操作します。
• 行バッファは curr と prev の2面を比較し、差分行のみ print します。
• 文字列の表示幅は UTF-8 先頭バイトを用いて概算し、ANSI/OSC8 制御列は幅0として扱います。

注意ちゅうい:

• 表示幅計算は厳密な East Asian Width 判定ではなく、実用上の近似です。
• 端末依存の表示差（フォント、絵文字幅、結合文字など）は吸収しきれません。
• 差分判定は行単位です。1文字だけの更新でも、その行全体を再出力します。

TtyState: WASIX TTY 構造体のメモリレイアウト

目的:

• WASIX ABI の Tty 構造体を扱います。

レイアウト:

• offset 0: cols (u32)
• offset 4: rows (u32)
• offset 8: width (u32)
• offset 12: height (u32)
• offset 16: stdin_tty (u8/bool)
• offset 17: stdout_tty (u8/bool)
• offset 18: stderr_tty (u8/bool)
• offset 19: echo (u8/bool)
• offset 20: line_buffered (u8/bool)
• (24 bytes allocated for safety)

TerminalSize: 端末の列数と行数

目的もくてき:

• get_terminal_size の戻り値を名前付き field で扱い、呼び出し側の意図を明確にします。

注意ちゅうい:

• cols と rows は 0 のことがあります。TTY 取得に失敗した場合も 0,0 を返します。

enter_raw_mode: ターミナルを RAW モードにする

目的:

• echo と line_buffered を無効化します。
• 成功時は以前の TtyState ポインタを返します。

注意(重要):

• 返されたポインタは restore_mode に渡して解放する必要があります。

restore_mode: ターミナルの状態を元に戻す

目的:

• enter_raw_mode で保存した状態を復元します。

get_terminal_size: ターミナルのサイズを取得する

目的もくてき:

• 現在のターミナルの列数と行数を TerminalSize として取得します。

実装じっそう:

• WASIX の TTY 状態を読み、cols / rows を取り出して構造化して返します。

注意ちゅうい:

• 取得に失敗した場合は TerminalSize 0 0 を返します。

--- ANSI 画面制御ヘルパー ---
clear_screen: 画面全体をクリアしてカーソルを左上に移動する
move_cursor: カーソルを (col, row) に移動する (1-indexed)
cursor_home: カーソルを左上 (1,1) に移動する
hide_cursor: カーソルを非表示にする
show_cursor: カーソルを再表示する
clear_line: カーソル行を消去する
set_bg_color: 背景色を設定する (0-7: 標準色)
0=黒 1=赤 2=緑 3=黄 4=青 5=マゼンタ 6=シアン 7=白
set_fg_color: 前景色を設定する (0-7: 標準色)
reset_color: 前景色と背景色をリセットする
repeat_text: 文字列を指定回数だけ連結して返す

目的もくてき:

• 罫線や空白など、同じ文字列を繰り返す行生成を簡潔に記述します。

実装じっそう:

• out に対して concat out s を n 回繰り返します。

注意ちゅうい:

• concat の繰り返しなので、長大文字列ではコストが大きくなります。

計算量けいさんりょう:

• O(n^2)（文字列再確保の影響を含む）

str_display_width: 文字列の表示幅を概算する

目的もくてき:

• 行の右パディングを行う際に、日本語を含む表示の崩れを減らします。

実装じっそう:

• UTF-8 の先頭バイトから文字境界を推定し、ASCII は幅1、非ASCIIは幅2で加算します。
• ANSI CSI（ESC [）と OSC8（ESC ] ... ESC \\）は幅0としてスキップします。

注意ちゅうい:

• 厳密な文字幅計算ではなく、端末依存差を含む近似です。
• ゼロ幅結合や一部絵文字の幅は環境ごとに差が出ます。

計算量けいさんりょう:

• O(n)

line_pad_to_cols: 行文字列を指定表示幅まで右側空白で埋める

目的もくてき:

• 以前の長い行が残る問題を防ぎ、行更新を安定させます。

実装じっそう:

• str_display_width で現在幅を求め、足りない分だけ空白を連結します。

注意ちゅうい:

• 入力が指定幅を超える場合は切り詰めず、そのまま返します。

計算量けいさんりょう:

• O(n)

line_clip_to_cols: 行文字列を指定表示幅以内に切り詰める

目的もくてき:

• 横幅制限がある領域へ安全に描画するため、表示幅ベースで文字列を切り詰めます。

実装じっそう:

• UTF-8 先頭バイトから 1文字ごとのバイト長と概算表示幅を求め、

次の文字を追加すると cols を超える時点で切り出しを終了します。

注意ちゅうい:

• ANSI/OSC8 を含む文字列の厳密処理は対象外です（通常テキスト向け）。
• 幅計算は厳密な East Asian Width 判定ではなく近似です。

計算量けいさんりょう:

• O(n)

text_wrap_lines: 表示幅で折り返した行配列を作る

目的もくてき:

• 長文を端末上で読みやすく表示するため、表示幅単位で複数行へ折り返します。

実装じっそう:

• 改行文字 を明示的な行区切りとして扱います。
• それ以外は UTF-8 先頭バイトから文字幅を推定し、cols を超える前で折り返します。

注意ちゅうい:

• 幅計算は近似です。結合文字や一部絵文字は端末依存差が出ます。
• cols <= 0 の場合は空配列を返します。

計算量けいさんりょう:

• O(n)

buffer_set_wrapped_text: 折り返し文字列を行バッファへ描画する

目的もくてき:

• 指定矩形（開始行と高さ）に、表示幅ベースで折り返したテキストを描画します。

実装じっそう:

• text_wrap_lines で行配列を作成し、上から順に buffer_set_line で反映します。
• 各行は line_clip_to_cols と line_pad_to_cols を通し、幅を安定化します。
• 高さを超える分は切り捨て、不足行は空白行を入れて残像を防ぎます。

注意ちゅうい:

• 行番号は 1-origin です。
• 文字色/背景色は、この関数に渡す前に style_text で付与してください。

計算量けいさんりょう:

• O(n + h) （n: テキスト長, h: 描画高さ）

line_box: 罫線付きの1行（│ ... │）を作る

目的もくてき:

• 枠線付きUIの行構築を簡潔に行います。

実装じっそう:

• 内側幅 cols-2 に合わせて content を右パディングし、両端に縦罫線を付けます。

注意ちゅうい:

• cols < 2 のケースは呼び出し側で回避してください。

line_box_styled: 罫線付きの1行を色付き背景で作る

目的もくてき:

• 行全体の背景色を確実に塗りたい場合に使います。

実装じっそう:

• 先に content を内側幅までパディングし、その結果全体に style_text を適用します。

注意ちゅうい:

• 罫線（│）自体は無色です。内側領域のみ色がつきます。

line_top: 上枠（┌──┐）を作る

目的もくてき:

• ボックス描画の先頭行を生成します。

line_bottom: 下枠（└──┘）を作る

目的もくてき:

• ボックス描画の最終行を生成します。

style_text: 前景色/背景色を付与した文字列を作る

目的もくてき:

• 文字列単位で色付けし、差分レンダリング行に埋め込めるようにします。

実装じっそう:

• ESC[<fg>;<bg>m を前置し、末尾に ESC[0m を付加します。

注意ちゅうい:

• fg,bg は 0..7（ANSI標準色）を前提とします。
• 色シーケンス自体は str_display_width で幅0として扱われます。

hyperlink_text: OSC8 でハイパーリンク付き文字列を作る

目的もくてき:

• 端末が対応している場合にクリック可能なリンクを表示します。

実装じっそう:

• ESC]8;;urlESC\\ + text + ESC]8;;ESC\\ を連結します。

注意ちゅうい:

• OSC8 非対応端末ではリンクとして機能しません。

---- 行バッファ差分レンダリング ----

Buffer レイアウト:

• +0 : cols (i32)
• +4 : rows (i32)
• +8 : curr_lines_ptr (i32) // i32[row] (str ポインタ)
• +12 : prev_lines_ptr (i32) // i32[row] (str ポインタ)

buffer_new: 行バッファを作成する

目的もくてき:

• 差分レンダリングのための curr/prev 行配列を初期化します。

実装じっそう:

• 行数ぶんの str ポインタ配列を2面確保し、空文字列で初期化します。

注意ちゅうい:

• 返り値は buffer_free で解放してください。

buffer_free: 行バッファを解放する

目的もくてき:

• buffer_new で確保したメモリを解放します。

buffer_set_line: row(1-origin) の行文字列を設定する

目的もくてき:

• 次フレームの行内容を curr 側へ登録します。

注意ちゅうい:

• 行番号が範囲外の場合は何もしません。

line_has_escape: 行に ESC 制御文字が含まれるか判定する

目的もくてき:

• 文字単位差分時に、ANSI/OSC8 を含む行を安全に全行更新へフォールバックするために使います。

buffer_present_diff: 差分のある行だけ再描画する

目的もくてき:

• curr と prev を比較し、変更行のみ端末へ出力します。
• 同一行内では先頭差分位置から末尾のみを書き換え、更新量を削減します。

実装じっそう:

• まず str_eq で同一行を判定します。
• 差分行では「最初に異なるバイト位置」を求め、そこから行末までを再描画します。
• ANSI/OSC8 を含む行は安全性のため行全体更新にフォールバックします。
• 描画後は該当行の prev を更新します。

注意ちゅうい:

• UTF-8 文字幅は str_display_width による近似です。
• 差分開始位置はバイト基準で探索し、カーソル列は表示幅換算で計算します。