# 機能設計書 87-コマンドパレット

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるコマンドパレット機能の設計仕様を記載する。

### 本機能の処理概要

コマンドパレット機能は、利用可能なアクションを検索・実行できるポップアップUIを提供する機能である。VS Codeのコマンドパレットに類似したインターフェースで、キーバインドを覚えていなくてもアクションを素早く実行できる。

**業務上の目的・背景**：
多数のキーバインドやアクションを覚えることなく、検索によって目的のアクションを素早く見つけて実行できるようにする。特にGhosttyを使い始めたユーザーや、頻繁に使用しないアクションを実行する際に有用。

**機能の利用シーン**：
- キーバインドを忘れた際にアクションを検索して実行
- 利用可能なアクションを探索的に確認
- 特定のウィンドウ/タブにフォーカスをジャンプ

**主要な処理内容**：
1. キーバインドアクション`toggle_command_palette`を受け取る
2. コマンドパレットダイアログを表示
3. 設定からコマンド一覧を読み込み、フィルタリング
4. ユーザーの検索入力でコマンドをフィルタ
5. 選択されたアクションを実行

**関連システム・外部連携**：
- libadwaita 1.5以降（GTK環境）
- キーバインドシステム

**権限による制御**：
特に権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 遷移元 | コマンドパレット呼び出し |
| 5 | コマンドパレット | 主画面 | コマンド検索・実行のためのパレット表示 |

## 機能種別

ユーザー操作 / UI

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (トグルアクション) | - | - | パラメータなしのアクション | - |
| 検索文字列 | string | No | コマンドのフィルタリング用 | - |

### 入力データソース

- キーバインドアクション
- 設定ファイル（command-palette-entry）
- ユーザーの検索入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コマンドパレットUI | ダイアログ | 検索可能なコマンド一覧 |
| 実行結果 | アクション | 選択されたコマンドの実行 |

### 出力先

アプリケーションUI

## 処理フロー

### 処理シーケンス

```
1. アクション受信
   └─ toggle_command_paletteアクション
2. パレット表示切り替え
   ├─ 表示中: 閉じる
   └─ 非表示: 開く
3. コマンド一覧の構築
   ├─ 設定からコマンドを読み込み
   ├─ ジャンプコマンドを収集
   └─ プラットフォーム非対応アクションをフィルタ
4. 検索入力処理
   └─ 入力文字列でコマンドをフィルタ
5. コマンド実行
   └─ 選択されたコマンドのアクションを実行
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_command_palette] --> B{パレット表示中?}
    B -->|Yes| C[パレット閉じる]
    B -->|No| D[パレット開く]
    D --> E[コマンド一覧構築]
    E --> F[ジャンプコマンド収集]
    F --> G[設定コマンド読み込み]
    G --> H[非対応アクションフィルタ]
    H --> I[一覧表示]
    I --> J{ユーザー入力}
    J -->|検索文字列| K[コマンドフィルタ]
    K --> I
    J -->|Enter/クリック| L[コマンド選択]
    J -->|Escape| C
    L --> M{ジャンプコマンド?}
    M -->|Yes| N[サーフェスにフォーカス]
    M -->|No| O[アクション実行シグナル]
    N --> C
    O --> C
    C --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-87-01 | libadwaita要件 | Linux環境ではlibadwaita 1.5以降が必要 | GTK環境 |
| BR-87-02 | プラットフォームフィルタ | GTKでは一部アクション（undo, redo等）がフィルタされる | GTK環境 |
| BR-87-03 | ジャンプコマンド | 各サーフェスへのフォーカスジャンプコマンドを自動生成 | 常時 |
| BR-87-04 | ソート順 | コマンドはタイトルのアルファベット順（大文字小文字無視）でソート | 常時 |

### 計算ロジック

フィルタリング: 検索文字列がコマンドタイトルに部分一致するかを判定

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | libadwaitaバージョン不足 | 機能を無効化 |
| OutOfMemory | メモリエラー | コマンド構築時 | ログ出力、コマンドをスキップ |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- コマンド一覧の構築は設定変更時のみ
- 検索フィルタリングはリアルタイムで動作

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

特になし。

## 備考

- macOSでは独自実装、GTKではlibadwaitaのAdwDialogを使用
- コマンドパレットエントリは設定ファイルでカスタマイズ可能

---

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

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

### 推奨読解順序

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

まず、コマンドの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.zig | `src/input/command.zig` | Command構造体の定義（18-86行目） |

**読解のコツ**: `Command`は`action`、`title`、`description`を持ち、キーバインドアクションと紐づく。

**主要処理フロー**:
- **18-29行目**: Command構造体の定義
- **88-113行目**: defaultsコンパイル時定数（デフォルトコマンド一覧）
- **128-133行目**: actionCommandsでアクションごとのコマンドを定義

#### Step 2: アクション定義を理解する

コマンドパレットのトグルアクション。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Binding.zig | `src/input/Binding.zig` | toggle_command_palette アクション定義（740-748行目） |
| 2-2 | action.zig | `src/apprt/action.zig` | toggle_command_palette アクション定義（117-118行目） |

#### Step 3: GTK実装を理解する

GTK環境でのコマンドパレット実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | CommandPalette GObjectクラス |

**主要処理フロー**:
- **23-33行目**: CommandPalette extern struct定義
- **66-86行目**: Private構造体（dialog, search, view, model, source）
- **182-207行目**: collectRegularCommands - 設定からコマンドを収集
- **209-223行目**: isActionSupportedOnGtk - GTK非対応アクションをフィルタ
- **225-243行目**: collectJumpCommands - ジャンプコマンドを収集
- **310-326行目**: toggle - パレットの表示/非表示切り替え
- **330-364行目**: activated - コマンド選択時の処理

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

```
キーバインドアクション
    │
    └─ toggle_command_palette
           │
           ▼
    action.zig
           │
           └─ performAction(.toggle_command_palette)
                  │
                  ▼
           [GTK環境]
                  │
                  ▼
           command_palette.zig#toggle()
                  │
                  ├─ パレット閉じる (表示中)
                  │
                  └─ パレット開く (非表示)
                         │
                         ▼
                  propConfig() (設定変更時)
                         │
                         ├─ collectJumpCommands()
                         │
                         └─ collectRegularCommands()
                                │
                                └─ isActionSupportedOnGtk()
```

### データフロー図

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

キーバインド ───▶ トグルアクション ───▶ パレット表示切替
                                              │
設定ファイル ────────────────────────▶ コマンド一覧構築
                                              │
サーフェス一覧 ─────────────────────▶ ジャンプコマンド生成
                                              │
                                              ▼
                                    フィルタリング
                                              │
                                              ▼
                                    コマンド一覧表示
                                              │
ユーザー入力 ───────────────────────▶ 検索フィルタ
                                              │
                                              ▼
                                    コマンド選択
                                              │
                                              ▼
                                    アクション実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.zig | `src/input/command.zig` | ソース | Command構造体とデフォルトコマンド定義 |
| Binding.zig | `src/input/Binding.zig` | ソース | toggle_command_paletteアクション定義 |
| action.zig | `src/apprt/action.zig` | ソース | apprレベルのアクション定義 |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | GTKコマンドパレット実装 |
| Config.zig | `src/config/Config.zig` | ソース | command-palette-entry設定 |
| window.zig | `src/apprt/gtk/class/window.zig` | ソース | ウィンドウでのパレット管理 |
| surface.zig | `src/apprt/gtk/class/surface.zig` | ソース | サーフェストリガー処理 |
