# 機能設計書 35-クイックターミナル

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるクイックターミナル機能の設計を定義する。

### 本機能の処理概要

クイックターミナル機能は、グローバルホットキーで呼び出せるドロップダウン型のターミナルを提供する。画面上部（または設定に応じた位置）からスライドインし、素早いコマンド実行や参照に利用できる。

**業務上の目的・背景**：Quake、Yakuake、Guakeなどのドロップダウンターミナルと同様に、どのアプリケーションを使用中でも素早くターミナルにアクセスできる。短いコマンドの実行やログの確認など、一時的なターミナル操作に最適。

**機能の利用シーン**：
- 作業中に素早くコマンドを実行したい場合
- システム状態を確認したい場合
- クリップボード内容を処理したい場合
- メモやスクラッチパッドとして使用する場合

**主要な処理内容**：
1. グローバルホットキー（toggle_quick_terminal）の受信
2. クイックターミナルの表示/非表示切り替え
3. アニメーション付きのスライドイン/アウト
4. フォーカス管理（前のアプリケーションへの復帰）

**関連システム・外部連携**：
- macOS: グローバルイベントタップ、NSWindow
- Linux/GTK: グローバルホットキー、GtkWindow

**権限による制御**：グローバルホットキー使用時はアクセシビリティ権限が必要（macOS）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | クイックターミナル | 主画面 | ドロップダウンターミナルの表示/非表示 |

## 機能種別

画面制御処理 / ウィンドウ管理 / グローバルホットキー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | パラメータなし（トグル動作） | - |

### 入力データソース

- グローバルホットキー設定（keybind = global:cmd+backquote=toggle_quick_terminal）
- 設定ファイル（quick-terminal-*系設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| visible | bool | クイックターミナルの表示状態 |

### 出力先

- ウィンドウ表示（アニメーション付きスライドイン/アウト）
- 通知（quickTerminalDidChangeVisibility）

## 処理フロー

### 処理シーケンス

```
1. toggle_quick_terminalグローバルホットキー受信
   └─ global:プレフィックス付きキーバインド
2. toggle()を呼び出し
   └─ QuickTerminalController.toggle()
3. 表示/非表示切り替え
   ├─ 非表示の場合: animateIn()
   │   ├─ 前のアプリケーションを記録
   │   ├─ ターミナルが空の場合は初期化
   │   ├─ ドック衝突時は自動非表示
   │   ├─ ウィンドウをアニメーション表示
   │   └─ フォーカスを取得
   └─ 表示の場合: animateOut()
       ├─ 現在のフレームを保存
       ├─ ドックを復元
       ├─ 前のアプリケーションを復元
       └─ ウィンドウをアニメーション非表示
4. 通知を送信
   └─ quickTerminalDidChangeVisibility
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_quick_terminal受信] --> B[toggle呼び出し]
    B --> C{visible?}
    C -->|No| D[animateIn]
    C -->|Yes| E[animateOut]
    D --> F[前アプリ記録]
    F --> G{サーフェスツリー空?}
    G -->|Yes| H[ターミナル初期化]
    G -->|No| I[スキップ]
    H --> J[ドック衝突チェック]
    I --> J
    J --> K[アニメーション表示]
    K --> L[フォーカス取得]
    E --> M[フレーム保存]
    M --> N[ドック復元]
    N --> O[前アプリ復元]
    O --> P[アニメーション非表示]
    L --> Q[通知送信]
    P --> Q
    Q --> R[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-35-01 | グローバルホットキー必須 | toggle_quick_terminalはglobal:プレフィックスが必要 | キーバインド設定時 |
| BR-35-02 | 自動非表示 | quick-terminal-autohide設定でフォーカス喪失時に非表示 | 設定有効時 |
| BR-35-03 | スペース動作 | quick-terminal-space-behaviorで空間移動時の動作を設定 | remain/move |
| BR-35-04 | 表示位置 | quick-terminal-position設定で表示位置を指定 | top/bottom/left/right/center |
| BR-35-05 | アニメーション | quick-terminal-animation-durationでアニメーション時間を設定 | 常時 |
| BR-35-06 | タブ非サポート | クイックターミナルはタブをサポートしない | 常時 |
| BR-35-07 | ネイティブFS非サポート | ネイティブフルスクリーンは非サポート、非ネイティブのみ | フルスクリーン時 |
| BR-35-08 | 環境変数 | GHOSTTY_QUICK_TERMINAL=1が設定される | クイックターミナル起動時 |

### 計算ロジック

表示位置計算（QuickTerminalPosition.setFinal）:
```
screen = 設定で指定されたスクリーン
size = quick-terminal-size設定値
position = quick-terminal-position設定値
frame = 位置に応じたフレーム計算
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | スクリーン取得失敗 | 設定スクリーンが存在しない | 処理を中断 |
| - | ウィンドウ取得失敗 | windowがnil | 処理を中断 |

### リトライ仕様

フォーカス取得に失敗した場合、最大10回のリトライを25ms間隔で実行。

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

トランザクションは使用しない。

## パフォーマンス要件

- アニメーション時間: quick-terminal-animation-duration設定値（デフォルト0.2秒）
- フォーカス取得: 最大250ms以内

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

- macOSではグローバルホットキー使用にアクセシビリティ権限が必要

## 備考

- Quake/Yakuake/Guakeスタイルのドロップダウンターミナル
- macOSとGTKの両方でサポート
- 通常のウィンドウとは異なる専用のコントローラーを使用

---

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

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

### 推奨読解順序

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

クイックターミナルに関連するアクションと設定の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.zig | `src/apprt/action.zig` | toggle_quick_terminalアクション定義（114-115行目） |
| 1-2 | Binding.zig | `src/input/Binding.zig` | toggle_quick_terminalバインディング（764-800行目） |

**読解のコツ**: ドキュメントコメントにクイックターミナルの制限事項が詳しく記載されている。

#### Step 2: macOS実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | QuickTerminalController.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalController.swift` | メインコントローラー |
| 2-2 | QuickTerminalPosition.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalPosition.swift` | 表示位置計算 |
| 2-3 | QuickTerminalSize.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalSize.swift` | サイズ計算 |

**主要処理フロー**:
1. **320-326行目**: toggle() - 表示/非表示切り替え
2. **328-385行目**: animateIn() - スライドインアニメーション
3. **387-401行目**: animateOut() - スライドアウトアニメーション
4. **419-509行目**: animateWindowIn() - ウィンドウアニメーション詳細
5. **542-598行目**: animateWindowOut() - ウィンドウアニメーション詳細

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | window.zig | `src/apprt/gtk/class/window.zig` | quick-terminalプロパティ（135-151行目） |

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

```
[グローバルホットキー: toggle_quick_terminal]
    │
    ├─ [macOS]
    │      └─ AppDelegate.toggleQuickTerminal
    │              └─ QuickTerminalController.toggle
    │                      ├─ animateIn
    │                      │      ├─ 前アプリ記録
    │                      │      ├─ ターミナル初期化
    │                      │      ├─ ドック非表示
    │                      │      └─ animateWindowIn
    │                      │              └─ window.setFrame (アニメーション)
    │                      └─ animateOut
    │                             ├─ フレーム保存
    │                             ├─ 前アプリ復元
    │                             └─ animateWindowOut
    │                                     └─ window.orderOut
    │
    └─ [GTK]
           └─ toggle_quick_terminal アクション
                  └─ Window (quick-terminalプロパティ)
```

### データフロー図

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

グローバル ──────▶ toggle_quick_terminal ─────────────▶ ウィンドウ表示/非表示
ホットキー          │
                    │
設定値 ────────────▶ toggle()
(quick-terminal-*)      │
                        │
                   animateIn/Out
                        │
                        ├─ ドック制御
                        ├─ アニメーション
                        └─ フォーカス管理 ───────────────▶ 通知送信
                                                          (quickTerminalDidChangeVisibility)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action.zig | `src/apprt/action.zig` | ソース | toggle_quick_terminalアクション定義 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインドアクション定義（詳細ドキュメント含む） |
| QuickTerminalController.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalController.swift` | ソース | macOSクイックターミナルコントローラー |
| QuickTerminalPosition.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalPosition.swift` | ソース | 表示位置計算 |
| QuickTerminalSize.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalSize.swift` | ソース | サイズ計算 |
| QuickTerminalScreen.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalScreen.swift` | ソース | スクリーン選択 |
| QuickTerminalSpaceBehavior.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalSpaceBehavior.swift` | ソース | スペース動作 |
| QuickTerminalWindow.swift | `macos/Sources/Features/QuickTerminal/QuickTerminalWindow.swift` | ソース | ウィンドウクラス |
| window.zig | `src/apprt/gtk/class/window.zig` | ソース | GTKウィンドウ（quick-terminalプロパティ） |
