# 機能設計書 57-カラースキームの設定

## 概要

本ドキュメントは、Windows Terminal における「カラースキームの設定」機能の設計を記述する。SetColorScheme アクションにより、ターミナルの配色テーマをランタイムで変更する機能である。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルの配色テーマ（カラースキーム）をプロファイル設定を永続変更せずにランタイムで切り替えられるようにする。作業内容や時間帯に応じた配色変更、プレゼンテーション用の見やすい配色への切り替え、テーマの試行など柔軟な利用シーンに対応する。コマンドパレットでのプレビュー機能にも対応している。

**機能の利用シーン**：ユーザーがターミナルの配色をその場で変更したい場合に利用する。コマンドパレットから SetColorScheme アクションを選択すると、カラースキーム一覧が表示され、プレビュー付きで配色を切り替えられる。

**主要な処理内容**：
1. ユーザーが SetColorScheme アクションを実行
2. ActionArgs から SetColorSchemeArgs を取得し、スキーム名を読み取る
3. CascadiaSettings からスキーム名に一致するカラースキームを検索
4. TerminalSettings オブジェクトを一時生成しスキームを適用
5. _ApplyToActiveControls で全コントロールに SetOverrideColorScheme を呼び出し
6. ControlCore が Terminal の RenderSettings を更新し再描画

**関連システム・外部連携**：CascadiaSettings のカラースキームコレクション（settings.json で定義）を参照する。コマンドパレットのプレビュー機能と連携する（ActionPreviewHandlers.cpp）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleSetColorSchemeによりターミナルの配色を変更 |
| 6 | TermControl（ターミナル表示） | 主画面 | SetOverrideColorSchemeにより配色テーマを変更 |

## 機能種別

外観設定操作 / ランタイム設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SchemeName | String | Yes | 適用するカラースキームの名前 | CascadiaSettings に登録済みのスキーム名であること |

### 入力データソース

キーバインド設定またはコマンドパレットからの SetColorScheme アクション。スキーム定義は settings.json の ColorSchemes セクションから参照。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Handled | bool | スキームの適用が成功したかどうか |

### 出力先

ターミナルの RenderSettings のカラーテーブルが更新され、全セルが新しい配色で再描画される。

## 処理フロー

### 処理シーケンス

```
1. TerminalPage::_HandleSetColorScheme がアクションイベントを受信
   └─ ActionArgs から SetColorSchemeArgs を取得（SchemeName）
2. Handled を false に初期設定
3. _settings.GlobalSettings().ColorSchemes().TryLookup(schemeName) でスキーム検索
4. スキームが見つかった場合
   ├─ TerminalSettings オブジェクトを一時生成
   ├─ temporarySettings->ApplyColorScheme(scheme) でスキームを適用
   ├─ _ApplyToActiveControls で control.SetOverrideColorScheme を呼び出し
   └─ ICoreScheme インターフェースとして渡す
5. ControlCore::SetOverrideColorScheme が実行される
   ├─ LockForWriting 取得
   ├─ _focusedColorSchemeOverride にオーバーライドスキームを保存
   ├─ Terminal::UpdateColorScheme でカラーテーブルを更新
   └─ _renderer->TriggerRedrawAll(true) で全体再描画
```

### フローチャート

```mermaid
flowchart TD
    A[SetColorScheme アクション受信] --> B[SetColorSchemeArgs から SchemeName 取得]
    B --> C[Handled = false]
    C --> D[ColorSchemes.TryLookup でスキーム検索]
    D --> E{スキーム見つかった?}
    E -->|Yes| F[TerminalSettings を一時生成]
    E -->|No| G[Handled = false のまま終了]
    F --> H[ApplyColorScheme でスキーム適用]
    H --> I[_ApplyToActiveControls]
    I --> J[ControlCore::SetOverrideColorScheme]
    J --> K[_focusedColorSchemeOverride に保存]
    K --> L[Terminal::UpdateColorScheme]
    L --> M[TriggerRedrawAll で全体再描画]
    M --> N[終了]
    G --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-1 | スキーム名検証 | 指定されたスキーム名が ColorSchemes に存在しない場合、処理をスキップ | 常時 |
| BR-57-2 | ランタイムオーバーライド | プロファイル設定のスキームは変更せず、ランタイムのオーバーライドとして適用 | 常時 |
| BR-57-3 | プレビュー対応 | コマンドパレットでの選択時にプレビュー表示が可能 | コマンドパレット使用時 |
| BR-57-4 | フォーカス状態保持 | _focusedColorSchemeOverride としてフォーカス時のスキームを保持 | 常時 |

### 計算ロジック

特になし。カラーテーブル（16色 ANSI + 前景色 + 背景色）の入れ替え。

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

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。ランタイムのカラー設定のみを変更する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | スキーム不在 | 指定されたスキーム名が ColorSchemes に存在しない | Handled=false のまま終了 |
| なし | ActionArgs 取得失敗 | SetColorSchemeArgs へのキャストが失敗 | Handled=false のまま終了 |

### リトライ仕様

リトライ処理は不要。

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

ControlCore で LockForWriting を取得してカラーテーブルの更新と再描画をアトミックに行う。

## パフォーマンス要件

カラーテーブルの更新は O(1)（固定サイズのテーブル）。TriggerRedrawAll による全体再描画が発生する。

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

特になし。

## 備考

- プレビュー機能は ActionPreviewHandlers.cpp の _PreviewColorScheme で実装されている
- プレビュー時は _stashedColorScheme に元のスキームが保存され、キャンセル時に ResetPreviewColorScheme で復帰する
- scheme が null の場合、_settings の ICoreScheme にフォールバックする

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | SetColorSchemeArgs の定義（SchemeName プロパティ） |
| 1-2 | ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | SetOverrideColorScheme, _focusedColorSchemeOverride, _stashedColorScheme の宣言 |

**読解のコツ**: ICoreScheme インターフェースはカラーテーブルの抽象化。TerminalSettings が ICoreScheme を実装し、ColorScheme のデータをラップする。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleSetColorScheme メソッド（664-679行目） |

**主要処理フロー**:
1. **664-679行目**: SetColorSchemeArgs から SchemeName を取得し、TryLookup でスキーム検索、TerminalSettings を生成してコントロールに適用
2. **667行目**: Handled を初期値 false に設定
3. **670行目**: スキーム名で ColorSchemes を検索
4. **672-676行目**: 一時 TerminalSettings 生成、ApplyColorScheme、SetOverrideColorScheme 呼び出し

#### Step 3: ControlCore のカラースキーム適用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | SetOverrideColorScheme メソッド（1049-1056行目） |

**主要処理フロー**:
- **1049-1056行目**: LockForWriting 取得、_focusedColorSchemeOverride に保存、UpdateColorScheme でカラーテーブル更新、TriggerRedrawAll

#### Step 4: プレビュー機能を理解する（補足）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ActionPreviewHandlers.cpp | `src/cascadia/TerminalApp/ActionPreviewHandlers.cpp` | _PreviewColorScheme メソッド（95-154行目） |

**主要処理フロー**:
- **95-154行目**: プレビュー時のスキーム適用と _restorePreviewFuncs への復帰関数の登録

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

```
TerminalPage::_HandleSetColorScheme (AppActionHandlers.cpp:664)
    │
    ├─ ActionArgs.try_as<SetColorSchemeArgs>() → SchemeName 取得
    │
    ├─ _settings.GlobalSettings().ColorSchemes().TryLookup(name)
    │
    ├─ TerminalSettings::ApplyColorScheme(scheme)
    │
    └─ _ApplyToActiveControls
           │
           └─ ControlCore::SetOverrideColorScheme (ControlCore.cpp:1049)
                  │
                  ├─ _focusedColorSchemeOverride = scheme
                  ├─ Terminal::UpdateColorScheme(scheme)
                  └─ _renderer->TriggerRedrawAll(true)

[プレビュー経路]
TerminalPage::_PreviewColorScheme (ActionPreviewHandlers.cpp:95)
    │
    ├─ _restorePreviewFuncs.clear()
    ├─ TerminalSettings::ApplyColorScheme(scheme)
    └─ control.SetOverrideColorScheme(...)
```

### データフロー図

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

SetColorSchemeArgs   ───▶ TerminalPage                   ───▶ カラーテーブル更新
(SchemeName: string)       ::_HandleSetColorScheme             + 全体再描画
                                │
                                ├─ ColorSchemes.TryLookup ◀── settings.json
                                │
                                ▼
                           TerminalSettings
                           ::ApplyColorScheme
                                │
                                ▼
                           ControlCore
                           ::SetOverrideColorScheme
                                │
                                ├─ UpdateColorScheme → RenderSettings 更新
                                └─ TriggerRedrawAll ──────────▶ 画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleSetColorScheme アクションハンドラー |
| ActionPreviewHandlers.cpp | `src/cascadia/TerminalApp/ActionPreviewHandlers.cpp` | ソース | _PreviewColorScheme プレビュー機能 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | SetOverrideColorScheme, ResetPreviewColorScheme の実装 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ヘッダー | SetOverrideColorScheme メソッド宣言 |
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL | SetOverrideColorScheme の IDL 定義 |
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | IDL | SetColorSchemeArgs 定義 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ヘッダー | SetColorScheme アクション登録 |
| CascadiaSettings.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettings.cpp` | ソース | ColorSchemes コレクション管理 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | _restorePreviewFuncs 定義 |
