# 機能設計書 18-ペインを閉じる

## 概要

本ドキュメントは、Windows Terminalにおける現在フォーカスされたペインを閉じる機能（ClosePane アクション）の設計を記述する。

### 本機能の処理概要

現在フォーカスされているペインを閉じる機能である。ペインが読み取り専用モードの場合は確認ダイアログを表示し、ユーザーの承認後にペインを閉じる。閉じる前にペインの復元情報を保存し、後でRestoreLastClosed機能で復元可能にする。タブ内の最後のペインが閉じられた場合、タブ自体も閉じられる。

**業務上の目的・背景**：不要になったターミナルセッションを個別に閉じることで、画面を整理し作業効率を維持する。タブ全体を閉じるのではなく、特定のペインのみを閉じられるため、他のペインでの作業を中断せずに済む。

**機能の利用シーン**：分割された複数のペインのうち、不要になったペインを閉じる場面で使用される。Ctrl+Shift+Wなどのキーバインドで実行するのが一般的。

**主要な処理内容**：
1. ClosePaneアクションの受信
2. _CloseFocusedPaneの呼び出し
3. フォーカス中のタブとペインの取得
4. ズーム状態の解除（_UnZoomIfNeeded）
5. 読み取り専用ペインの場合、確認ダイアログ表示（_PaneConfirmCloseReadOnly）
6. _HandleClosePaneRequestedによる復元データ保存
7. Pane::Close()によるペインの閉じ処理

**関連システム・外部連携**：外部連携なし。

**権限による制御**：読み取り専用ペインの場合、確認ダイアログでユーザーの承認が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleClosePaneによりフォーカス中のペインを閉じる |
| 16 | CloseReadOnlyDialog（読み取り専用警告） | 確認画面 | 読み取り専用セッション閉じの警告表示 |

## 機能種別

UI操作 / ペイン構造変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | ClosePaneアクションにパラメータなし | - |

### 入力データソース

キーバインド、コマンドパレット、またはプログラム的なアクション実行。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 復元データ | std::vector<ActionAndArgs> | 閉じたペインの復元に必要なアクションのリスト |

### 出力先

ペインツリーから対象ペインを除去。復元データは _previouslyClosedPanesAndTabs スタックに保存。

## 処理フロー

### 処理シーケンス

```
1. _HandleClosePane が呼び出される
   └─ _CloseFocusedPane() を呼び出し
2. _CloseFocusedPane() の処理（コルーチン）
   ├─ _GetFocusedTabImpl() でフォーカス中のタブを取得
   ├─ _UnZoomIfNeeded() でズーム解除
   └─ activeTab->GetActivePane() でフォーカス中のペインを取得
3. 読み取り専用チェック
   └─ co_await _PaneConfirmCloseReadOnly(pane)
       ├─ 読み取り専用でない → true を返す
       └─ 読み取り専用 → 確認ダイアログを表示、ユーザーの応答を待つ
4. _HandleClosePaneRequested(pane) の処理
   ├─ BuildStartupActions で復元アクションを生成
   ├─ SplitPaneアクションを先頭に追加
   ├─ _AddPreviouslyClosedPaneOrTab で保存
   └─ pane->Close() でペインを閉じる
5. args.Handled(true) を設定
```

### フローチャート

```mermaid
flowchart TD
    A[ClosePane アクション受信] --> B[_CloseFocusedPane 呼び出し]
    B --> C[フォーカス中のタブ・ペイン取得]
    C --> D[_UnZoomIfNeeded]
    D --> E{読み取り専用?}
    E -->|Yes| F[確認ダイアログ表示]
    E -->|No| G[_HandleClosePaneRequested]
    F --> H{ユーザー承認?}
    H -->|Yes| G
    H -->|No| I[処理終了]
    G --> J[BuildStartupActions で復元データ生成]
    J --> K[_AddPreviouslyClosedPaneOrTab]
    K --> L[Pane::Close]
    L --> M[Handled = true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-18-01 | 読み取り専用確認 | 読み取り専用ペインを閉じる場合、確認ダイアログを表示する | ペインが読み取り専用モードの場合 |
| BR-18-02 | 復元データ保存 | ペイン閉じ前に復元データを _previouslyClosedPanesAndTabs に保存する | 常時 |
| BR-18-03 | 最後のペイン閉じ | タブ内の最後のペインが閉じられた場合、タブ自体も閉じられる | ペインのClosedイベント処理 |
| BR-18-04 | ズーム解除 | ペインを閉じる前にズーム状態を解除する | ペインがズームされている場合 |

### 計算ロジック

特になし。

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | タブ/ペイン未取得 | フォーカス中のタブまたはペインが取得できない場合 | 処理をスキップ |
| なし | ユーザーキャンセル | 読み取り専用確認ダイアログでキャンセルされた場合 | ペインを閉じない |

### リトライ仕様

リトライ不要。

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

トランザクション管理なし。

## パフォーマンス要件

ペインの閉じ処理は即座に実行されること。コルーチンによる非同期処理だが、確認ダイアログが不要な場合は同期的に完了する。

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

特になし。

## 備考

- _CloseFocusedPane は safe_void_coroutine として実装されており、非同期の確認ダイアログ表示に対応している
- co_await 後の strong reference チェック（weak.get()）により、非同期処理中にTerminalPageが破棄された場合のクラッシュを防止している
- ペインの Close() メソッドは、ペインツリーの再構成とUIの更新をトリガーする

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **96-101行目**: _HandleClosePane の実装。_CloseFocusedPane() を呼び出して args.Handled(true) を設定 |

**主要処理フロー**:
1. **99行目**: _CloseFocusedPane() を呼び出し
2. **100行目**: args.Handled(true) を設定

#### Step 2: ペイン閉じ処理（コルーチン）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TabManagement.cpp | `src/cascadia/TerminalApp/TabManagement.cpp` | **776-794行目**: _CloseFocusedPane の実装（safe_void_coroutine）。タブ/ペイン取得、ズーム解除、読み取り専用チェック、_HandleClosePaneRequested 呼び出し |

**主要処理フロー**:
- **778行目**: _GetFocusedTabImpl() でフォーカス中のタブを取得
- **780行目**: _UnZoomIfNeeded() でズーム解除
- **782行目**: activeTab->GetActivePane() でアクティブペインを取得
- **785行目**: co_await _PaneConfirmCloseReadOnly(pane) で読み取り専用チェック
- **789行目**: _HandleClosePaneRequested(pane) でペインを閉じる

#### Step 3: 復元データ保存とペイン閉じ

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TabManagement.cpp | `src/cascadia/TerminalApp/TabManagement.cpp` | **749-770行目**: _HandleClosePaneRequested。BuildStartupActions で復元データ生成、_AddPreviouslyClosedPaneOrTab で保存、Close() 呼び出し |

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

```
TerminalPage::_HandleClosePane (AppActionHandlers.cpp:96)
    |
    +-- TerminalPage::_CloseFocusedPane() (TabManagement.cpp:776)
            |
            +-- _GetFocusedTabImpl()
            +-- _UnZoomIfNeeded()
            +-- activeTab->GetActivePane()
            |
            +-- co_await _PaneConfirmCloseReadOnly(pane)
            |       +-- [読み取り専用の場合: 確認ダイアログ表示]
            |
            +-- _HandleClosePaneRequested(pane) (TabManagement.cpp:749)
                    |
                    +-- pane->BuildStartupActions(0, 1, None)
                    +-- SplitPaneAction を args に追加
                    +-- _AddPreviouslyClosedPaneOrTab(args)
                    +-- pane->Close()
```

### データフロー図

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

ClosePane         TerminalPage                          ペインツリー
アクション ------> ::_CloseFocusedPane() ------------> (ペイン除去)
                      |                                     |
                      v                                     v
                  _HandleClosePaneRequested()        復元データ保存
                      |                              (スタックに push)
                      v
                  Pane::Close()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleClosePane の実装 |
| TabManagement.cpp | `src/cascadia/TerminalApp/TabManagement.cpp` | ソース | _CloseFocusedPane / _HandleClosePaneRequested の実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | _CloseFocusedPane の宣言 |
| Pane.cpp | `src/cascadia/TerminalApp/Pane.cpp` | ソース | Close / BuildStartupActions の実装 |
| Pane.h | `src/cascadia/TerminalApp/Pane.h` | ヘッダー | Pane クラスの宣言 |
