# 機能設計書 94-VTアダプター

## 概要

本ドキュメントは、Windows Terminal / Console Host における VTアダプター（AdaptDispatch）の機能設計を記述する。VTパーサーが解析したシーケンスをTerminal APIコールに変換する中間層の構造と動作を解説する。

### 本機能の処理概要

VTアダプターは、VTパーサーから受け取ったエスケープシーケンスの解析結果を、ITerminalApi インターフェースを通じてターミナルバッファの操作に変換するアダプターレイヤーである。AdaptDispatch クラスがITermDispatch インターフェースを実装し、100以上のVTコマンドに対応する。

**業務上の目的・背景**：VTパーサーが解析した抽象的なコマンド（「カーソルを上に3行移動」「画面をクリア」等）を、具体的なテキストバッファ操作やカーソル制御に変換する必要がある。AdaptDispatchはこの変換を担当し、VT規格の膨大なコマンドセットをサポートする。

**機能の利用シーン**：すべてのVTシーケンス処理の中間層として機能する。vim、tmux、git log --color等のCLIアプリケーションが出力するVTシーケンスが、この層を通じてターミナルの状態変更に変換される。

**主要な処理内容**：
1. カーソル制御（CUU/CUD/CUF/CUB/CUP等）
2. 画面消去（ED/EL/ECH等）
3. スクロール（SU/SD/IL/DL等）
4. 文字属性設定（SGR - 色、太字、下線等）
5. モード設定/リセット（SM/RM/DECSET/DECRST）
6. 文字セット切替（SCS/LS/SS等）
7. ウィンドウ操作（DTTERM Window Manipulation）
8. Sixel画像処理、ソフトフォント（DECDLD）、マクロ（DECDMAC）
9. 矩形領域操作（DECCRA/DECFRA/DECERA等）
10. レポート/クエリ応答（DSR/DA/DECRQM等）

**関連システム・外部連携**：ITerminalApi を通じてテキストバッファ、レンダラー、入力処理と連携する。PageManager によるページ管理、TerminalOutput による文字セット変換を使用する。

**権限による制御**：OptionalFeature 列挙体により、ClipboardWrite 等の機能を選択的に有効/無効化できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | VTシーケンスからTerminal APIへの変換 |

## 機能種別

データ変換処理 / コマンドディスパッチ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| api | ITerminalApi& | Yes | ターミナルAPI参照 | - |
| renderer | Renderer* | Yes | レンダラーポインタ | - |
| renderSettings | RenderSettings& | Yes | レンダリング設定 | - |
| terminalInput | TerminalInput& | Yes | ターミナル入力ハンドラ | - |

### 入力データソース

OutputStateMachineEngine からの ITermDispatch インターフェース呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| バッファ操作 | ITerminalApi経由 | テキストバッファへの書き込み、カーソル移動等 |
| レンダリング指示 | Renderer経由 | 画面更新のトリガー |
| 応答シーケンス | 文字列 | DSR等のクエリに対するVTシーケンス応答 |

### 出力先

ITerminalApi（テキストバッファ操作）、Renderer（描画指示）

## 処理フロー

### 処理シーケンス

```
1. VTパーサーからITermDispatchメソッド呼び出し
   └─ 例: CursorUp(3) - カーソルを3行上に移動
2. パラメータの検証と変換
   └─ VT座標系（1-origin）からバッファ座標系（0-origin）への変換
3. ITerminalApi経由でバッファ操作
   └─ GetBufferAndViewport()でバッファ取得、カーソル位置更新
4. レンダラーへの更新通知
   └─ 必要に応じてTriggerRedraw等を呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[ITermDispatch呼び出し] --> B{コマンド種別}
    B -->|カーソル制御| C[_CursorMovePosition]
    B -->|画面消去| D[_FillRect / EraseInDisplay]
    B -->|SGR| E[_ApplyGraphicsOptions]
    B -->|モード設定| F[_ModeParamsHelper]
    B -->|スクロール| G[_ScrollMovement]
    B -->|レポート| H[_DeviceStatusReport]
    C --> I[ITerminalApi::SetViewportPosition]
    D --> J[TextBuffer::FillRect]
    E --> K[TextAttribute更新]
    F --> L[モードフラグ更新]
    G --> M[_ScrollRectVertically]
    H --> N[ITerminalApi::ReturnResponse]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-01 | VT座標変換 | VTの1-origin座標をバッファの0-origin座標に変換 | カーソル位置操作 |
| BR-94-02 | スクロールマージン | DECSTBM/DECSLRMで設定されたマージン内でのスクロール | スクロール操作 |
| BR-94-03 | Origin Mode | DECOM有効時はカーソル移動がスクロールマージン内に制限 | カーソル移動時 |
| BR-94-04 | 代替バッファ | UseAlternateScreenBuffer時は別のCursorStateを使用 | DECSET 1049 |
| BR-94-05 | SGRスタック | XTPUSHSGR/XTPOPSGRによる属性の保存・復元 | SGR操作 |

### 計算ロジック

- VT座標からバッファ座標への変換: `Offset::Absolute(value)` は `{value - 1, true}` を返す
- SGR色処理: `_SetRgbColorsHelper` で256色/RGB色の解析、`_ApplyGraphicsOption` で属性適用

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 未知のモード | 警告 | 認識できないDECSET/DECRSTモード番号 | 無視して処理を継続 |
| 不正なパラメータ | 警告 | SGR等で無効な色指定 | デフォルト値を使用 |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- PrintString でテキストの一括書き込みを最適化（文字セット変換が不要な場合はバッチ処理）
- ページマネージャーによるページ切替の効率化

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

- OptionalFeature::ClipboardWrite によるクリップボード書き込みの制御
- OSCSetClipboard は OptionalFeature で有効化されている場合のみ動作

## 備考

- AdaptDispatch は100以上のVTコマンドをサポートする大規模クラス
- adaptDispatchGraphics.cpp にSGR関連の処理が分離されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ITermDispatch.hpp | `src/terminal/adapter/ITermDispatch.hpp` | VTコマンドのインターフェース定義 |
| 1-2 | ITerminalApi.hpp | `src/terminal/adapter/ITerminalApi.hpp` | ターミナルAPIインターフェース。BufferState構造体 |
| 1-3 | DispatchTypes.hpp | `src/terminal/adapter/DispatchTypes.hpp` | VTパラメータ型定義 |

**読解のコツ**: ITermDispatch は純粋仮想関数の集合であり、AdaptDispatch がこれを実装する。ITerminalApi は逆方向のインターフェースで、AdaptDispatch がターミナルを操作するために使用する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | adaptDispatch.hpp | `src/terminal/adapter/adaptDispatch.hpp` | AdaptDispatchクラス定義。CursorState, Offset, ChangeOps等の内部型 |

**主要処理フロー**:
1. **33-39行目**: AdaptDispatch クラス宣言。ITermDispatch継承
2. **193-205行目**: 内部Mode列挙体（InsertReplace, Origin, Column等）
3. **211-230行目**: CursorState構造体（カーソル位置・属性・文字セットの保存用）
4. **315行目**: OptionalFeature管理（ClipboardWrite）

#### Step 3: コマンド実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | adaptDispatch.cpp | `src/terminal/adapter/adaptDispatch.cpp` | メインのコマンド実装 |
| 3-2 | adaptDispatchGraphics.cpp | `src/terminal/adapter/adaptDispatchGraphics.cpp` | SGR（文字属性）処理の実装 |

**主要処理フロー**:
- **40-48行目**: コンストラクタ。API/Renderer/RenderSettings/TerminalInputの参照保持
- **57-68行目**: Print() - 文字セット変換後にバッファ書き込み
- **77-80行目以降**: PrintString() - 文字列の一括処理

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

```
OutputStateMachineEngine::ActionCsiDispatch()
    │
    └─ AdaptDispatch::{コマンドメソッド}()
           │
           ├─ _api.GetBufferAndViewport()     → バッファ・ビューポート取得
           ├─ _pages.ActivePage()             → アクティブページ取得
           ├─ _CursorMovePosition()           → カーソル移動
           │      └─ TextBuffer::GetCursor()  → カーソル位置更新
           ├─ _FillRect()                     → 矩形塗りつぶし
           │      └─ TextBuffer::FillRect()
           ├─ _ScrollRectVertically()         → 垂直スクロール
           │      └─ TextBuffer::ScrollRows()
           └─ _api.ReturnResponse()           → VT応答送信
```

### データフロー図

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

ITermDispatch       ───▶ AdaptDispatch             ───▶ ITerminalApi
(VTコマンド)               (座標変換・パラメータ処理)       (バッファ操作)
                           │                               │
VTParameters        ───▶ パラメータ解析             ───▶ TextBuffer
                           │                               (テキスト更新)
                           ├─ TerminalOutput               │
                           │   (文字セット変換)         ───▶ Renderer
                           └─ PageManager                   (画面更新通知)
                               (ページ管理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| adaptDispatch.hpp | `src/terminal/adapter/adaptDispatch.hpp` | ソース | AdaptDispatchクラス定義 |
| adaptDispatch.cpp | `src/terminal/adapter/adaptDispatch.cpp` | ソース | コマンド実装（メイン） |
| adaptDispatchGraphics.cpp | `src/terminal/adapter/adaptDispatchGraphics.cpp` | ソース | SGR関連処理 |
| ITermDispatch.hpp | `src/terminal/adapter/ITermDispatch.hpp` | ソース | VTコマンドインターフェース |
| termDispatch.hpp | `src/terminal/adapter/termDispatch.hpp` | ソース | ITermDispatchのデフォルト実装 |
| ITerminalApi.hpp | `src/terminal/adapter/ITerminalApi.hpp` | ソース | ターミナルAPIインターフェース |
| terminalOutput.hpp | `src/terminal/adapter/terminalOutput.hpp` | ソース | 文字セット変換 |
| terminalOutput.cpp | `src/terminal/adapter/terminalOutput.cpp` | ソース | 文字セット変換実装 |
| PageManager.hpp | `src/terminal/adapter/PageManager.hpp` | ソース | ページ管理 |
| PageManager.cpp | `src/terminal/adapter/PageManager.cpp` | ソース | ページ管理実装 |
| SixelParser.hpp | `src/terminal/adapter/SixelParser.hpp` | ソース | Sixel画像パーサー |
| FontBuffer.hpp | `src/terminal/adapter/FontBuffer.hpp` | ソース | ソフトフォントバッファ |
| MacroBuffer.hpp | `src/terminal/adapter/MacroBuffer.hpp` | ソース | マクロバッファ |
| charsets.hpp | `src/terminal/adapter/charsets.hpp` | ソース | 文字セット定義 |
| InteractDispatch.hpp | `src/terminal/adapter/InteractDispatch.hpp` | ソース | 対話型ディスパッチ |
| InteractDispatch.cpp | `src/terminal/adapter/InteractDispatch.cpp` | ソース | 対話型ディスパッチ実装 |
