# 機能設計書 26-Kittyキーボードプロトコル

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「Kittyキーボードプロトコル」機能の設計を記述する。Kittyキーボードプロトコルは、Kitty端末エミュレータが策定した拡張キーボードプロトコルであり、従来の端末キーボードエンコーディングの制限を解消し、より詳細なキー情報をアプリケーションに伝達する。

### 本機能の処理概要

**業務上の目的・背景**：
従来の端末キーボードプロトコルには多くの制限があり、現代のアプリケーションが必要とする詳細なキー情報（例：Ctrl+Shift+文字の区別、修飾キー単体の検出）を伝達できなかった。Kittyキーボードプロトコルは、これらの制限を解消し、以下の機能を提供する：
- すべてのキーの一意な識別
- 修飾キーの詳細な状態報告
- キープレス、リピート、リリースイベントの区別
- 代替キーコードの報告

**機能の利用シーン**：
- neovim、emacsでの詳細なキーバインド
- TUIアプリケーションでのショートカットキー
- ゲームや対話的アプリケーションでのキー入力

**主要な処理内容**：
1. アプリケーションからのプロトコルモード設定（CSI > Ps u）
2. キーイベントの拡張エンコーディング
3. 修飾キーエンコーディング
4. プロトコルフラグの管理

**関連システム・外部連携**：
- キー入力システム
- PTY出力システム
- xtermキーエンコーディングシステム

**権限による制御**：
本機能に特別な権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | Kittyプロトコル対応アプリへのキー送信 |

## 機能種別

プロトコル処理 / キーエンコーディング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | Key | Yes | 押されたキー | 有効なキーコード |
| mods | Mods | Yes | 修飾キー状態 | - |
| event_type | EventType | Yes | press/repeat/release | - |

### 入力データソース

- OSからのキーボードイベント
- アプリケーションからのモード設定シーケンス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| sequence | []const u8 | Kittyプロトコル形式のキーシーケンス |

### 出力先

- PTY（実行中アプリケーションへ）

## 処理フロー

### 処理シーケンス

```
1. プロトコルモード設定
   └─ CSI > Ps u でフラグ設定

2. キーイベント受信
   └─ OSからのキーボードイベント

3. エンコーディング判定
   └─ Kittyプロトコル有効かつ対応キーか

4. キーシーケンス生成
   └─ CSI keycode ; modifiers u 形式

5. PTY送信
```

### フローチャート

```mermaid
flowchart TD
    A[キーイベント受信] --> B{Kittyプロトコル有効?}
    B -->|No| C[従来のエンコーディング]
    B -->|Yes| D[キーコード検索]

    D --> E{対応キー?}
    E -->|No| C
    E -->|Yes| F[修飾キーエンコード]

    F --> G{イベントタイプ}
    G -->|press| H[プレスシーケンス生成]
    G -->|repeat| I[リピートシーケンス生成]
    G -->|release| J[リリースシーケンス生成]

    H --> K[PTY送信]
    I --> K
    J --> K
    C --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-26-1 | フラグ1 | disambiguate_escape_codes | 曖昧なシーケンスを一意化 |
| BR-26-2 | フラグ2 | report_event_types | press/repeat/releaseを報告 |
| BR-26-3 | フラグ4 | report_alternate_keys | 代替キーを報告 |
| BR-26-4 | フラグ8 | report_all_keys_as_escape_codes | すべてのキーをエスケープ形式で報告 |
| BR-26-5 | フラグ16 | report_associated_text | 関連テキストを報告 |

### 計算ロジック

**修飾キーエンコーディング**:
```
modifier = 1 (base)
         + (shift ? 1 : 0)
         + (alt ? 2 : 0)
         + (ctrl ? 4 : 0)
         + (super ? 8 : 0)
         + (hyper ? 16 : 0)
         + (meta ? 32 : 0)
         + (caps_lock ? 64 : 0)
         + (num_lock ? 128 : 0)
```

**キーシーケンス形式**:
```
CSI keycode ; modifier u       (基本)
CSI keycode ; modifier : event u (イベントタイプ付き)
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 未対応キー | entriesテーブルに存在しないキー | 従来のエンコーディングにフォールバック |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- キーエンコーディング: 即時（マイクロ秒オーダー）

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

- 詳細なキー情報がアプリケーションに送信されるため、悪意のあるアプリケーションがキー入力を完全に追跡可能

## 備考

- Kittyキーボードプロトコル仕様: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
- Foot端末からキーマップを移植

---

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

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

### 推奨読解順序

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

Kittyキーマップのデータ構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kitty.zig | `src/input/kitty.zig` | Entry struct定義（6-11行目） |
| 1-2 | kitty.zig | `src/input/kitty.zig` | entries配列定義（14-27行目） |
| 1-3 | kitty.zig | `src/input/kitty.zig` | raw_entries定義（44-128行目） |

**読解のコツ**: Entryのcode/finalフィールドがどのようにシーケンス生成に使用されるかを理解する。

#### Step 2: キーマップデータを理解する

具体的なキーマッピングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kitty.zig | `src/input/kitty.zig` | ファンクションキーマッピング（65-88行目） |
| 2-2 | kitty.zig | `src/input/kitty.zig` | テンキーマッピング（91-119行目） |
| 2-3 | kitty.zig | `src/input/kitty.zig` | 修飾キーマッピング（121-128行目） |

**主要処理フロー**:
1. **45-63行目**: 基本キー（escape、enter、tab等）のマッピング
2. **65-88行目**: ファンクションキー（F1-F25）のマッピング
3. **91-119行目**: テンキーのマッピング
4. **121-128行目**: 修飾キー自体のマッピング

#### Step 3: エンコーディング処理を理解する

キーエンコードの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | key_encode.zig | `src/input/key_encode.zig` | キーエンコードロジック |

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

```
キー入力
    │
    └─ Surface.keyInput()
           │
           └─ key_encode.encode()
                  │
                  ├─ kitty.entries検索
                  │      │
                  │      └─ Entry取得
                  │
                  └─ シーケンス生成
                         │
                         └─ CSI code ; mods u
```

### データフロー図

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

キー入力 ────────▶ kitty.entries検索 ────▶ Entry取得
    │                      │
    │                      ▼
修飾キー状態 ────▶ modifier計算 ────────▶ modifier値
                           │
                           ▼
                   シーケンス生成 ────────▶ CSI keycode ; modifier u
                           │
                           ▼
                       PTY送信
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kitty.zig | `src/input/kitty.zig` | ソース | Kittyキーマップ定義 |
| key_encode.zig | `src/input/key_encode.zig` | ソース | キーエンコードロジック |
| key.zig | `src/input/key.zig` | ソース | キー定義 |
| Surface.zig | `src/Surface.zig` | ソース | キー入力処理 |
