# 機能設計書 93-VT (Virtual Terminal) パーサー

## 概要

本ドキュメントは、Windows Terminal / Console Host における VT (Virtual Terminal) エスケープシーケンスの解析処理（VTパーサー）の機能設計を記述する。StateMachineクラスを中心とした状態遷移ベースの解析エンジンの構造と動作を解説する。

### 本機能の処理概要

VTパーサーは、ANSI/VTエスケープシーケンス（ESC, CSI, OSC, DCS, SS3等）を解析する有限状態機械（Finite State Machine）である。入力されるバイトストリームを文字単位で処理し、対応するアクション（画面制御、カーソル移動、色設定等）をディスパッチエンジンに委譲する。

**業務上の目的・背景**：ターミナルエミュレータの根幹をなす機能であり、あらゆるVTシーケンス（カーソル制御、画面消去、色設定、ウィンドウ操作等）の解析を担当する。VT100/VT220/xterm等の標準に準拠し、現代のCLIアプリケーション（vim, tmux, htop等）が正常に動作するための基盤となる。

**機能の利用シーン**：シェルやCLIアプリケーションがVTシーケンスを出力するたびに呼び出される。出力パーサー（OutputStateMachineEngine）と入力パーサー（InputStateMachineEngine）の2種類が存在し、それぞれ出力ストリーム解析と入力ストリーム解析を担当する。

**主要な処理内容**：
1. 文字ストリームの状態遷移ベース解析（19種類の状態）
2. CSIシーケンスのパラメータ・サブパラメータ解析（最大32パラメータ、各最大6サブパラメータ）
3. OSCシーケンスのパラメータとペイロード解析
4. DCSシーケンスのパススルー処理
5. VT52互換モード対応
6. C0/C1制御コードの処理
7. ConPTY用のインジェクションポイント管理

**関連システム・外部連携**：IStateMachineEngine インターフェースを通じてOutputStateMachineEngine/InputStateMachineEngineにアクションをディスパッチする。ConPTY経由でのシーケンスインジェクション機能を持つ。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | VTシーケンスの解析によるターミナル表示制御 |

## 機能種別

データ解析処理 / 状態機械

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| wch | wchar_t | Yes | 処理する文字 | - |
| string | std::wstring_view | Yes | 処理する文字列 | - |
| engine | unique_ptr\<IStateMachineEngine\> | Yes | ディスパッチエンジン | NULLでないこと |
| isEngineForInput | bool | Yes | 入力用エンジンかどうか | - |

### 入力データソース

- ConPTY接続またはConsole Hostからの出力ストリーム
- ターミナル入力ストリーム

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| アクション呼び出し | IStateMachineEngine経由 | 解析されたシーケンスに対応するアクション |
| injections | til::small_vector\<Injection, 8\> | ConPTY用インジェクションポイント |

### 出力先

IStateMachineEngine（OutputStateMachineEngine または InputStateMachineEngine）

## 処理フロー

### 処理シーケンス

```
1. ProcessString() - 文字列の処理開始
   └─ 文字列の各文字に対してProcessCharacter()を呼び出し
2. ProcessCharacter() - 1文字の処理
   └─ 現在の状態に対応する_Event*メソッドを呼び出し
3. _Event*(wch) - 状態別イベントハンドラ
   └─ 文字の種類に応じて状態遷移またはアクション実行
4. _Action*(wch) - アクション実行
   └─ IStateMachineEngineの対応メソッドを呼び出し
5. _Enter*() - 状態遷移
   └─ 新しい状態への遷移処理
```

### フローチャート

```mermaid
flowchart TD
    A[ProcessString/ProcessCharacter] --> B{現在の状態}
    B -->|Ground| C[_EventGround]
    B -->|Escape| D[_EventEscape]
    B -->|CsiEntry| E[_EventCsiEntry]
    B -->|CsiParam| F[_EventCsiParam]
    B -->|OscParam| G[_EventOscParam]
    B -->|OscString| H[_EventOscString]
    B -->|DcsPassThrough| I[_EventDcsPassThrough]
    B -->|Other| J[対応するイベントハンドラ]
    C --> K{文字種別}
    K -->|印刷可能| L[_ActionPrint]
    K -->|ESC| M[_EnterEscape]
    K -->|C0制御| N[_ActionExecute]
    K -->|C1制御| O[対応状態へ遷移]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-93-01 | パラメータ上限 | パラメータ値の最大値は65535 | CSI/DCSシーケンス |
| BR-93-02 | パラメータ数上限 | 最大32個のパラメータをサポート | CSI/DCSシーケンス |
| BR-93-03 | サブパラメータ上限 | 各パラメータに最大6個のサブパラメータ | CSIシーケンス |
| BR-93-04 | C1制御コード受理 | 入力エンジンでは常にC1制御コードを受理 | isEngineForInput=true |
| BR-93-05 | 割り込み処理 | Ground以外の状態でC0/C1制御コードを受信した場合、現在のシーケンスを中断して処理 | 常時 |

### 計算ロジック

- パラメータ値の蓄積: `_AccumulateTo(wch, value)` で `value = value * 10 + (wch - L'0')` を計算し、MAX_PARAMETER_VALUE(65535)でクランプ
- VTID の構築: _identifier (VTIDBuilder) が中間文字と最終文字を組み合わせてシーケンスIDを構築

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| パラメータオーバーフロー | 解析エラー | パラメータ数が上限を超過 | _parameterLimitOverflowed フラグを設定し、超過分を無視 |
| 不正なシーケンス | 解析エラー | 認識できない中間文字・最終文字 | _ActionIgnore() で無視し、Ground状態に遷移 |

### リトライ仕様

リトライは行わない。不正なシーケンスは無視してGround状態にリセットする。

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

該当なし。

## パフォーマンス要件

- _CurrentRun() は遅延評価（lazy construction）で文字列ビューを構築し、大量テキスト処理時のパフォーマンスを最適化
- _runOffset/_runSize によるゼロコピー文字列処理

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

- パラメータ値の上限チェック（MAX_PARAMETER_VALUE = 65535）によるオーバーフロー防止
- ファジングテスト（ft_fuzzer/ft_fuzzwrapper）が用意されており、不正入力に対する堅牢性を検証

## 備考

- VT100.netの仕様書に基づいた設計（stateMachine.hppのコメントに記載）
- GH#12977: win32-input-mode対応のためMAX_PARAMETER_VALUEを65535に設定

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IStateMachineEngine.hpp | `src/terminal/parser/IStateMachineEngine.hpp` | エンジンインターフェース。ActionExecute/ActionPrint/ActionCsiDispatch等のメソッド |
| 1-2 | DispatchTypes.hpp | `src/terminal/adapter/DispatchTypes.hpp` | VTパラメータ型（VTInt, VTParameter, VTID等）の定義 |
| 1-3 | stateMachine.hpp | `src/terminal/parser/stateMachine.hpp` | StateMachineクラス定義。VTStates列挙体（19状態）、パラメータ格納構造 |

**読解のコツ**: VTStates列挙体の19状態はVT100.netの状態遷移図と対応している。Ground状態が基本状態で、ESCを受信するとEscape状態に遷移する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | stateMachine.cpp | `src/terminal/parser/stateMachine.cpp` | ProcessString/ProcessCharacterからの状態遷移処理 |

**主要処理フロー**:
1. **14-32行目**: コンストラクタ。エンジン所有権取得、入力エンジンの場合はC1受理を有効化
2. **60-63行目**: _isNumericParamValue - パラメータ値の数字判定
3. **76-81行目**: _isC0Code - C0制御コード判定

#### Step 3: 出力エンジンの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | OutputStateMachineEngine.hpp | `src/terminal/parser/OutputStateMachineEngine.hpp` | 出力用エンジン。CSI/ESC/OSC/DCSのアクションコード定義 |
| 3-2 | OutputStateMachineEngine.cpp | `src/terminal/parser/OutputStateMachineEngine.cpp` | アクションの具体的なディスパッチ実装 |

#### Step 4: 入力エンジンの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | InputStateMachineEngine.hpp | `src/terminal/parser/InputStateMachineEngine.hpp` | 入力用エンジン。VTモディファイア定数、DeviceAttribute列挙体 |
| 4-2 | InputStateMachineEngine.cpp | `src/terminal/parser/InputStateMachineEngine.cpp` | 入力シーケンスからINPUT_RECORDへの変換 |

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

```
StateMachine::ProcessString()
    │
    ├─ ProcessCharacter(wch)
    │      │
    │      ├─ _EventGround(wch)
    │      │      ├─ _ActionPrint(wch)        → Engine::ActionPrint()
    │      │      ├─ _ActionExecute(wch)      → Engine::ActionExecute()
    │      │      └─ _EnterEscape()           → 状態遷移
    │      │
    │      ├─ _EventEscape(wch)
    │      │      ├─ _ActionEscDispatch(wch)  → Engine::ActionEscDispatch()
    │      │      ├─ _EnterCsiEntry()         → 状態遷移
    │      │      ├─ _EnterOscParam()         → 状態遷移
    │      │      └─ _EnterDcsEntry()         → 状態遷移
    │      │
    │      ├─ _EventCsiParam(wch)
    │      │      ├─ _ActionParam(wch)        → パラメータ蓄積
    │      │      └─ _ActionCsiDispatch(wch)  → Engine::ActionCsiDispatch()
    │      │
    │      ├─ _EventOscString(wch)
    │      │      └─ _ActionOscDispatch()     → Engine::ActionOscDispatch()
    │      │
    │      └─ _EventDcsPassThrough(wch)
    │             └─ _dcsStringHandler(wch)   → DCS文字列ハンドラ
    │
    └─ _ActionPrintString(string)             → Engine::ActionPrintString()
```

### データフロー図

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

バイトストリーム     ───▶ StateMachine              ───▶ IStateMachineEngine
(VTシーケンス含む)         (状態遷移解析)                  (アクションディスパッチ)
                           │                               │
                           ├─ パラメータ解析                ├─ OutputStateMachineEngine
                           ├─ VTID構築                     │    └─ ITermDispatch (画面制御)
                           └─ 状態管理                     └─ InputStateMachineEngine
                                                                └─ IInteractDispatch (入力制御)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stateMachine.hpp | `src/terminal/parser/stateMachine.hpp` | ソース | StateMachineクラス定義 |
| stateMachine.cpp | `src/terminal/parser/stateMachine.cpp` | ソース | 状態遷移処理の実装 |
| IStateMachineEngine.hpp | `src/terminal/parser/IStateMachineEngine.hpp` | ソース | エンジンインターフェース |
| OutputStateMachineEngine.hpp | `src/terminal/parser/OutputStateMachineEngine.hpp` | ソース | 出力エンジンのアクションコード定義 |
| OutputStateMachineEngine.cpp | `src/terminal/parser/OutputStateMachineEngine.cpp` | ソース | 出力エンジンの実装 |
| InputStateMachineEngine.hpp | `src/terminal/parser/InputStateMachineEngine.hpp` | ソース | 入力エンジンのアクションコード定義 |
| InputStateMachineEngine.cpp | `src/terminal/parser/InputStateMachineEngine.cpp` | ソース | 入力エンジンの実装 |
| tracing.hpp | `src/terminal/parser/tracing.hpp` | ソース | パーサートレーシング |
| tracing.cpp | `src/terminal/parser/tracing.cpp` | ソース | トレーシング実装 |
| ascii.hpp | `src/terminal/parser/ascii.hpp` | ソース | ASCII文字定数 |
| base64.hpp | `src/terminal/parser/base64.hpp` | ソース | Base64エンコード/デコード |
| base64.cpp | `src/terminal/parser/base64.cpp` | ソース | Base64実装 |
| DispatchTypes.hpp | `src/terminal/adapter/DispatchTypes.hpp` | ソース | VTパラメータ型定義 |
