# 機能設計書 7-カラー対応

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける256色、True Color（24bit）、X11色名に対応した端末カラー表示の「カラー対応」機能の設計を記述する。

### 本機能の処理概要

カラー対応機能は、端末のカラー表示を管理する。256色パレット、True Color（RGB 24bit）、X11色名（140以上の名前付き色）をサポートする。動的パレット（DynamicPalette）により、設定やOSCコマンドによるカラーの動的変更も可能。

**業務上の目的・背景**：現代のターミナルアプリケーションは豊富な色表現を使用する。シンタックスハイライト、ステータス表示、エラー/警告の色分けなど、色は情報伝達の重要な手段である。True Color対応により、GUIアプリケーションと同等の色表現が可能になる。

**機能の利用シーン**：
- vim/neovimでシンタックスハイライトを表示する場面
- lsコマンドでファイルタイプ別に色分けする場面
- gitコマンドでdiff/status表示を色分けする場面
- シェルプロンプトをカスタムカラーで表示する場面

**主要な処理内容**：
1. 256色パレットの管理とデフォルト値設定
2. True Color（RGB）値の処理
3. X11色名の解析と変換
4. 動的パレットによるランタイムカラー変更
5. テーマに基づく調和的パレット生成（generate256Color）

**関連システム・外部連携**：
- SGR（Select Graphic Rendition）との連携
- OSC 4/10/11による動的カラー変更
- テーマ設定との連携

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 256色、True Color、X11色名の端末カラー表示 |

## 機能種別

データ処理 / 表示制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| color_index | u8 | - | 256色パレットインデックス | 0-255 |
| rgb | RGB | - | True Color値 | r,g,b各0-255 |
| color_name | []const u8 | - | X11色名 | 有効な色名 |

### 入力データソース

- SGRエスケープシーケンス
- OSC 4/10/11シーケンス
- 設定ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| rgb | RGB | RGB値（r, g, b各u8） |
| palette | Palette | 256色パレット配列 |

### 出力先

- セルのスタイル情報
- レンダラー

## 処理フロー

### 処理シーケンス

```
1. デフォルトパレット生成
   └─ 16色：名前付き色のデフォルト値
   └─ 216色（16-231）：6x6x6カラーキューブ
   └─ 24色（232-255）：グレースケールランプ

2. SGRカラー処理
   └─ 8色（30-37, 40-47）：基本色
   └─ 256色（38;5;n, 48;5;n）：パレット参照
   └─ True Color（38;2;r;g;b）：直接RGB

3. OSC動的カラー
   └─ OSC 4：パレット変更
   └─ OSC 10：前景色変更
   └─ OSC 11：背景色変更

4. テーマ適用
   └─ ライト/ダークモード検出
   └─ 調和的パレット生成（CIELAB補間）
```

### フローチャート

```mermaid
flowchart TD
    A[カラー指定受信] --> B{カラータイプ}
    B -->|8色| C[Name enum参照]
    B -->|256色| D[パレット参照]
    B -->|True Color| E[RGB直接使用]
    B -->|X11色名| F[x11_color.zig参照]

    C --> G[RGB取得]
    D --> G
    E --> G
    F --> G

    G --> H[セル/スタイルに適用]
    H --> I[レンダラーで表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトパレット | ECMA-48準拠のデフォルト16色 | 初期化時 |
| BR-002 | カラーキューブ | 6x6x6=216色のRGBキューブ（16-231） | パレット生成時 |
| BR-003 | グレースケール | 24段階のグレー（232-255） | パレット生成時 |
| BR-004 | CIELAB補間 | テーマ適用時はCIELAB空間で補間 | generate256Color時 |

### 計算ロジック

- カラーキューブ: `r*36 + g*6 + b + 16` （r,g,b: 0-5）
- グレースケール: `(index - 232) * 10 + 8`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-001 | 無効な色名 | X11色名が見つからない | デフォルト色を使用 |

### リトライ仕様

リトライ機構は使用しない。

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

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

## パフォーマンス要件

- パレット参照: O(1)
- X11色名検索: O(log n)

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

特になし。

## 備考

- DynamicPaletteで動的変更とリセットをサポート
- generate256Color()でテーマに調和したパレット生成

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | color.zig | `src/terminal/color.zig` | RGB、Palette、Name、DynamicPalette構造体 |
| 1-2 | color.zig | `src/terminal/color.zig` | default（デフォルトパレット生成） |

**読解のコツ**: `default`はcomptime定数で、16色+216色キューブ+24グレースケールを生成。`DynamicPalette`はcurrent/original/maskで変更を追跡。

#### Step 2: パレット生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | color.zig | `src/terminal/color.zig` | generate256Color()関数 |
| 2-2 | color.zig | `src/terminal/color.zig` | LAB構造体（CIELAB色空間） |

**主要処理フロー**:
- **8-45行目**: defaultパレット生成（comptime）
- **88-174行目**: generate256Color() - テーマ調和パレット生成
- **96-119行目**: base8_lab - 8基本色をCIELABに変換

#### Step 3: X11色名を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | x11_color.zig | `src/terminal/x11_color.zig` | 色名からRGBへの変換テーブル |

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

```
color.zig
    |
    +-- default [comptime]
    |      +-- Name.default() (0-15)
    |      +-- カラーキューブ計算 (16-231)
    |      +-- グレースケール計算 (232-255)
    |
    +-- DynamicPalette
    |      +-- init(default_palette)
    |      +-- set(index, color)
    |      +-- reset(index)
    |      +-- resetAll()
    |
    +-- generate256Color()
           +-- LAB.fromRgb()
           +-- LAB.lerp()
           +-- LAB.toRgb()
```

### データフロー図

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

設定/テーマ ────────> generate256Color()
                           |
                           v
                    CIELAB補間 ─────────> Palette[256]

SGR 38;5;n ─────────> DynamicPalette.current[n]
                           |
                           v
                    RGB取得 ───────────> セルスタイル

OSC 4;n;rgb ────────> DynamicPalette.set()
                           |
                           v
                    パレット更新 ───────> mask設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| color.zig | `src/terminal/color.zig` | ソース | カラー管理のメインロジック |
| x11_color.zig | `src/terminal/x11_color.zig` | ソース | X11色名テーブル |
| sgr.zig | `src/terminal/sgr.zig` | ソース | SGRカラー処理 |
