# 機能設計書 97-画面クリア

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「画面クリア」機能の設計を記述する。本機能により、ターミナルの画面とスクロールバック履歴をクリアし、クリーンな表示状態にできる。

### 本機能の処理概要

画面クリア機能は、現在の画面表示とスクロールバック履歴を消去する。ターミナルの状態（モード設定等）は維持したまま、表示内容のみをクリアする。

**業務上の目的・背景**：作業中に画面が出力で埋まった場合、見やすさのためにクリアしたい場合がある。また、スクロールバック履歴に機密情報が含まれる場合、それを消去したい場合もある。シェルの`clear`コマンドやCtrl+Lとは異なり、スクロールバック履歴も消去できる。

**機能の利用シーン**：
- 画面を整理して作業を開始したい場合
- 機密情報を含むスクロールバック履歴を消去したい場合
- デモや画面共有前にクリーンな状態にしたい場合

**主要な処理内容**：
1. ユーザーがclear_screenアクションを実行
2. 代替スクリーンの場合は何もしない（キーバインドを消費しない）
3. 選択範囲をクリア
4. スクロールバック履歴を消去
5. プロンプト位置に基づいて適切にクリア
6. Kittyグラフィックスをクリア
7. 画面が再描画される

**関連システム・外部連携**：シェル統合（プロンプト検出）と連携して適切なクリア動作を行う

**権限による制御**：特になし。全ユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | クリア操作が行われる画面 |

## 機能種別

状態管理 / 画面操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | clear_screenはパラメータなし | - |

### 入力データソース

- キーバインド設定（例: `keybind = cmd+k=clear_screen`）
- コマンドパレットからの選択（「Clear Screen」）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 結果 | bool | true: クリア実行、false: 代替スクリーンのため未実行 |

### 出力先

- 画面表示（クリア後の状態）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがclear_screenアクションを実行
   └─ キーバインド経由（通常Cmd+K / Ctrl+Shift+K）
2. Surface.performBindingActionでアクションを処理
   └─ 代替スクリーンかどうかをチェック
3. 代替スクリーンの場合
   └─ return false（キーバインドを消費しない）
4. プライマリスクリーンの場合
   └─ queueIo(.clear_screen = .{ .history = true })
5. Termio.clearScreenで処理
   └─ 選択範囲をクリア
   └─ スクロールバック履歴を消去
   └─ プロンプト位置に基づいてカーソル上の行を消去
   └─ Kittyグラフィックスをクリア
6. 画面が再描画される
```

### フローチャート

```mermaid
flowchart TD
    A[clear_screenアクション実行] --> B{代替スクリーン?}
    B -->|Yes| C[return false]
    B -->|No| D[clear_screenメッセージ送信]
    D --> E[選択範囲をクリア]
    E --> F[スクロールバック履歴を消去]
    F --> G{プロンプト位置にいる?}
    G -->|Yes| H[プロンプト行を画面上部に移動]
    G -->|No| I[カーソル上の行を消去]
    H --> J[Kittyグラフィックスをクリア]
    I --> J
    J --> K[画面再描画]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-97-1 | 代替スクリーン | 代替スクリーンでは何もしない | screens.active_key == .alternate |
| BR-97-2 | 履歴消去 | スクロールバック履歴を消去する | history = true |
| BR-97-3 | プロンプト保持 | プロンプト行は保持して上部に移動 | cursorIsAtPrompt() == true |
| BR-97-4 | グラフィックス消去 | Kittyグラフィックスも消去される | 常時 |

### 計算ロジック

特になし

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | なし | 特になし | - |

### リトライ仕様

リトライ不要

## トランザクション仕様

トランザクション不要（メモリ上の状態更新のみ）

## パフォーマンス要件

クリア操作は即座に完了すること（100ms以内）

## セキュリティ考慮事項

- スクロールバック履歴を消去できるため、機密情報の消去に有用

## 備考

- `reset`アクションとは異なり、ターミナルモード等の状態は維持される
- 代替スクリーン（vim等）では動作しないため、キーバインドがアプリケーションに渡される

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

アクション定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | clear_screenアクション定義（411行目） |

**読解のコツ**: clear_screenはパラメータなしのアクション。

#### Step 2: エントリーポイントを理解する

Surfaceでのアクション処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | clear_screen処理（5475-5490行目） |

**主要処理フロー**:
1. **5475行目**: clear_screenアクションのマッチング
2. **5481-5485行目**: 代替スクリーンのチェック、代替スクリーンならreturn false
3. **5487-5489行目**: queueIo(.clear_screen = .{ .history = true })

#### Step 3: Termio.clearScreenを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Termio.zig | `src/termio/Termio.zig` | clearScreen関数（583-630行目） |

**主要処理フロー**:
- **592行目**: 代替スクリーンのチェック（二重チェック）
- **595行目**: clearSelection() - 選択範囲をクリア
- **598行目**: eraseDisplay(.scrollback, false) - スクロールバック消去
- **601行目**: cursorIsAtPrompt()チェック
- **602-607行目**: プロンプト位置でない場合、カーソル上の行を消去
- **609-613行目**: Kittyグラフィックスのクリア

### プログラム呼び出し階層図

```
Surface.performBindingAction
    │
    └─ clear_screenアクションを検出
           │
           ├─ 代替スクリーンチェック
           │      └─ return false（代替スクリーンの場合）
           │
           └─ queueIo(.clear_screen = .{ .history = true })
                  │
                  └─ Termio.clearScreen()
                         │
                         ├─ clearSelection()
                         │
                         ├─ eraseDisplay(.scrollback)
                         │
                         ├─ プロンプト位置に基づく処理
                         │
                         └─ Kittyグラフィックスクリア
```

### データフロー図

```
[入力]                    [処理]                         [出力]

キーバインド ───▶ Surface.performBindingAction ───▶ IOメッセージ送信
(Cmd+K等)               │
                        ▼
               代替スクリーンチェック
                        │
                        ▼（プライマリスクリーンの場合）
               Termio.clearScreen()
                        │
                        ├─ 選択クリア
                        ├─ 履歴消去
                        ├─ 画面消去
                        └─ グラフィックス消去 ───▶ 画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | clear_screenアクション定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット用コマンド（232-236行目） |
| Surface.zig | `src/Surface.zig` | ソース | アクション処理のエントリーポイント |
| Termio.zig | `src/termio/Termio.zig` | ソース | clearScreen関数の実装 |
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | eraseDisplay関数 |
