# 機能設計書 108-カラースキーム管理

## 概要

本ドキュメントは、Windows Terminalのカラースキーム管理機能について記述する。カラースキームは、ターミナル表示に使用する16色のANSIカラーテーブル、前景色、背景色、選択背景色、カーソル色を定義する名前付き設定の集合であり、プロファイルごとに適用可能である。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルの配色は生産性と視認性に直結する重要な設定である。カラースキーム機能は、定義済みの色セットを名前で管理し、プロファイルごとに簡単に切り替えられるようにすることで、ユーザーの好みや用途に応じた視覚的カスタマイズを実現する。

**機能の利用シーン**：ユーザーがsettings.jsonでカラースキームを定義し、各プロファイルのcolorSchemeプロパティで適用するスキームを指定する。設定UIのColorSchemes画面から視覚的に編集することも可能。組み込みスキーム（Campbell等）がデフォルトとして提供される。

**主要な処理内容**：
1. カラースキーム定義のJSON読み込み（ColorScheme::FromJson / _layerJson）
2. カラースキームのJSON書き出し（ColorScheme::ToJson）
3. 16色カラーテーブルの管理（Table / SetColorTableEntry）
4. スキームの複製（ColorScheme::Copy）
5. スキームの等価性判定（IsEquivalentForSettingsMergePurposes）

**関連システム・外部連携**：settings.json、WinRT/XAML設定UI。

**権限による制御**：特段の権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | ColorSchemes（配色一覧） | 主機能 | 配色スキームの一覧表示・新規作成・削除 |
| 28 | EditColorScheme（配色編集） | 主機能 | 個別配色スキームの色編集・プレビュー・保存 |
| 35 | Profiles_Appearance（外観設定） | 補助機能 | プロファイルの配色スキーム選択 |

## 機能種別

設定管理 / データモデル

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | スキームの識別名 | 空でないこと |
| foreground | Color | No | 前景色 | 有効な色値 |
| background | Color | No | 背景色 | 有効な色値 |
| selectionBackground | Color | No | 選択背景色 | 有効な色値 |
| cursorColor | Color | No | カーソル色 | 有効な色値 |
| black/red/green/yellow/blue/purple/cyan/white | Color | Yes | 標準8色 | 16色全て必須 |
| brightBlack/.../brightWhite | Color | Yes | 明るい8色 | 16色全て必須 |

### 入力データソース

- settings.json（schemes配列）
- 組み込みデフォルト（CampbellColorTable）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ColorScheme | ColorScheme | カラースキームオブジェクト |
| Table() | com_array<Color> | 16色のカラーテーブル |

### 出力先

- ターミナル描画エンジンへの色情報提供
- settings.jsonへのシリアライズ
- 設定UIへの表示

## 処理フロー

### 処理シーケンス

```
1. カラースキーム読み込み (ColorScheme::FromJson)
   |-- uninitialized_tでテーブル未初期化のインスタンス生成
   +-- _layerJson呼び出し
       |-- nameキーの読み込み（必須）
       |-- foreground/background/selectionBackground/cursorColorの読み込み
       +-- 16色テーブルの読み込み（TableColorsMapping使用）
           |-- black(0), red(1), ..., white(7)
           |-- brightBlack(8), ..., brightWhite(15)
           |-- magenta(5), brightMagenta(13) : purple/brightPurpleの別名
           +-- 16色全てが存在すること（isValid判定）

2. カラースキーム書き出し (ColorScheme::ToJson)
   |-- name, foreground, background, selectionBackground, cursorColor
   +-- 16色テーブル (TableColorsMapping先頭16エントリ)

3. 等価性判定 (IsEquivalentForSettingsMergePurposes)
   +-- _table, _Background, _Foregroundの一致を比較
       (CursorColor, SelectionBackgroundは無視)
```

### フローチャート

```mermaid
flowchart TD
    A[settings.json schemes配列] --> B[ColorScheme::FromJson]
    B --> C[uninitialized_tインスタンス]
    C --> D[_layerJson]
    D --> E{nameキー存在?}
    E -->|No| F[nullptr返却]
    E -->|Yes| G[foreground/background等パース]
    G --> H[16色テーブルパース]
    H --> I{16色全て存在?}
    I -->|No| F
    I -->|Yes| J[有効なColorScheme返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-108-1 | 16色必須 | カラーテーブルは16色全てが定義されていること | FromJson時 |
| BR-108-2 | name必須 | nameフィールドが存在しない場合は無効 | FromJson時 |
| BR-108-3 | 色名の別名 | "magenta"は"purple"(index 5)、"brightMagenta"は"brightPurple"(index 13)の別名 | JSONパース時 |
| BR-108-4 | デフォルト色 | 前景/背景/選択背景/カーソル色にはデフォルト値がある | 常時 |
| BR-108-5 | 等価性マージ | table, Background, Foregroundが一致すればマージ対象（CursorColor/SelectionBackgroundは無視） | IsEquivalentForSettingsMergePurposes |
| BR-108-6 | 起源タグ | OriginTag::NoneまたはOriginTag::Userで組み込み/ユーザー定義を区別 | 常時 |

### 計算ロジック

特殊な計算ロジックはない。

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

本機能はデータベースを使用しない。settings.jsonファイルで永続化される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| nullptr | パース失敗 | nameが存在しない、または16色が揃わない | FromJsonがnullptrを返却 |
| E_INVALIDARG | インデックス不正 | SetColorTableEntryでindex >= TABLE_SIZE | THROW_HR_IF |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

- カラースキームのパースは設定読み込み時に一括実行されるため、個別のパフォーマンス要件はない
- Table()はcom_arrayのコピーを返すため、頻繁な呼び出しは避けること

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

- 特段のセキュリティ考慮事項はない

## 備考

- デフォルトのカラーテーブルはCampbell配色（Utils::CampbellColorTable）
- TableColorsMappingは18エントリ（16色 + magenta/brightMagentaの別名2つ）
- ColorSchemeExpectedSizeは16で固定
- COLOR_TABLE_SIZEは配列のサイズとして使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ColorScheme.h | `src/cascadia/TerminalSettingsModel/ColorScheme.h` | ColorSchemeクラスの宣言(26-65行目)。_table配列(64行目)、各色プロパティ(54-59行目) |

**読解のコツ**: 30-32行目のuninitialized_t構造体はパフォーマンス最適化のためにテーブルを未初期化で生成するための型。36行目の`explicit ColorScheme(uninitialized_t)`コンストラクタはFromJsonで使用される。52行目のIsEquivalentForSettingsMergePurposesはスキーム統合時の等価判定に使われる。

#### Step 2: JSON変換と色テーブル管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ColorScheme.cpp | `src/cascadia/TerminalSettingsModel/ColorScheme.cpp` | TableColorsMapping(25-47行目)、FromJson(81-85行目)、_layerJson(97-122行目)、ToJson(130-147行目) |

**主要処理フロー**:
1. **25-47行目**: TableColorsMappingで色名とインデックスの対応を定義（18エントリ、magenta/brightMagentaは別名）
2. **49-60行目**: デフォルトコンストラクタでCampbellColorTableをコピー
3. **81-85行目**: FromJsonでuninitialized_tインスタンスを生成し_layerJsonを呼び出し
4. **97-122行目**: _layerJsonでname（必須）、色プロパティ、16色テーブルをパース。colorCountが16でない場合はisValid=false
5. **130-147行目**: ToJsonで全プロパティをシリアライズ
6. **149-152行目**: Table()でcom_arrayとしてテーブルを返却

#### Step 3: 等価性判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ColorScheme.cpp | `src/cascadia/TerminalSettingsModel/ColorScheme.cpp` | IsEquivalentForSettingsMergePurposes(167-173行目)、SetColorTableEntry(161-165行目) |

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

```
CascadiaSettings (設定読み込み)
    |
    +-- ColorScheme::FromJson             ... JSONからスキーム生成
    |       +-- ColorScheme(uninitialized_t)  ... テーブル未初期化
    |       +-- _layerJson                    ... JSONキーのパース
    |           +-- JsonUtils::GetValueForKey(NameKey)         ... name
    |           +-- JsonUtils::GetValueForKey(ForegroundKey)   ... foreground
    |           +-- JsonUtils::GetValueForKey(BackgroundKey)   ... background
    |           +-- JsonUtils::GetValueForKey(SelectionBgKey)  ... selectionBackground
    |           +-- JsonUtils::GetValueForKey(CursorColorKey)  ... cursorColor
    |           +-- for TableColorsMapping: GetValueForKey     ... 16色テーブル
    |
    +-- ColorScheme::ToJson               ... スキームをJSONに書き出し
    |       +-- JsonUtils::SetValueForKey (全プロパティ)
    |
    +-- ColorScheme::Table()              ... 16色テーブル取得
    +-- ColorScheme::SetColorTableEntry() ... 個別色設定
    +-- ColorScheme::Copy()               ... 深いコピー
    +-- ColorScheme::IsEquivalentForSettingsMergePurposes() ... マージ等価判定
```

### データフロー図

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

settings.json                  ColorScheme                    Terminal描画
  schemes[] ---------> FromJson/_layerJson -----------> カラーテーブル(16色)
                                                        前景色/背景色
  デフォルト                                            選択背景色/カーソル色
  (Campbell) --------> コンストラクタ --------+              |
                                              |              v
  設定UI ------------> SetColorTableEntry ---> 色変更   テキスト描画に使用
                                              |
  保存 <-------------- ToJson <-------------- ColorSchemeオブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ColorScheme.h | `src/cascadia/TerminalSettingsModel/ColorScheme.h` | ソース(ヘッダ) | ColorSchemeクラス宣言 |
| ColorScheme.cpp | `src/cascadia/TerminalSettingsModel/ColorScheme.cpp` | ソース(実装) | JSON変換・色テーブル管理 |
| conattrs.hpp | `src/inc/conattrs.hpp` | ソース(ヘッダ) | COLOR_TABLE_SIZE定義 |
| DefaultSettings.h | `src/cascadia/TerminalSettingsModel/DefaultSettings.h` | ソース(ヘッダ) | DEFAULT_FOREGROUND等のデフォルト色定義 |
| colorTable.hpp | `src/types/inc/colorTable.hpp` | ソース(ヘッダ) | CampbellColorTable定義 |
| JsonUtils.h | `src/cascadia/TerminalSettingsModel/JsonUtils.h` | ソース(ヘッダ) | JSON変換ユーティリティ |
| ColorScheme.g.h | 自動生成 | 自動生成 | ColorSchemeのWinRTプロジェクション |
