# 画面設計書 32-Extensions（拡張機能管理）

## 概要

本ドキュメントは、Windows Terminal の設定画面における「拡張機能管理」画面（Extensions）の設計仕様を記述する。フラグメント拡張機能（Fragment Extensions）のインストール状況を確認し、有効/無効を切り替え、拡張機能が追加・変更したプロファイルやカラースキームの詳細を確認するためのページである。

### 本画面の処理概要

**業務上の目的・背景**：Windows Terminal はフラグメント拡張機能により、外部からプロファイルやカラースキームを追加・変更できる仕組みを持つ。本画面は、インストール済みの拡張機能を一覧表示し、各拡張機能の有効/無効を切り替え、拡張機能がもたらした変更内容を JSON レベルで確認できるようにする。これにより、ユーザーは拡張機能の影響範囲を把握し、問題がある場合は個別に無効化できる。

**画面へのアクセス方法**：メイン画面（TerminalPage）から Ctrl+, で設定画面（MainPage）を開き、左側ナビゲーションの「拡張機能」項目を選択して遷移する。

**主要な操作・処理内容**：
1. インストール済み拡張機能パッケージの一覧表示（ルートビュー）
2. 各拡張機能の有効/無効切り替え（ToggleSwitch）
3. 拡張機能の詳細ビューへの遷移（拡張機能ナビゲーターボタンのクリック）
4. 拡張機能の詳細表示（スコープ、フラグメント JSON の確認）
5. 変更されたプロファイルの一覧と JSON 差分の表示
6. 追加されたプロファイルの一覧と JSON 内容の表示
7. 追加されたカラースキームの一覧とプレビューの表示
8. プロファイルやカラースキームへの直接ナビゲーション

**画面遷移**：MainPage（設定ナビゲーション）から遷移して表示される。拡張機能一覧からクリックすると拡張機能詳細ビューに切り替わる。プロファイルやカラースキームへのナビゲーションボタンで対応する設定ページに遷移できる。

**権限による表示制御**：特に権限による表示制御は行われない。拡張機能のスコープ（User/System）は表示のみで、操作への制限はない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | 設定の読み込み・保存 | 主機能 | 拡張機能の一覧表示・詳細確認・設定管理 |
| 84 | 設定UI | 主機能 | 拡張機能管理のUI表示 |

## 画面種別

設定（一覧 + 詳細のハイブリッド画面）

## URL/ルーティング

設定画面内のNavigationViewによるページ遷移。タグ値は `Extensions_Nav`。MainPage の ContentFrame に `Extensions` ページがナビゲートされる。

## 入出力項目

### ルートビュー

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 1 | ドキュメントリンク | HyperlinkButton | 出力 | - | フラグメント拡張機能の詳細情報リンク |
| 2 | アクティブな拡張機能一覧 | ItemsControl | 出力 | - | インストール済み拡張機能の一覧表示 |
| 3 | 有効/無効トグル | ToggleSwitch | 入力 | - | 各拡張機能の有効/無効を切り替え |
| 4 | 拡張機能ナビゲーター | Button | 入力 | - | 拡張機能詳細ビューへの遷移 |

### 拡張機能詳細ビュー

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 5 | 拡張機能名/ソース | Expander | 出力 | - | 拡張機能のアイコン・名前・ソース表示 |
| 6 | 有効/無効トグル | ToggleSwitch | 入力 | - | 拡張機能の有効/無効を切り替え |
| 7 | スコープ | SettingContainer | 出力 | - | User または System の表示 |
| 8 | フラグメント JSON | Expander + TextBlock | 出力 | - | 各フラグメントのファイル名と JSON 内容 |

### 変更/追加プロファイル一覧

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 9 | 変更プロファイル一覧 | ItemsControl | 出力 | - | 拡張機能により変更されたプロファイルの一覧 |
| 10 | 追加プロファイル一覧 | ItemsControl | 出力 | - | 拡張機能により追加されたプロファイルの一覧 |
| 11 | プロファイルナビゲーション | Button | 入力 | - | プロファイルの設定ページへ遷移 |
| 12 | プロファイル JSON | Expander + TextBlock | 出力 | - | プロファイルの JSON 設定内容 |

### 追加カラースキーム一覧

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 13 | 追加カラースキーム一覧 | ItemsControl | 出力 | - | 拡張機能により追加されたカラースキームの一覧 |
| 14 | カラースキームプレビュー | ColorChip Grid | 出力 | - | 16色のカラーチッププレビュー |
| 15 | カラースキームナビゲーション | Button | 入力 | - | カラースキーム設定ページへ遷移 |
| 16 | カラースキーム JSON | Expander + TextBlock | 出力 | - | カラースキームの JSON 設定内容 |

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | 拡張機能パッケージ | アイコン + 表示名 + ソース | DisplayName がある場合はアイコンと共に2行表示、ない場合はソースのみ表示 |
| 2 | 拡張機能スコープ | テキスト「User」または「System」 | FragmentScope に基づく表示 |
| 3 | フラグメント JSON | コードブロック（Cascadia Mono フォント） | テキスト選択可能な JSON 表示 |
| 4 | プロファイル名 | アイコン + プロファイル名 + ソース名 | Expander ヘッダーに表示 |
| 5 | カラースキーム | 16色チップ + スキーム名 | 背景色付きの2行8列カラーチップとテキスト |

## イベント仕様

### 1-拡張機能詳細への遷移

ExtensionNavigator_Click イベントハンドラにより、ボタンの Tag から ExtensionPackageViewModel を取得し、ViewModel.CurrentExtensionPackage を設定する。IsExtensionView プロパティが true になり、ルートビューから詳細ビューに切り替わる。

### 2-拡張機能の有効/無効切り替え

ToggleSwitch の IsOn が ExtensionPackageViewModel.Enabled プロパティに TwoWay バインドされている。Enabled の setter は ExtensionsViewModel.SetExtensionState() を呼び出し、settings.json の disabledProfileSources リストを更新する。有効/無効変更時は PropertyChanged 通知により関連するプロファイル・カラースキーム一覧が更新される。

### 3-プロファイルへのナビゲーション

NavigateToProfile_Click イベントハンドラにより、ボタンの Tag からプロファイル GUID を取得し、ExtensionsViewModel.NavigateToProfile() を呼び出す。NavigateToProfileRequested イベントが発火し、MainPage がこれを受けてプロファイル設定ページに遷移する。

### 4-カラースキームへのナビゲーション

NavigateToColorScheme_Click イベントハンドラにより、ボタンの Tag から ColorSchemeViewModel を取得し、ExtensionsViewModel.NavigateToColorScheme() を呼び出す。内部で ColorSchemesPageViewModel.CurrentScheme を設定し、NavigateToColorSchemeRequested イベントを発火する。

### 5-遅延読み込み

OnNavigatedTo 内で ExtensionsViewModel.LazyLoadExtensions() が呼び出される。拡張機能パッケージの列挙、フラグメントの解析、プロファイルとカラースキームのマッピングが行われる。2回目以降は _extensionsLoaded フラグにより処理がスキップされる。

## データベース更新仕様

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

本画面はデータベースを使用しない。設定は settings.json ファイルに保存される。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| 拡張機能の有効/無効切り替え | settings.json (disabledProfileSources) | UPDATE | disabledProfileSources 配列への追加/削除 |

## メッセージ仕様

| No | メッセージID | 種別 | メッセージ内容 | 表示条件 |
|----|-------------|------|---------------|----------|
| 1 | Extensions_DisclaimerHyperlink | 情報 | フラグメント拡張機能についてのリンク | ルートビューに常時表示 |
| 2 | Extensions_ScopeUser | 情報 | "User" | スコープが User の場合 |
| 3 | Extensions_ScopeSystem | 情報 | "System" | スコープが System の場合 |

## 例外処理

- 拡張機能がインストールされていない場合、一覧は空で表示される
- フラグメントが変更を試みたプロファイルが見つからない場合（ユーザーにより削除済み等）、該当エントリはスキップされる（Extensions.cpp 255-263行目のnullチェック）
- カラースキームが見つからない場合も同様にスキップされる

## 備考

- 拡張機能のテンプレート選択は ExtensionPackageTemplateSelector により行われる。DisplayName の有無、アイコンの文字コード範囲（Segoe MDL2 Icons: U+E700 - U+F8FF）に基づいて3種類のテンプレートが使い分けられる
- ルートビューでは有効な拡張機能のプロファイル/カラースキーム変更のみ表示される。詳細ビューでは選択した拡張機能の全変更が表示される
- JSON 表示は Cascadia Mono, Consolas フォントで表示され、テキスト選択が可能（IsTextSelectionEnabled=True）
- カラースキームのプレビューは Appearances.xaml から複製されたテンプレートを使用
- 一覧はすべて言語順（linguistic sort）でソートされる

---

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

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

### 推奨読解順序

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

拡張機能パッケージとフラグメントのビューモデル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Extensions.idl | `src/cascadia/TerminalSettingsEditor/Extensions.idl` | ExtensionsViewModel, ExtensionPackageViewModel, FragmentExtensionViewModel, FragmentProfileViewModel, FragmentColorSchemeViewModel の各インターフェース定義を確認する |
| 1-2 | Extensions.h | `src/cascadia/TerminalSettingsEditor/Extensions.h` | 37-81行目: ExtensionsViewModel の構造体。83-106行目: ExtensionPackageViewModel。108-186行目: 各フラグメント関連ViewModel |

**読解のコツ**: ViewModel が階層構造になっている。ExtensionsViewModel > ExtensionPackageViewModel > FragmentExtensionViewModel > FragmentProfileViewModel/FragmentColorSchemeViewModel の順で理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | 48行目: extensionsTag 定数定義 |
| 2-2 | Extensions.cpp | `src/cascadia/TerminalSettingsEditor/Extensions.cpp` | 22-32行目: コンストラクタでテンプレートセレクタの取得とアクセシビリティ名設定。34-70行目: OnNavigatedTo でViewModel受け取りと遅延読み込み |

**主要処理フロー**:
1. **22-32行目**: コンストラクタでリソースからテンプレートセレクタを取得
2. **34-39行目**: OnNavigatedTo で ViewModel を受け取り、テンプレートセレクタを設定
3. **39行目**: LazyLoadExtensions() で拡張機能の遅延読み込みを実行
4. **41-69行目**: テレメトリ送信（ルートビューと詳細ビューで異なる情報）

#### Step 3: 遅延読み込みロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Extensions.cpp | `src/cascadia/TerminalSettingsEditor/Extensions.cpp` | 225-358行目: LazyLoadExtensions() の実装。拡張機能パッケージの列挙、フラグメントの解析、プロファイル/カラースキームのマッピングと ViewModel の構築 |

#### Step 4: 有効/無効切り替えロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Extensions.cpp | `src/cascadia/TerminalSettingsEditor/Extensions.cpp` | 366-375行目: GetExtensionState() で disabledProfileSources リストを確認。378-412行目: SetExtensionState() で有効/無効を切り替え |
| 4-2 | Extensions.cpp | `src/cascadia/TerminalSettingsEditor/Extensions.cpp` | 460-472行目: ExtensionPackageViewModel.Enabled の getter/setter。SetExtensionState を呼び出す |

#### Step 5: XAMLレイアウトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Extensions.xaml | `src/cascadia/TerminalSettingsEditor/Extensions.xaml` | 445-557行目: ルートビュー（拡張機能一覧）と詳細ビュー（拡張機能詳細+プロファイル/カラースキーム一覧）のレイアウト |

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

```
MainPage (設定ナビゲーション)
    |
    +-- Extensions (ページ)
            |
            +-- ExtensionsViewModel
            |       |
            |       +-- LazyLoadExtensions()
            |       |       +-- ExtensionPackageViewModel (各パッケージ)
            |       |       |       +-- FragmentExtensionViewModel (各フラグメント)
            |       |       |               +-- FragmentProfileViewModel (変更/追加プロファイル)
            |       |       |               +-- FragmentColorSchemeViewModel (追加カラースキーム)
            |       |       +-- _UpdateListViews()
            |       |
            |       +-- GetExtensionState() / SetExtensionState()
            |       +-- NavigateToProfile() --> NavigateToProfileRequested event
            |       +-- NavigateToColorScheme() --> NavigateToColorSchemeRequested event
            |
            +-- ExtensionPackageTemplateSelector
                    +-- SelectTemplateCore()
                            +-- DefaultTemplate (ソースのみ)
                            +-- ComplexTemplate (アイコン+名前+ソース)
                            +-- ComplexTemplateWithFontIcon (フォントアイコン+名前+ソース)
```

### データフロー図

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

拡張機能パッケージ         ExtensionsViewModel              UIリスト
(settings.Extensions())    LazyLoadExtensions()            (拡張機能一覧)
        |                         |                              |
        +-- FragmentsView ----> フラグメント解析 ---------> FragmentExtensionViewModel
                                  |                              |
                    ModifiedProfilesView ---------> FragmentProfileViewModel
                    NewProfilesView ----------> FragmentProfileViewModel
                    ColorSchemesView ---------> FragmentColorSchemeViewModel

ToggleSwitch             ExtensionPackageViewModel        settings.json
(有効/無効)              Enabled setter                   (disabledProfileSources)
        |                         |                              |
        +-- SetExtensionState --> disabledProfileSources 更新 --> 保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Extensions.xaml | `src/cascadia/TerminalSettingsEditor/Extensions.xaml` | ソース | ページのXAMLレイアウト定義 |
| Extensions.cpp | `src/cascadia/TerminalSettingsEditor/Extensions.cpp` | ソース | ページとViewModelのコードビハインド |
| Extensions.h | `src/cascadia/TerminalSettingsEditor/Extensions.h` | ソース | ヘッダー定義（全ViewModelの構造体含む） |
| Extensions.idl | `src/cascadia/TerminalSettingsEditor/Extensions.idl` | ソース | WinRT インターフェース定義 |
| MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | ソース | 設定画面のメインページ（ナビゲーション管理） |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル・テンプレートリソース |
| ColorSchemesPageViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.idl` | ソース | カラースキーム遷移先のViewModel定義 |
