# 機能設計書 69-Kittyカラー

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける Kitty カラープロトコル実装の設計を記述する。

### 本機能の処理概要

Kitty カラープロトコルは、ターミナルの色設定をプログラムから照会・変更するための拡張 OSC シーケンスである。標準の OSC 10/11/12 では対応できない詳細な色指定（選択範囲の前景色・背景色、カーソルテキスト色など）や、パレット全体の一括操作が可能。

**業務上の目的・背景**：ターミナルアプリケーションは、テーマ切り替えや動的なカラー設定変更を行うことがある。Kitty カラープロトコルは、Kitty ターミナルが開発した拡張 OSC 21 で、より柔軟な色制御を提供する。

**機能の利用シーン**：
- テーマの動的切り替え
- アプリケーション起動時の色設定照会
- 特定色（選択範囲、カーソル等）のカスタマイズ
- パレット色のクエリとリセット

**主要な処理内容**：
1. OSC 21 シーケンスの解析
2. 色の照会（query）リクエスト処理
3. 色の設定（set）リクエスト処理
4. 色のリセット（reset）リクエスト処理
5. 応答の PTY への送信

**関連システム・外部連携**：
- OSC パーサー: エスケープシーケンス解析
- ターミナル色設定: 内部色パレット

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主機能 | 色設定の反映 |

## 機能種別

色設定 / プロトコル処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | Kind | Yes | 色種別（パレット番号 0-255、または特殊色名） | 有効な Kind |
| operation | enum | Yes | 操作種別（query, set, reset） | 有効な操作 |
| color | RGB | No | 設定する色（set 時のみ） | RGB 形式 |

### 色種別（Kind）

| 種別 | 説明 |
|------|------|
| palette | パレット色（0-255） |
| foreground | 前景色 |
| background | 背景色 |
| selection_foreground | 選択範囲前景色 |
| selection_background | 選択範囲背景色 |
| cursor | カーソル色 |
| cursor_text | カーソルテキスト色 |
| visual_bell | ビジュアルベル色 |
| second_transparent_background | 第2透明背景色 |

### 入力データソース

- OSC 21 シーケンス: `ESC ] 21 ; <requests> ST`
- リクエスト形式: `key=?`（query）, `key=color`（set）, `key`（reset）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Response | []Request | 照会応答リスト |
| color | RGB | 色値（r, g, b 各 0-255） |

### 出力先

- PTY: 応答エスケープシーケンス `ESC ] 21 ; <response> ST`

## 処理フロー

### 処理シーケンス

```
1. OSC 21 シーケンス受信
   └─ osc.Parser で解析
   └─ kitty_color_protocol パーサー呼び出し

2. リクエスト解析
   └─ セミコロンで分割
   └─ 各リクエストを Request 構造体に変換
   └─ リストに格納

3. リクエスト処理
   └─ query: 現在の色値を取得
   └─ set: 色を RGB 値に設定
   └─ reset: デフォルト色に戻す

4. 応答生成（query の場合）
   └─ 同じ ST（文字列終端）を使用
   └─ OSC 21 形式で応答

5. 色変更通知
   └─ color_change アクション送信
   └─ レンダラー再描画トリガー
```

### フローチャート

```mermaid
flowchart TD
    A[OSC 21 受信] --> B[osc.Parser]
    B --> C[kitty_color_protocol.parse]
    C --> D{リクエスト分割}
    D --> E[各リクエスト解析]
    E --> F{operation?}
    F -->|query| G[Kind.parse]
    F -->|set| H[Kind.parse + color]
    F -->|reset| I[Kind.parse]
    G --> J[Request.query 生成]
    H --> K[Request.set 生成]
    I --> L[Request.reset 生成]
    J --> M[list に追加]
    K --> M
    L --> M
    M --> N{次のリクエスト?}
    N -->|Yes| E
    N -->|No| O[OSC 構造体返却]
    O --> P[Terminal 処理]
    P --> Q{query?}
    Q -->|Yes| R[色値取得]
    Q -->|No| S{set?}
    S -->|Yes| T[色設定]
    S -->|No| U[色リセット]
    R --> V[応答生成]
    T --> W[color_change アクション]
    U --> W
    V --> X[PTY 送信]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-01 | パレット範囲 | パレット番号は 0-255 | palette 種別 |
| BR-69-02 | 特殊色名 | foreground, background 等の文字列で指定可能 | special 種別 |
| BR-69-03 | ST 維持 | 応答は受信と同じ ST（ESC \ または BEL）を使用 | query 応答時 |
| BR-69-04 | 複数リクエスト | セミコロンで区切って複数リクエストを1シーケンスで送信可能 | 常時 |

### 計算ロジック

色値のパースは `std.fmt.parseUnsigned` を使用し、10進数または16進数（# プレフィックス）に対応。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidFormat | 不正なキー名 | リクエストをスキップ |
| - | InvalidColor | 不正な色値 | リクエストをスキップ |

### リトライ仕様

該当なし（不正なリクエストはスキップ）

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

該当なし

## パフォーマンス要件

- OSC パースはストリーミングで行い、メモリ効率を維持
- ArrayList でリクエストを動的に蓄積

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

該当なし

## 備考

- Kitty カラープロトコルは OSC 21 を使用（Kitty 独自拡張）
- 標準 OSC 10/11/12 とは異なる形式

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | color.zig | `src/terminal/kitty/color.zig` | OSC, Kind, Special 構造体（1-77行目） |

**読解のコツ**: `Kind` は `palette`（u8）か `special`（enum）のいずれか。`Special` は foreground, background などの特殊色を表現。

#### Step 2: OSC 構造体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | color.zig | `src/terminal/kitty/color.zig` | OSC 構造体（6-30行目） |
| 2-2 | color.zig | `src/terminal/kitty/color.zig` | Request union（7-11行目） |

**主要処理フロー**:
- **6-30行目**: OSC 構造体は Request リストと terminator を保持
- **7-11行目**: Request は query, set, reset の3種類の操作を表現

#### Step 3: Kind パースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | color.zig | `src/terminal/kitty/color.zig` | Kind.parse（49-52行目） |
| 3-2 | color.zig | `src/terminal/kitty/color.zig` | Kind.format（54-62行目） |

**主要処理フロー**:
- **49-52行目**: 文字列を Special enum または u8 パレット番号に変換
- **54-62行目**: Kind を文字列形式にフォーマット（応答生成用）

#### Step 4: OSC パーサー統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kitty_color_protocol.zig | `src/terminal/osc/parsers/kitty_color_protocol.zig` | パーサー実装 |
| 4-2 | osc.zig | `src/terminal/osc.zig` | OSC コマンド統合 |

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

```
OSC シーケンス受信
    │
    └─ osc.Parser.next
           │
           └─ 状態遷移で OSC 21 検出
                  │
                  └─ kitty_color_protocol.parse
                         │
                         ├─ セミコロン分割
                         │
                         └─ 各リクエスト解析
                                │
                                ├─ Kind.parse（キー解析）
                                │
                                └─ Request 生成
                                       │
                                       ├─ query（key=?）
                                       │
                                       ├─ set（key=color）
                                       │
                                       └─ reset（key のみ）

Terminal 処理
    │
    └─ OSC.kitty_color_protocol
           │
           ├─ query
           │     └─ 現在の色値取得
           │     └─ 応答 OSC 生成
           │
           ├─ set
           │     └─ 色設定
           │     └─ color_change アクション
           │
           └─ reset
                 └─ デフォルト色に戻す
                 └─ color_change アクション
```

### データフロー図

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

OSC 21 シーケンス ───────▶ osc.Parser
                               │
                               ▼
セミコロン区切り ─────────▶ リクエスト分割
                               │
                               ▼
key=? / key=color / key ──▶ Request 生成 ────▶ list
                               │
                               ▼
                        Terminal 処理
                               │
                               ├── query ────▶ 色値取得 ────▶ OSC 21 応答
                               │
                               ├── set ────▶ 色設定
                               │                 │
                               │                 ▼
                               │           color_change
                               │                 │
                               │                 ▼
                               └── reset ────▶ 色リセット ────▶ レンダラー更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| color.zig | `src/terminal/kitty/color.zig` | ソース | OSC, Kind, Request 構造体 |
| kitty_color_protocol.zig | `src/terminal/osc/parsers/kitty_color_protocol.zig` | ソース | OSC 21 パーサー |
| osc.zig | `src/terminal/osc.zig` | ソース | OSC コマンド統合 |
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | 色設定処理 |
| stream_handler.zig | `src/termio/stream_handler.zig` | ソース | OSC ハンドラ統合 |
| action.zig | `src/apprt/action.zig` | ソース | color_change アクション定義 |
