# 機能設計書 22-グローバルホットキー

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「グローバルホットキー」機能の設計を記述する。グローバルホットキーは、Ghosttyがフォーカスされていない状態でも、システム全体で機能するキーバインドを提供する機能である。

### 本機能の処理概要

**業務上の目的・背景**：
ターミナルユーザーは、他のアプリケーションで作業中にもターミナル操作を迅速に呼び出したいというニーズがある。グローバルホットキー機能により、Ghosttyがバックグラウンドにある状態でも、システム全体で定義されたキーバインドを使用してGhosttyの機能を呼び出すことができる。これは特にクイックターミナル（ドロップダウンターミナル）やウィンドウ表示切り替えなどの機能と組み合わせて使用されることが多い。

**機能の利用シーン**：
- クイックターミナルのトグル表示（例：`global:cmd+backquote=toggle_quick_terminal`）
- Ghosttyウィンドウの表示/非表示切り替え
- 新規ウィンドウ/タブの作成
- 他のアプリケーション使用中からのGhostty呼び出し

**主要な処理内容**：
1. 設定ファイルでのグローバルキーバインドの定義（`global:` プレフィックス）
2. OS固有のグローバルショートカットAPI登録
3. システム全体でのキーイベント監視
4. キーマッチ時のアクション実行
5. アプリケーションフォーカスの自動切り替え

**関連システム・外部連携**：
- macOS: CGEvent（Core Graphics Event Services）を使用したグローバルキーリスナー
- Linux/GTK: プラットフォーム固有のDBus/グローバルショートカットAPI
- 設定システムとの連携

**権限による制御**：
- macOS: アクセシビリティ権限が必要な場合がある
- Linux: プラットフォーム/デスクトップ環境に依存

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 結果表示画面 | グローバルホットキーによるフォーカス/表示 |
| 2 | クイックターミナル | 結果表示画面 | グローバルホットキーによるトグル表示 |

## 機能種別

システムイベント処理 / OS連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| keybind | []const u8 | Yes | `global:` プレフィックス付きキーバインド定義 | 有効なキー組み合わせであること |
| action | Action | Yes | 実行するアクション | app スコープのアクションであること |

### 入力データソース

- 設定ファイル（`keybind = global:...`形式）
- システムからのキーボードイベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| registered | bool | グローバルキーバインド登録成功フラグ |

### 出力先

- アプリケーションアクション実行
- ウィンドウフォーカス変更

## 処理フロー

### 処理シーケンス

```
1. アプリケーション起動時
   └─ 設定からglobal:プレフィックス付きバインドを抽出

2. OSグローバルショートカット登録
   └─ プラットフォーム固有APIでショートカット登録

3. キーイベント発生（システム全体）
   └─ 登録されたショートカットとマッチング

4. マッチした場合
   └─ 対応するアクションを実行
   └─ 必要に応じてGhosttyをフォーカス
```

### フローチャート

```mermaid
flowchart TD
    A[アプリケーション起動] --> B[設定読み込み]
    B --> C{global:プレフィックス検出}
    C -->|Yes| D[グローバルバインド抽出]
    C -->|No| E[通常バインドとして処理]
    D --> F[OSグローバルショートカットAPI登録]

    G[システムキーイベント] --> H{登録済みショートカット?}
    H -->|Yes| I[アクション実行]
    H -->|No| J[イベント通過]
    I --> K{フォーカス必要?}
    K -->|Yes| L[Ghosttyをフォアグラウンドに]
    K -->|No| M[処理完了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-1 | globalプレフィックス必須 | グローバルバインドには`global:`プレフィックスが必要 | keybind設定時 |
| BR-22-2 | シーケンス不可 | グローバルバインドはキーシーケンスと組み合わせ不可 | バインド解析時 |
| BR-22-3 | allフラグ不可 | グローバルバインドは`all:`フラグと組み合わせ不可 | バインド解析時 |
| BR-22-4 | プラットフォーム制限 | 一部プラットフォームではグローバルバインド非対応 | 実行時 |

### 計算ロジック

該当なし

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidFormat | global:とシーケンス/allの組み合わせ | エラーを返し登録をスキップ |
| - | 権限エラー | OS権限不足（macOSアクセシビリティ等） | ログ出力、機能を無効化 |
| - | 登録失敗 | OS APIエラー | ログ出力、該当バインドをスキップ |

### リトライ仕様

該当なし（起動時に一度だけ登録を試行）

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

該当なし

## パフォーマンス要件

- グローバルキーイベント検出: 即時（ミリ秒オーダー）
- アクション実行: 通常のアクション実行時間と同等

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

- グローバルキーフックはシステム全体のキー入力を監視するため、セキュリティ上の考慮が必要
- macOSではアクセシビリティ権限が必要な場合がある
- パスワード入力時など、セキュア入力モードではグローバルキーが無効化される場合がある

## 備考

- グローバルホットキーの使用例として、クイックターミナル（`toggle_quick_terminal`）との組み合わせが推奨される
- Linux/Waylandでは、wlr-layer-shell-v1プロトコル対応が必要な場合がある

---

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

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

### 推奨読解順序

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

グローバルフラグの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | Flags structのglobalフィールド定義（40-43行目） |
| 1-2 | Binding.zig | `src/input/Binding.zig` | parseFlags関数での`global:`プレフィックス解析（162-164行目） |

**読解のコツ**: `packed struct`の定義に注目。各フラグは1ビットで表現される。

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

グローバルバインドの登録処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Binding.zig | `src/input/Binding.zig` | Parser.init関数でのflagsパース（94-96行目） |
| 2-2 | Binding.zig | `src/input/Binding.zig` | Parser.next関数でのglobal/allとシーケンスの排他チェック（196行目） |

**主要処理フロー**:
1. **94-96行目**: parseFlags関数を呼び出してプレフィックスを解析
2. **162-164行目**: `global`プレフィックスの検出とフラグ設定
3. **196行目**: globalフラグとシーケンスの組み合わせエラーチェック

#### Step 3: プラットフォーム実装を理解する

GTK/macOSでの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | global_shortcuts.zig | `src/apprt/gtk/class/global_shortcuts.zig` | GTKでのグローバルショートカット実装 |
| 3-2 | embedded.zig | `src/apprt/embedded.zig` | 組み込みランタイムでのグローバルキー処理 |

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

```
設定読み込み
    │
    ├─ Config.keybind.parse()
    │      │
    │      └─ Binding.Parser.init()
    │             │
    │             └─ parseFlags() ─── global:検出
    │
    └─ App.init()
           │
           ├─ [macOS] CGEvent登録
           │
           └─ [GTK] global_shortcuts.zig
                  │
                  └─ DBus/ポータルAPI登録
```

### データフロー図

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

設定ファイル ────▶ keybind = global:cmd+` ────▶ Binding with global=true
                          │
                          ▼
                   OS API登録
                          │
システムキーイベント ────▶ ショートカット照合 ────▶ アクション実行
                                                        │
                                                        ▼
                                               toggle_quick_terminal等
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | Flagsのglobal定義、パース処理 |
| global_shortcuts.zig | `src/apprt/gtk/class/global_shortcuts.zig` | ソース | GTKグローバルショートカット実装 |
| embedded.zig | `src/apprt/embedded.zig` | ソース | 組み込みランタイム（macOS）のグローバルキー処理 |
| Config.zig | `src/config/Config.zig` | ソース | 設定解析 |
