# Windows Terminal コードリーディングガイドライン

## はじめに

このガイドラインは、Windows Terminal（Microsoft/terminal）のコードベースを効率的に理解するための手引きです。
C++やWinRT/XAMLに精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者（C++/WinRT未経験者含む）
- コードレビューを行う担当者

---

## 1. 言語基礎

> このセクションでは、C++20とC++/WinRTの基本構文と概念を解説します。

### 1.1 プログラム構造

本プロジェクトはC++20（一部C#/.NET）で記述されたWindowsデスクトップアプリケーションです。エントリーポイントは `wWinMain` で、Win32 Windowsアプリケーションの標準的な形式を取ります。

```cpp
// ファイル: src/cascadia/WindowsTerminal/main.cpp:85
int __stdcall wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int nCmdShow)
{
    TraceLoggingRegister(g_hWindowsTerminalProvider);
    // ...
    winrt::init_apartment(winrt::apartment_type::single_threaded);

    const auto emperor = std::make_shared<::WindowEmperor>();
    emperor->HandleCommandlineArgs(nCmdShow);
}
```

**ポイント:**
- `wWinMain` はUnicode版のWindowsアプリケーション・エントリーポイント
- `winrt::init_apartment(single_threaded)` でSTA（シングルスレッドアパートメント）を初期化
- `WindowEmperor` がアプリケーション全体のライフサイクルを管理

### 1.2 データ型と変数

C++20の型システムに加え、プロジェクト固有の型が多数定義されています。

```cpp
// ファイル: src/cascadia/TerminalControl/ControlCore.h:63-64
til::property<til::color> Color;
til::property<bool> IsIndex16;
```

**主要な型パターン:**
| 型 | 用途 | 定義元 |
|---|---|---|
| `til::color` | COLORREF ラッパー | `src/inc/til/color.h` |
| `til::rect` / `til::inclusive_rect` | 矩形型（SMALL_RECT互換） | `src/inc/til/rect.h` |
| `til::size` / `til::point` | サイズ・座標型 | `src/inc/til/rect.h` |
| `til::property<T>` | WinRT風プロパティ | `src/inc/til/winrt.h` |
| `til::enumset<T>` | 型安全ビットセット | `src/inc/til/enumset.h` |
| `winrt::hstring` | WinRTの不変文字列 | C++/WinRT標準 |
| `wil::unique_*` | RAIIラッパー（ハンドル等） | Windows Implementation Library |

### 1.3 制御構造

基本的なC++制御構造に加え、以下のプロジェクト固有のパターンがあります。

**WILエラーハンドリングマクロ:**
```cpp
// ファイル: src/cascadia/WindowsTerminal/main.cpp:66
THROW_IF_WIN32_BOOL_FALSE(IsWow64Process2(GetCurrentProcess(), &processMachine, &nativeMachine));
```

- `THROW_IF_WIN32_BOOL_FALSE` — Win32 API呼出しの戻り値がFALSEの場合に例外をスロー
- `THROW_HR` — HRESULTエラーを例外としてスロー
- `LOG_CAUGHT_EXCEPTION()` — 捕捉した例外をログに記録

**条件付きコンパイル:**
```cpp
// ファイル: src/cascadia/TerminalCore/Terminal.hpp:45-51
#ifdef UNIT_TESTING
namespace TerminalCoreUnitTests
{
    class TerminalBufferTests;
    class TerminalApiTest;
};
#endif
```

### 1.4 関数/メソッド定義

本プロジェクトでは、メソッドに`noexcept`、`const`、`[[nodiscard]]`などの修飾子が頻繁に使われます。

```cpp
// ファイル: src/cascadia/WindowsTerminal/WindowEmperor.h:33-37
HWND GetMainWindow() const noexcept;
AppHost* GetWindowById(uint64_t id) const noexcept;
AppHost* GetWindowByName(std::wstring_view name) const noexcept;
void CreateNewWindow(winrt::TerminalApp::WindowRequestedArgs args);
void HandleCommandlineArgs(int nCmdShow);
```

**コルーチン（C++20 Coroutines）:**
```cpp
// ファイル: src/cascadia/WindowsTerminal/AppHost.h:27
safe_void_coroutine HandleSummon(winrt::TerminalApp::SummonWindowBehavior args) const;
```

`safe_void_coroutine` は `winrt::fire_and_forget` の安全版で、未処理例外をアプリ終了ではなくログ記録のみで処理します（`src/cascadia/inc/cppwinrt_utils.h:25-66`）。

### 1.5 モジュール/インポート

C++のヘッダーインクルードに加え、C++/WinRT固有のパターンがあります。

```cpp
// ファイル: src/cascadia/WindowsTerminal/main.cpp:4-14
#include "pch.h"                           // プリコンパイル済みヘッダー
#include "WindowEmperor.h"                 // プロジェクト内ヘッダー
#include "../types/inc/User32Utils.hpp"    // 共有ユーティリティ
#include <WilErrorReporting.h>             // 外部ライブラリ

using namespace winrt;
using namespace winrt::Windows::UI;
using namespace winrt::Windows::UI::Xaml::Hosting;
```

**命名規約:**
- `pch.h` — cascadia系プロジェクトのプリコンパイル済みヘッダー
- `precomp.h` — conhost系プロジェクトのプリコンパイル済みヘッダー
- `.h` — 一般的なヘッダー
- `.hpp` — コア層やバッファ層で使われるヘッダー（テンプレート等を多く含む）
- `*.g.h` — C++/WinRTツールが自動生成するヘッダー（手動編集禁止）

---

## 2. プロジェクト固有の概念

> このセクションでは、当プロジェクト特有の概念を解説します。

### 2.1 フレームワーク固有の概念

#### C++/WinRT

C++/WinRTは、Windows Runtime APIをネイティブC++から利用するための投影技術です。IDLファイルから自動生成される基底クラスをCRTPパターンで継承します。

```cpp
// ファイル: src/cascadia/TerminalApp/AppLogic.h:27
struct AppLogic : AppLogicT<AppLogic>
{
    // AppLogicT<AppLogic> は AppLogic.g.h (自動生成) から取得
    // IDLで宣言したインターフェースの実装を提供
};
```

**IDL定義の例:**
IDLファイルでWinRTのランタイムクラスとインターフェースを宣言し、cppwinrtツールが対応するヘッダーを生成します。

```idl
// 例: AppLogic.idl
namespace TerminalApp
{
    [default_interface] runtimeclass AppLogic
    {
        void Create();
        TerminalWindow CreateNewWindow();
        event Windows.Foundation.TypedEventHandler<Object, SettingsLoadEventArgs> SettingsChanged;
    }
}
```

#### XAML (Windows UI)

UIはXAML（Extensible Application Markup Language）で記述されます。`src/cascadia/TerminalApp/` と `src/cascadia/TerminalControl/` にXAMLファイルがあります。

#### WIL (Windows Implementation Library)

エラーハンドリング、RAIIラッパー、トレースログなどのユーティリティを提供するMicrosoft製ライブラリです。

- `wil::unique_hwnd` — HWNDのRAIIラッパー
- `THROW_IF_WIN32_BOOL_FALSE()` — Win32 APIのエラーチェックマクロ
- `TraceLogging*` — ETWベースのテレメトリ

### 2.2 プロジェクト独自のパターン

#### TIL (Terminal Implementation Library)

`til` 名前空間（`src/inc/til/`）はプロジェクト全体で使われる共通ユーティリティライブラリです。

```cpp
// ファイル: src/inc/til.h:55
namespace til // Terminal Implementation Library. Also: "Today I Learned"
```

主要コンポーネント:
| ヘッダー | 内容 |
|---|---|
| `til/color.h` | COLORREFラッパー |
| `til/rect.h` | 矩形・座標型 |
| `til/winrt.h` | `property<T>`, `typed_event<>` |
| `til/rle.h` | ランレングスエンコーディング（TextAttribute配列用） |
| `til/mutex.h` | 型安全ミューテックスガード `shared_mutex<T>` |
| `til/ticket_lock.h` | フェアな読み書きチケットロック |
| `til/enumset.h` | 型安全ビットセット |
| `til/small_vector.h` | スタックバッファ付き小サイズベクター |
| `til/generational.h` | 世代管理（変更追跡） |

#### プロパティマクロ

WinRTプロパティの定義を簡略化するマクロ群があります。

```cpp
// ファイル: src/cascadia/TerminalSettingsModel/CascadiaSettings.h:59-60
WINRT_PROPERTY(hstring, Icon);
WINRT_PROPERTY(hstring, DisplayName);
```

| マクロ | 用途 |
|---|---|
| `WINRT_PROPERTY(type, name)` | 単純なゲッター/セッター |
| `WINRT_OBSERVABLE_PROPERTY(type, name, event)` | 変更通知付きプロパティ |
| `TYPED_EVENT(name, sender, args)` | WinRTイベントの定義 |
| `RUNTIME_SETTING(type, name, setting)` | ランタイム上書き可能な設定 |

#### safe_void_coroutine

```cpp
// ファイル: src/cascadia/inc/cppwinrt_utils.h:25-27
struct safe_void_coroutine
{
};
```

`winrt::fire_and_forget` と同等のfire-and-forgetコルーチンですが、未処理例外時にアプリケーションを終了させず、`LOG_CAUGHT_EXCEPTION()` でログ記録のみを行います（`cppwinrt_utils.h:55-57`）。

#### 設定継承システム (IInheritable)

`src/cascadia/TerminalSettingsModel/IInheritable.h` で定義される継承チェーンにより、設定プロファイルが親プロファイルから値を継承する仕組みです。`defaults.json` → `userDefaults.json` → ユーザー設定 の順で解決されます。

#### Feature Flags

`src/features.xml` で機能フラグを定義し、`Generate-FeatureStagingHeader.ps1` でC++ヘッダーを自動生成します。ブランディング段階（Dev, Canary, Release, WindowsInbox）に応じて機能の有効/無効を切り替えます。

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| PascalCase | クラス名と一致するソースファイル | `WindowEmperor.h`, `AppHost.cpp` |
| `*.g.h` | C++/WinRT自動生成ヘッダー | `AppLogic.g.h`, `TermControl.g.h` |
| `*.idl` | WinRTインターフェース定義 | `AppLogic.idl`, `TermControl.idl` |
| `*.xaml` | UIマークアップ | `TerminalPage.xaml`, `App.xaml` |
| `pch.h` / `pch.cpp` | cascadia系プリコンパイル済みヘッダー | `src/cascadia/*/pch.h` |
| `precomp.h` / `precomp.cpp` | conhost系プリコンパイル済みヘッダー | `src/host/precomp.h` |
| `*.hpp` | テンプレート/インライン実装を含むヘッダー | `Terminal.hpp`, `textBuffer.hpp` |
| camelCase ディレクトリ | ソースサブモジュール | `src/cascadia/`, `src/buffer/` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| PascalCase（パブリックメソッド） | パブリックAPI | `HandleCommandlineArgs()`, `CreateNewWindow()` |
| `_`プレフィックス + PascalCase | プライベートメソッド | `_registerHotKey()`, `_persistState()` |
| `_`プレフィックス + camelCase | プライベートメンバー変数 | `_window`, `_appLogic`, `_windowLogic` |
| `_`プレフィックス + PascalCase | プライベートプロパティバッキングフィールド | `_ProposedName` (WINRTプロパティ) |
| `g_`プレフィックス | グローバル変数 | `g_hWindowsTerminalProvider` |
| `s_`プレフィックス | 静的メンバー | 各種staticメソッド |
| `*T<Self>` サフィックス | C++/WinRT CRTPベースクラス | `AppLogicT<AppLogic>` |
| `I`プレフィックス | インターフェース | `ITerminalApi`, `ITerminalInput`, `IRenderData` |
| `*Revoker` / `*_revoker` | イベント解除用トークン | `Initialized_revoker` |

### 3.3 プログラム分類一覧

| 分類 | プレフィックス/パターン | ファイル場所 | 例 |
|------|----------------------|-------------|-----|
| WinRTランタイムクラス | IDL + .g.h + 実装.h/.cpp | `src/cascadia/` 配下 | `AppLogic`, `TermControl` |
| ネイティブC++クラス | .h / .hpp + .cpp | `src/host/`, `src/buffer/` | `Terminal`, `TextBuffer` |
| XAMLページ/コントロール | .xaml + .h + .cpp | `src/cascadia/TerminalApp/` | `TerminalPage`, `TermControl` |
| 接続クラス | `*Connection` | `src/cascadia/TerminalConnection/` | `ConptyConnection` |
| 設定モデル | `*Settings`, `Profile` | `src/cascadia/TerminalSettingsModel/` | `CascadiaSettings`, `GlobalAppSettings` |
| テスト | `*Tests` | 各 `ut_*` サブディレクトリ | `TerminalBufferTests` |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
terminal-main/
├── src/                           # 全ソースコード
│   ├── cascadia/                  # Windows Terminal (C++/WinRT + XAML)
│   │   ├── WindowsTerminal/       #   EXEエントリ、WindowEmperor、AppHost
│   │   ├── TerminalApp/           #   XAMLアプリ層 (AppLogic, TerminalPage, Tab, Pane)
│   │   ├── TerminalControl/       #   TermControl XAMLコントロール + ControlCore
│   │   ├── TerminalCore/          #   VTエミュレータ本体 (Terminal クラス)
│   │   ├── TerminalSettingsModel/ #   設定モデル (CascadiaSettings, Profile)
│   │   ├── TerminalSettingsEditor/ #  設定UI (XAML + ViewModel)
│   │   ├── TerminalConnection/    #   接続層 (ConptyConnection, AzureConnection)
│   │   ├── Remoting/              #   ウィンドウ間通信
│   │   ├── WinRTUtils/            #   ThrottledFunc, SafeDispatcherTimer等
│   │   ├── UIHelpers/             #   UI補助ユーティリティ
│   │   ├── UIMarkdown/            #   Markdownパネル
│   │   ├── CascadiaPackage/       #   MSIXパッケージプロジェクト
│   │   ├── ElevateShim/           #   UAC昇格シム
│   │   ├── wt/                    #   wt.exe シム（リダイレクト）
│   │   └── inc/                   #   共通WinRTユーティリティヘッダー
│   ├── host/                      # conhost.exe (古典的コンソールホスト)
│   ├── server/                    # コンソールサーバー (APIディスパッチャー)
│   ├── terminal/                  # VTパーサー・アダプター・入力
│   │   ├── adapter/               #   VTシーケンス → 端末操作変換
│   │   ├── parser/                #   VTエスケープシーケンスパーサー (StateMachine)
│   │   └── input/                 #   キー入力 → VTシーケンス変換
│   ├── renderer/                  # レンダリングエンジン群
│   │   ├── atlas/                 #   AtlasEngine (DirectX 11, 高速)
│   │   ├── dx/                    #   DxEngine (Direct2D/DirectWrite)
│   │   ├── gdi/                   #   GdiEngine (conhost用)
│   │   ├── uia/                   #   UIAutomation (アクセシビリティ)
│   │   └── inc/                   #   レンダラーインターフェース
│   ├── buffer/out/                # テキストバッファ (TextBuffer, ROW)
│   ├── types/                     # 共有型 (Viewport, GlyphWidth, UIA)
│   ├── til/                       # TILの追加ユーティリティ
│   ├── inc/                       # 共通インクルード (til.h, DefaultSettings.h)
│   │   └── til/                   #   TILヘッダー群
│   ├── interactivity/             # プラットフォーム入力抽象
│   │   ├── base/                  #   基底インターフェース
│   │   ├── win32/                 #   Win32実装
│   │   └── onecore/               #   OneCore実装
│   ├── winconpty/                 # ConPTY (Windows Pseudo Console)
│   ├── tools/                     # ColorTool等の補助ツール
│   ├── audio/                     # オーディオ (MIDI, ベル音)
│   ├── tsf/                       # Text Services Framework
│   └── propslib/                  # プロパティシート用ライブラリ
├── build/                         # ビルドパイプライン (Azure DevOps)
├── dep/                           # 依存ライブラリ (vcpkg, NT/Console ヘッダー)
├── doc/                           # 設計仕様書 (Markdown)
├── oss/                           # OSS コンポーネント (chromium numerics, pcg等)
├── res/                           # リソースファイル
├── samples/                       # ConPTY サンプルコード
├── tools/                         # ビルド補助スクリプト (.ps1, .cmd)
├── OpenConsole.slnx               # Visual Studio ソリューション
└── vcpkg.json                     # vcpkg 依存関係マニフェスト
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `src/cascadia/WindowsTerminal/` | アプリケーションEXE、ウィンドウ管理 | `main.cpp`, `WindowEmperor.h/cpp`, `AppHost.h/cpp` |
| `src/cascadia/TerminalApp/` | XAML UIロジック（タブ、ペイン、コマンド） | `AppLogic.h`, `TerminalPage.h`, `Pane.h`, `Tab.h` |
| `src/cascadia/TerminalControl/` | TermControl XAMLコントロール | `TermControl.h`, `ControlCore.h`, `ControlInteractivity.h` |
| `src/cascadia/TerminalCore/` | VTエミュレータ本体 | `Terminal.hpp`, `TerminalApi.cpp`, `TerminalSelection.cpp` |
| `src/cascadia/TerminalSettingsModel/` | JSON設定のパース・管理 | `CascadiaSettings.h`, `Profile.h`, `GlobalAppSettings.h` |
| `src/cascadia/TerminalConnection/` | プロセス接続抽象層 | `ConptyConnection.h`, `AzureConnection.h` |
| `src/host/` | conhost.exe（レガシーコンソールホスト） | `exemain.cpp`, `screenInfo.h`, `getset.cpp` |
| `src/terminal/parser/` | VTシーケンスのステートマシン | `StateMachine.hpp`, `stateMachine.cpp` |
| `src/terminal/adapter/` | VTシーケンス → 端末操作変換 | `AdaptDispatch.hpp`, `ITerminalApi.hpp` |
| `src/renderer/atlas/` | DirectX 11 GPUレンダラー | `AtlasEngine.h`, `AtlasEngine.api.cpp` |
| `src/buffer/out/` | テキストバッファデータ構造 | `textBuffer.hpp`, `Row.h`, `TextAttribute.hpp` |
| `src/types/` | プロジェクト横断の共有型 | `Viewport.hpp`, `GlyphWidth.hpp` |
| `src/inc/til/` | Terminal Implementation Library | `color.h`, `rect.h`, `winrt.h`, `rle.h` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

Windows Terminalはレイヤードアーキテクチャを採用しています。UI層（XAML/WinRT）、コントロール層、コア層（VTエミュレータ）、バッファ層、レンダラー層が明確に分離されています。

```mermaid
graph TD
    subgraph "UI層 (XAML/WinRT)"
        WE[WindowEmperor] --> AH[AppHost]
        AH --> AL[AppLogic]
        AL --> TP[TerminalPage]
        TP --> Tab[Tab]
        Tab --> Pane[Pane]
    end

    subgraph "コントロール層"
        Pane --> TC[TermControl]
        TC --> CI[ControlInteractivity]
        CI --> CC[ControlCore]
    end

    subgraph "コア層"
        CC --> Term[Terminal]
        Term --> SM[StateMachine<br/>VTパーサー]
        Term --> AD[AdaptDispatch<br/>VTアダプタ]
        Term --> TI[TerminalInput<br/>キー入力]
    end

    subgraph "データ層"
        Term --> TB[TextBuffer]
        TB --> ROW[ROW]
        ROW --> TA[TextAttribute]
    end

    subgraph "レンダラー層"
        CC --> AE[AtlasEngine<br/>DirectX 11]
        CC --> R[Renderer]
    end

    subgraph "接続層"
        CC --> Conn[ConptyConnection]
        Conn --> ConPTY[ConPTY API]
    end
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| ウィンドウ管理 | プロセス内複数ウィンドウ管理、ホットキー、通知アイコン | `WindowEmperor.h`, `AppHost.h`, `IslandWindow.h` |
| アプリロジック | 設定読み込み、タブ/ペイン管理、コマンドパレット | `AppLogic.h`, `TerminalPage.h`, `Pane.h`, `Tab.h` |
| XAMLコントロール | ユーザー入力処理、UIイベント | `TermControl.h`, `ControlInteractivity.h` |
| コントロールコア | Terminal + Renderer + Connection の統合 | `ControlCore.h` |
| VTエミュレータ | VTシーケンス解析・実行、テキスト操作 | `Terminal.hpp`, `StateMachine.hpp`, `AdaptDispatch.hpp` |
| テキストバッファ | 文字列・属性の格納、スクロールバック | `textBuffer.hpp`, `Row.h`, `TextAttribute.hpp` |
| レンダラー | 画面描画 (DirectX 11 Atlas / Direct2D / GDI) | `AtlasEngine.h` |
| 接続 | 子プロセス管理、ConPTYパイプ | `ConptyConnection.h` |
| 設定モデル | JSON設定パース、プロファイル継承 | `CascadiaSettings.h`, `Profile.h` |

### 5.3 データフロー

**入力フロー（キー入力 → シェルへの送信）:**
```
ユーザーキー入力
  → TermControl (XAML UIイベント)
  → ControlInteractivity::KeyDown()
  → ControlCore
  → Terminal::SendKeyEvent()
  → TerminalInput (VTシーケンス変換)
  → ConptyConnection::WriteInput()
  → ConPTY パイプ → シェルプロセス
```

**出力フロー（シェル出力 → 画面表示）:**
```
シェルプロセス出力
  → ConPTY パイプ
  → ConptyConnection (読み取りスレッド)
  → ControlCore::_connectionOutputHandler()
  → Terminal::Write() → StateMachine (VTパース)
  → AdaptDispatch (VTコマンド実行)
  → TextBuffer (テキスト更新)
  → Renderer::TriggerPaint()
  → AtlasEngine (DirectX 11 描画)
```

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

アプリケーションには2つの主要なエントリーポイントがあります。

**Windows Terminal (wt.exe / WindowsTerminal.exe):**
```cpp
// ファイル: src/cascadia/WindowsTerminal/main.cpp:85-125
int __stdcall wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int nCmdShow)
{
    // 1. トレースログ登録
    TraceLoggingRegister(g_hWindowsTerminalProvider);
    // 2. アーキテクチャ検証
    EnsureNativeArchitecture();
    // 3. STA初期化
    winrt::init_apartment(winrt::apartment_type::single_threaded);
    // 4. WindowEmperor 生成 → メッセージループ開始
    const auto emperor = std::make_shared<::WindowEmperor>();
    emperor->HandleCommandlineArgs(nCmdShow);
}
```

**conhost.exe:**
```
ファイル: src/host/exe/exemain.cpp:219
```
レガシーコンソールホスト。Windows Terminal内部でもConPTY経由で使用されます。

### 6.2 ビジネスロジック

**WindowEmperor** — プロセス全体の管理者:
```cpp
// ファイル: src/cascadia/WindowsTerminal/WindowEmperor.h:22-98
class WindowEmperor
{
    // 複数ウィンドウの管理
    std::vector<std::shared_ptr<::AppHost>> _windows;
    // グローバルホットキー
    std::vector<winrt::Microsoft::Terminal::Settings::Model::GlobalSummonArgs> _hotkeys;
    // 通知アイコン
    NOTIFYICONDATA _notificationIcon{};
    // セッション永続化
    SafeDispatcherTimer _persistStateTimer;
};
```

**AppLogic** — アプリケーション設定管理:
```cpp
// ファイル: src/cascadia/TerminalApp/AppLogic.h:27-28
struct AppLogic : AppLogicT<AppLogic>
{
    void Create();                         // 設定読み込み
    TerminalApp::TerminalWindow CreateNewWindow(); // 新規ウィンドウ
    Microsoft::Terminal::Settings::Model::CascadiaSettings Settings() const noexcept;
};
```

**Pane** — 分割ペインの管理（二分木構造）:
```cpp
// ファイル: src/cascadia/TerminalApp/Pane.h:62-70
class Pane : public std::enable_shared_from_this<Pane>
{
    // リーフペイン（ターミナルコンテンツを保持）
    Pane(winrt::TerminalApp::IPaneContent content, const bool lastFocused = false);
    // 分岐ペイン（子ペインを2つ持つ）
    Pane(std::shared_ptr<Pane> first, std::shared_ptr<Pane> second,
         const SplitState splitType, ...);
};
```

### 6.3 データアクセス

**Terminal** — VTエミュレータコア:
```cpp
// ファイル: src/cascadia/TerminalCore/Terminal.hpp:54-57
class Microsoft::Terminal::Core::Terminal final :
    public Microsoft::Console::VirtualTerminal::ITerminalApi,  // VTシーケンス処理
    public Microsoft::Terminal::Core::ITerminalInput,          // キー入力
    public Microsoft::Console::Render::IRenderData             // レンダーデータ提供
```

Terminalクラスは3つのインターフェースを実装し、VT処理・入力・描画データの中心点となります。

**ConptyConnection** — プロセス接続:
```cpp
// ファイル: src/cascadia/TerminalConnection/ConptyConnection.h:15
struct ConptyConnection : ConptyConnectionT<ConptyConnection>,
                          BaseTerminalConnection<ConptyConnection>
{
    void Start();                                // 子プロセス起動
    void WriteInput(const winrt::array_view<const char16_t> buffer); // 入力送信
    void Resize(uint32_t rows, uint32_t columns); // サイズ変更
    void Close() noexcept;                       // 接続終了
};
```

### 6.4 ユーティリティ/共通機能

**TIL (Terminal Implementation Library):**

```cpp
// ファイル: src/inc/til.h:55-96
namespace til // Terminal Implementation Library. Also: "Today I Learned"
{
    // 安全なスライス操作
    template<typename T>
    as_view_t<T> safe_slice_abs(const T& view, size_t beg, size_t end) noexcept;

    // ベクターの効率的なメモリ管理
    template<typename T>
    void manage_vector(std::vector<T>& vector, size_t requestedSize, float shrinkThreshold);
}
```

**cppwinrt_utils.h** — WinRTイベント定義マクロ:
```cpp
// ファイル: src/cascadia/inc/cppwinrt_utils.h:74-79
#define TYPED_EVENT(name, sender, args)                                                  \
public:                                                                                  \
    winrt::event_token name(const winrt::Windows::Foundation::TypedEventHandler<sender, args>& handler) \
    {                                                                                    \
        return _##name##Handlers.add(handler);                                           \
    }
```

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| CRTP WinRT実装 | IDLから生成された基底クラスを継承 | 高 | `AppLogic.h`, `TermControl.h` |
| safe_void_coroutine | 安全なfire-and-forgetコルーチン | 高 | `AppHost.h`, `WindowEmperor.h` |
| WINRT_PROPERTY | プロパティ定義マクロ | 高 | `CascadiaSettings.h`, `TerminalPage.h` |
| TYPED_EVENT | イベント定義マクロ | 高 | `AppLogic.h`, `ControlCore.h` |
| Revokerパターン | イベント購読の自動解除 | 高 | `AppHost.h:138-163` |
| RUNTIME_SETTING | ランタイム上書き可能設定 | 中 | `ControlCore.h:43-55` |
| IInheritable | 設定値の親子継承 | 中 | `IInheritable.h`, `Profile.h` |
| ThrottledFunc | 関数呼出しのスロットリング | 中 | `AppLogic.h:68`, `AppHost.h:42` |
| WILエラーマクロ | Win32エラーハンドリング | 高 | プロジェクト全体 |
| enable_shared_from_this | shared_ptrの自己参照 | 中 | `AppHost.h:12`, `Pane.h:62` |

### 各パターンの詳細

#### パターン1: CRTP WinRT実装

**目的:** IDLで宣言したWinRTランタイムクラスをC++で実装する

**実装例:**
```cpp
// ファイル: src/cascadia/TerminalApp/AppLogic.h:27
struct AppLogic : AppLogicT<AppLogic>
{
    // AppLogicT<AppLogic>はAppLogic.g.h(自動生成)で定義
    // IInspectable等のWinRTインターフェースメソッドが自動実装される
    static AppLogic* Current() noexcept;
    void Create();
};
```

**解説:** `AppLogicT<AppLogic>` はCRTP（Curiously Recurring Template Pattern）で、`AppLogic.g.h` から自動生成される基底クラスです。IDLで定義したメソッドシグネチャへのフォワードを提供します。

#### パターン2: Revokerパターン（イベント購読の自動解除）

**目的:** デストラクタ時にイベント購読を自動的に解除し、メモリリークを防止する

**実装例:**
```cpp
// ファイル: src/cascadia/WindowsTerminal/AppHost.h:138-163
struct Revokers
{
    winrt::TerminalApp::TerminalWindow::Initialized_revoker Initialized;
    winrt::TerminalApp::TerminalWindow::RequestedThemeChanged_revoker RequestedThemeChanged;
    winrt::TerminalApp::TerminalWindow::FullscreenChanged_revoker FullscreenChanged;
    // ... 多数のrevoker
} _revokers{};
```

**解説:** `_revokers` に新しい `Revokers` インスタンスを代入すると、古いインスタンスのデストラクタが全イベントの `revoke()` を呼び出します。

#### パターン3: RUNTIME_SETTING

**目的:** 設定ファイルの値をランタイムで一時的に上書き可能にする

**実装例:**
```cpp
// ファイル: src/cascadia/TerminalControl/ControlCore.h:43-55
#define RUNTIME_SETTING(type, name, setting)                 \
private:                                                     \
    std::optional<type> _runtime##name{ std::nullopt };      \
    void name(const type newValue)                           \
    {                                                        \
        _runtime##name = newValue;                           \
    }                                                        \
public:                                                      \
    type name() const                                        \
    {                                                        \
        return til::coalesce_value(_runtime##name, setting); \
    }
```

**解説:** `til::coalesce_value` でランタイム値が設定されていればそれを、なければ設定ファイルの値を返します。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定（`main.cpp` の `wWinMain`）
2. 処理の流れを追跡（呼び出し関係を追う）
3. データの変換を確認（VTシーケンス ↔ テキスト操作）
4. 最終的な出力を確認（レンダラーでの描画）

### 8.2 フロー追跡の実例

#### 例1: アプリケーション起動フロー

**概要:** ユーザーが `wt.exe` を実行してからターミナルウィンドウが表示されるまでの流れ

**処理フロー:**
```
wWinMain → WindowEmperor::HandleCommandlineArgs → AppLogic::Create
  → CascadiaSettings読み込み → TerminalWindow生成 → AppHost生成
  → IslandWindow作成 → TerminalPage + Tab + Pane + TermControl 初期化
  → ConptyConnection::Start → シェルプロセス起動
```

**詳細な追跡:**

1. **wWinMain** (`src/cascadia/WindowsTerminal/main.cpp:85`)
   ```cpp
   winrt::init_apartment(winrt::apartment_type::single_threaded);
   const auto emperor = std::make_shared<::WindowEmperor>();
   emperor->HandleCommandlineArgs(nCmdShow);
   ```

2. **WindowEmperor::HandleCommandlineArgs** — コマンドライン解析後、既存プロセスへのハンドオフを試みるか、新規ウィンドウを作成

3. **WindowEmperor::CreateNewWindow** (`src/cascadia/WindowsTerminal/WindowEmperor.h:36`)
   ```cpp
   void CreateNewWindow(winrt::TerminalApp::WindowRequestedArgs args);
   ```
   `AppHost` を生成し `_windows` ベクターに追加

4. **AppHost コンストラクタ** (`src/cascadia/WindowsTerminal/AppHost.h:15`)
   ```cpp
   AppHost(WindowEmperor* manager, const winrt::TerminalApp::AppLogic& logic,
           winrt::TerminalApp::WindowRequestedArgs args) noexcept;
   ```
   `NonClientIslandWindow` または `IslandWindow` を作成し、XAMLコンテンツをホスト

5. **TermControl 初期化** → `ControlCore` が `Terminal` と `AtlasEngine` を生成

6. **ConptyConnection::Start** (`src/cascadia/TerminalConnection/ConptyConnection.h:23`) — ConPTY APIを使ってシェルプロセスを起動、パイプ接続

#### 例2: キー入力からシェルへの送信

**概要:** ユーザーが文字を入力してからシェルに到達するまで

**処理フロー:**
```
XAML KeyDown → TermControl → ControlInteractivity → ControlCore
  → Terminal::SendKeyEvent → TerminalInput → VTシーケンス生成
  → ConptyConnection::WriteInput → ConPTY パイプ → シェル
```

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイントを特定したか（`main.cpp:85` または `exemain.cpp:219`）
- [ ] 呼び出し関係を把握したか（WindowEmperor → AppHost → TermControl → Terminal）
- [ ] データの変換ポイントを確認したか（VTシーケンス ↔ テキスト操作）
- [ ] エラーハンドリングを確認したか（WILマクロ、safe_void_coroutine）
- [ ] 最終的な出力を確認したか（AtlasEngine による描画、ConPTY パイプ出力）

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `README.md` — プロジェクト概要、ビルド方法
2. `doc/` ディレクトリ — 設計仕様書群
3. `src/cascadia/` のディレクトリ構造を把握
4. `src/cascadia/WindowsTerminal/main.cpp` → `WindowEmperor.h` → `AppHost.h` を順に読む

#### 特定機能を理解したい場合
1. `doc/specs/` 内の対応する仕様書を検索
2. `src/cascadia/TerminalApp/` の対応するコンポーネントを読む
3. 対応する `.idl` ファイルでAPIインターフェースを確認
4. テストコード（`ut_*`ディレクトリ）で動作を理解

#### 改修作業を行う場合
1. `CONTRIBUTING.md` — コントリビューションガイドライン
2. 対象機能の仕様書（`doc/specs/`）
3. 変更対象のソースとそのテスト
4. `src/features.xml` — 機能フラグの確認
5. `.clang-format` — コードスタイル設定

#### 設定関連を理解したい場合
1. `src/cascadia/TerminalSettingsModel/defaults.json` — デフォルト設定
2. `doc/cascadia/profiles.schema.json` — 設定スキーマ
3. `src/cascadia/TerminalSettingsModel/CascadiaSettings.h` — 設定パースロジック
4. `src/cascadia/TerminalSettingsModel/IInheritable.h` — 継承メカニズム

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要・ビルド手順 | 初回参照 |
| `CONTRIBUTING.md` | コントリビューションルール | コード変更時 |
| `doc/specs/` | 機能仕様書群 | 機能理解時 |
| `doc/cascadia/profiles.schema.json` | 設定JSONスキーマ | 設定変更時 |
| `src/features.xml` | 機能フラグ一覧 | 機能ON/OFF確認時 |
| `.clang-format` | C++コードフォーマット設定 | コード記述時 |
| `SECURITY.md` | セキュリティポリシー | 脆弱性報告時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: `*.g.h` ファイルが見つからない
A: `*.g.h` はビルド時にC++/WinRTツール（cppwinrt.exe）が `.idl` ファイルから自動生成するヘッダーです。ビルドを一度実行するか、対応する `.idl` ファイルを参照してインターフェース定義を確認してください。

#### Q: `WINRT_PROPERTY` や `TYPED_EVENT` の展開後を見たい
A: これらはマクロです。定義は以下のファイルにあります:
- `WINRT_PROPERTY` — C++/WinRT標準マクロ（winrt/base.hに定義）
- `TYPED_EVENT` — `src/cascadia/inc/cppwinrt_utils.h:74`
- `RUNTIME_SETTING` — `src/cascadia/TerminalControl/ControlCore.h:43`

#### Q: `til::` 名前空間の型が分からない
A: `src/inc/til/` ディレクトリに全定義があります。`src/inc/til.h` がルートヘッダーで、各サブヘッダーをインクルードしています。

#### Q: VTシーケンスの処理箇所を知りたい
A: 以下の順序でコードを追ってください:
1. `src/terminal/parser/StateMachine.hpp` — パーサー（状態遷移）
2. `src/terminal/adapter/AdaptDispatch.hpp` — コマンドディスパッチ
3. `src/terminal/adapter/ITerminalApi.hpp` — 端末操作インターフェース

#### Q: 設定JSONの読み込み箇所を知りたい
A: `src/cascadia/TerminalSettingsModel/CascadiaSettings.h` の `CascadiaSettings` クラスがエントリーポイントです。`defaults.json`（組み込み）→ ユーザー `settings.json` → フラグメント拡張の順にマージされます。

### デバッグのヒント

- **TraceLogging**: プロジェクト全体でETW（Event Tracing for Windows）を使用しています。`g_hWindowsTerminalProvider` で登録されたイベントはWPR/WPAで収集可能です
- **WILのデバッグ**: `THROW_IF_*` マクロはデバッガ接続時にブレークポイントを自動設定します
- **`_assertIsMainThread()`**: `WindowEmperor.h:92-94` でUIスレッド外からのアクセスを検出します（Debugビルドのみ）
- **Feature Flags**: `src/features.xml` とビルド構成を確認し、対象機能が有効かどうかを確認してください

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| ConPTY | Windows Pseudo Console。従来のコンソールAPIとVT互換のパイプインターフェースを橋渡しする |
| conhost | Windows Console Host。従来のコマンドプロンプトウィンドウを提供するプログラム |
| VT / VT100 | Virtual Terminal。ANSI/VT100エスケープシーケンスによる端末制御プロトコル |
| WinRT | Windows Runtime。UWP/Desktop向けのコンポーネントモデル |
| C++/WinRT | WinRTをネイティブC++から使用するための投影技術 |
| XAML | Extensible Application Markup Language。UIを宣言的に記述するマークアップ |
| IDL | Interface Definition Language。WinRTインターフェースを定義する言語 |
| TIL | Terminal Implementation Library。プロジェクト内共通ユーティリティ |
| WIL | Windows Implementation Library。Microsoft製のC++ユーティリティライブラリ |
| CRTP | Curiously Recurring Template Pattern。テンプレート継承パターン |
| Atlas Engine | DirectX 11ベースの高速GPUテキストレンダリングエンジン |
| STA | Single-Threaded Apartment。COMのスレッドモデル |
| ETW | Event Tracing for Windows。Windowsの診断トレーシング基盤 |
| MSIX | Microsoftのアプリパッケージ形式 |
| Pane | ターミナルウィンドウ内の分割ビュー領域（二分木構造） |
| Tab | タブ。1つ以上のPaneを含むコンテナ |
| Quake Window | キー一押しで画面上部からスライドダウンするドロップダウン型ウィンドウ |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `src/cascadia/WindowsTerminal/main.cpp` | EXEエントリーポイント | `wWinMain`, 初期化処理 |
| `src/cascadia/WindowsTerminal/WindowEmperor.h` | プロセスレベルウィンドウ管理 | 複数ウィンドウ、ホットキー、通知アイコン |
| `src/cascadia/WindowsTerminal/AppHost.h` | 個別ウィンドウホスト | XAML Island、ウィンドウイベント処理 |
| `src/cascadia/TerminalApp/AppLogic.h` | アプリケーションロジック | 設定管理、ウィンドウ生成 |
| `src/cascadia/TerminalApp/TerminalPage.h` | メインUIページ | タブバー、コンテンツエリア |
| `src/cascadia/TerminalApp/Pane.h` | ペイン管理（二分木） | 分割、リサイズ、フォーカス |
| `src/cascadia/TerminalControl/TermControl.h` | XAMLターミナルコントロール | ユーザー入力、テキスト選択 |
| `src/cascadia/TerminalControl/ControlCore.h` | コントロールコア | Terminal + Renderer + Connection 統合 |
| `src/cascadia/TerminalCore/Terminal.hpp` | VTエミュレータ本体 | ITerminalApi, ITerminalInput, IRenderData実装 |
| `src/cascadia/TerminalSettingsModel/CascadiaSettings.h` | 設定コンテナ | JSON設定パース・プロファイル管理 |
| `src/cascadia/TerminalConnection/ConptyConnection.h` | ConPTY接続 | 子プロセス管理、I/O |
| `src/terminal/parser/StateMachine.hpp` | VTパーサー | 状態遷移ベースのシーケンスパース |
| `src/terminal/adapter/AdaptDispatch.hpp` | VTアダプター | VTコマンド → 端末操作変換 |
| `src/buffer/out/textBuffer.hpp` | テキストバッファ | 行管理、スクロールバック |
| `src/inc/til.h` | TILルートヘッダー | 共通ユーティリティのインクルード |
| `src/cascadia/inc/cppwinrt_utils.h` | WinRTユーティリティ | safe_void_coroutine, TYPED_EVENT |
| `src/features.xml` | 機能フラグ定義 | Dev/Canary/Release/Inbox別の有効/無効 |
| `OpenConsole.slnx` | ソリューション | ビルド構成、プロジェクト参照 |
| `vcpkg.json` | vcpkg依存関係 | fmt, ms-gsl, jsoncpp, cli11, cmark |

### C. 参考資料

- [Windows Terminal 公式ドキュメント](https://docs.microsoft.com/windows/terminal)
- [C++/WinRT ドキュメント](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/)
- [WIL (Windows Implementation Library)](https://github.com/microsoft/wil)
- [VT100 エスケープシーケンス仕様](https://vt100.net/)
- [Console API ドキュメント](https://github.com/MicrosoftDocs/Console-Docs)
- [Cascadia Code フォント](https://github.com/Microsoft/Cascadia-Code)
- [vcpkg パッケージマネージャー](https://github.com/microsoft/vcpkg)
