# 機能設計書 42-テーマ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「テーマ」機能の設計を記述する。この機能は、カラースキーム（前景色、背景色、パレット色など）をテーマファイルとして管理し、ユーザーが簡単に端末の外観をカスタマイズできるようにする。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルエミュレータの外観は、ユーザーの作業効率と快適性に大きく影響する。特にプログラマーは長時間ターミナルを使用するため、目に優しい配色や好みのデザインを選択できることが重要である。テーマ機能は、複雑なカラー設定を個別に行う代わりに、事前に定義されたカラースキームを簡単に適用できるようにすることで、ユーザー体験を向上させる。

**機能の利用シーン**：
- 新しいターミナル環境をセットアップする際にテーマを選択する
- ライトモード/ダークモードの切り替えに応じてテーマを変更する
- 作業環境や気分に合わせてカラースキームを変更する
- カスタムテーマを作成して適用する

**主要な処理内容**：
1. テーマ名の解決と検索（ユーザーディレクトリ優先）
2. テーマファイルの読み込みとパース
3. カラー設定（前景色、背景色、16色パレット、拡張色）の適用
4. 条件付きテーマの処理（ライト/ダークモード対応）
5. テーマ関連のエラー診断

**関連システム・外部連携**：
- ファイルシステム（テーマファイルの読み込み）
- XDG Base Directory仕様（ユーザーテーマディレクトリ）
- Ghosttyリソースディレクトリ（組み込みテーマ）

**権限による制御**：特になし。すべてのユーザーがテーマを使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | コマンドパレット | 遷移先機能 | テーマ選択コマンドの実行 |

## 機能種別

設定管理 / スタイル適用

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| theme | []const u8 | No | テーマ名またはテーマファイルへの絶対パス | パス区切り文字を含む場合は絶対パスのみ許可 |

### 入力データソース

- 設定ファイル: `theme = <テーマ名>` または `theme = <絶対パス>`
- テーマファイル検索パス:
  1. `$XDG_CONFIG_HOME/ghostty/themes/` (ユーザーテーマ)
  2. `<リソースディレクトリ>/themes/` (組み込みテーマ)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| foreground | Color | 前景色 |
| background | Color | 背景色 |
| palette | [256]Color | 256色パレット |
| cursor-color | ?Color | カーソル色（オプション） |
| cursor-text | ?Color | カーソル上のテキスト色（オプション） |
| selection-foreground | ?Color | 選択範囲の前景色（オプション） |
| selection-background | ?Color | 選択範囲の背景色（オプション） |

### 出力先

- 設定オブジェクト（Config構造体）へのカラー値の適用
- レンダラーへのカラー情報の伝播

## 処理フロー

### 処理シーケンス

```
1. テーマ名の取得
   └─ 設定ファイルからthemeの値を読み込み

2. テーマファイルの検索
   └─ 絶対パスの場合: 直接オープン
   └─ 相対名の場合: LocationIteratorで優先順位順に検索

3. テーマファイルのオープンと検証
   └─ 通常ファイルであることを確認
   └─ エラー時は診断リストに追加

4. テーマファイルのパース
   └─ 設定ファイルと同じ形式でパース
   └─ カラー関連の設定値を抽出

5. 設定への適用
   └─ Config構造体のカラーフィールドに値を設定
```

### フローチャート

```mermaid
flowchart TD
    A[theme設定値取得] --> B{絶対パス?}
    B -->|Yes| C[openAbsolute]
    B -->|No| D{パス区切り含む?}
    D -->|Yes| E[エラー: 無効なテーマ名]
    D -->|No| F[LocationIteratorで検索]
    F --> G{ユーザーディレクトリ}
    G -->|見つかった| H[ファイルオープン]
    G -->|見つからない| I{リソースディレクトリ}
    I -->|見つかった| H
    I -->|見つからない| J[エラー: テーマ未発見]
    C --> K{ファイル種別確認}
    H --> K
    K -->|通常ファイル| L[テーマファイルパース]
    K -->|その他| M[エラー: 非ファイル]
    L --> N[カラー設定適用]
    N --> O[完了]
    E --> O
    J --> O
    M --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-42-01 | ユーザーテーマ優先 | ユーザーディレクトリのテーマがリソースディレクトリより優先される | 同名テーマが両方に存在する場合 |
| BR-42-02 | 絶対パス制約 | テーマ名にパス区切り文字を含む場合は絶対パスのみ許可 | パス区切り文字を含む場合 |
| BR-42-03 | ファイル種別制約 | テーマファイルは通常ファイルでなければならない | ディレクトリ、シンボリックリンク等は拒否 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFound | テーマファイルが見つからない | 検索したパスを診断リストに追加 |
| - | InvalidPath | テーマ名にパス区切り文字を含むが絶対パスでない | エラーメッセージを診断リストに追加 |
| - | InvalidFileType | テーマパスが通常ファイルでない | ファイル種別を診断リストに追加 |
| OutOfMemory | メモリ不足 | パスの結合やパース時にメモリ不足 | エラーを返す |

### リトライ仕様

リトライなし。テーマファイルの問題はユーザーが修正する必要がある。

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

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

## パフォーマンス要件

- テーマファイルの検索と読み込みは起動時のみ行われる
- テーマファイルは通常小さい（数KB以下）ため、パフォーマンス上の懸念なし

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

- テーマファイルはユーザーの設定ディレクトリまたはリソースディレクトリからのみ読み込む
- シンボリックリンクは許可されない（ファイル種別チェック）

## 備考

- Ghosttyは多数の組み込みテーマを同梱している
- カスタムテーマはユーザーディレクトリに配置することで使用可能
- テーマファイルは設定ファイルと同じ形式を使用

---

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

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

### 推奨読解順序

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

テーマの検索場所と優先順位を定義する構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | theme.zig | `src/config/theme.zig` | Location enumの定義（10-12行目） |
| 1-2 | theme.zig | `src/config/theme.zig` | LocationIterator構造体（67-94行目） |

**読解のコツ**: Zigの`enum`と`struct`の組み合わせを理解する。Locationは検索場所の種類を、LocationIteratorはその反復処理を担当する。

#### Step 2: テーマファイルの検索処理

テーマ名からファイルパスを解決する処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | theme.zig | `src/config/theme.zig` | open関数の全体構造（96-240行目） |
| 2-2 | theme.zig | `src/config/theme.zig` | 絶対パスの処理（119-151行目） |
| 2-3 | theme.zig | `src/config/theme.zig` | 相対名の検索処理（166-220行目） |

**主要処理フロー**:
1. **119行目**: 絶対パスかどうかの判定
2. **153-164行目**: パス区切り文字のチェック
3. **168行目**: LocationIteratorの初期化
4. **170-220行目**: 検索ループと診断エラー収集

#### Step 3: ディレクトリ解決

各Location種別に対応するディレクトリパスを取得する処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | theme.zig | `src/config/theme.zig` | Location.dir関数（23-62行目） |

**主要処理フロー**:
- **28-54行目**: ユーザーディレクトリ（XDG config）の解決
- **57-60行目**: リソースディレクトリの解決

#### Step 4: 絶対パスからの読み込み

絶対パス指定時のファイルオープン処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | theme.zig | `src/config/theme.zig` | openAbsolute関数（250-277行目） |

**主要処理フロー**:
- **255行目**: ファイルオープン
- **256-273行目**: エラーハンドリングと診断追加

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

```
Config.load (設定読み込み)
    │
    └─ theme設定値の処理
           │
           ├─ themepkg.open
           │      ├─ isAbsolute判定
           │      │      └─ openAbsolute
           │      │
           │      └─ LocationIterator.next
           │             └─ Location.dir
           │                    ├─ .user → XDG config
           │                    └─ .resources → リソースディレクトリ
           │
           └─ テーマファイルのパース
                  └─ Config.loadFile
```

### データフロー図

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

theme設定値 ────────▶ テーマ名解決 ────────▶ ファイルパス
     │                     │
     │                     ▼
     │              LocationIterator
     │               ├─ user ($XDG_CONFIG_HOME/ghostty/themes/)
     │               └─ resources (リソースディレクトリ/themes/)
     │                     │
     ▼                     ▼
テーマファイル ────▶ パース処理 ────────▶ カラー設定値
                                              │
                                              ▼
                                         Config構造体
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| theme.zig | `src/config/theme.zig` | ソース | テーマ検索・読み込みのコア実装 |
| Config.zig | `src/config/Config.zig` | ソース | テーマ設定の統合と適用 |
| color.zig | `src/terminal/color.zig` | ソース | カラー型の定義 |
| global.zig | `src/global.zig` | ソース | リソースディレクトリのグローバル状態 |
| xdg.zig | `src/os/xdg.zig` | ソース | XDGディレクトリ解決 |
