# 機能設計書 1-端末エミュレーション

## 概要

本ドキュメントは、GhosttyターミナルエミュレータにおけるANSIエスケープシーケンスとxterm互換の端末制御コードを解釈し、端末として動作する「端末エミュレーション」機能の設計を記述する。

### 本機能の処理概要

端末エミュレーション機能は、Ghosttyの中核をなす機能であり、PTY（擬似端末）から受信したバイトストリームを解析し、画面への文字表示、カーソル移動、画面制御などの端末操作を実行する。

**業務上の目的・背景**：ターミナルエミュレータの本質的な役割は、シェルやCLIアプリケーションからの出力を正しく解釈し、ユーザーに視覚的なフィードバックを提供することである。ECMA-48規格およびxterm互換性を実現することで、既存のCLIツール、シェルスクリプト、TUIアプリケーションとの幅広い互換性を確保する。

**機能の利用シーン**：
- ユーザーがシェルコマンドを実行し、その結果が画面に表示される場面
- vim、htop、tmux等のTUIアプリケーションが画面を制御する場面
- カラー出力やスタイル付きテキストを表示する場面
- シェルプロンプトやコマンド出力のフォーマットが適用される場面

**主要な処理内容**：
1. PTYからのバイトストリーム受信とUTF-8デコード
2. VTパーサーによる制御シーケンス（CSI、OSC、DCS、APC等）の解析
3. 端末状態の更新（カーソル位置、スクロール領域、文字属性等）
4. 画面バッファ（Screen）への文字書き込み
5. モード管理（挿入モード、アプリケーションカーソルモード等）
6. マウスイベントモードの管理

**関連システム・外部連携**：
- PTY管理サブシステム（POSIXpty/WindowsPty）との連携
- レンダラーサブシステム（Metal/OpenGL）への描画要求
- シェル統合機能（OSC 133によるセマンティックプロンプト）

**権限による制御**：特になし。端末エミュレーションは全ユーザーに対して同一の動作を提供する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | ANSIエスケープシーケンスの解釈、端末としての動作を提供 |
| 2 | クイックターミナル | 主画面 | ANSIエスケープシーケンスの解釈、端末としての動作を提供 |
| 3 | スプリットビュー | 主画面 | 分割された各ペインでの端末エミュレーション |

## 機能種別

データ処理 / 状態管理 / 画面制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| byte_stream | []const u8 | Yes | PTYから受信したバイトストリーム | UTF-8として有効であること |
| cols | size.CellCountInt | Yes | 端末の列数 | 1以上の正の整数 |
| rows | size.CellCountInt | Yes | 端末の行数 | 1以上の正の整数 |
| max_scrollback | usize | No | スクロールバック最大行数 | デフォルト10,000行 |

### 入力データソース

- PTY（擬似端末）からのバイトストリーム
- 設定ファイルからの初期端末サイズ、スクロールバック設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| screen_buffer | Screen | 現在の画面状態を保持するバッファ |
| cursor_position | Cursor | カーソルの現在位置とスタイル |
| terminal_modes | ModeState | 端末のモード状態 |
| scrollback_buffer | PageList | スクロールバック履歴 |

### 出力先

- 画面バッファ（Screen構造体）
- レンダラーへの描画要求

## 処理フロー

### 処理シーケンス

```
1. バイトストリーム受信
   └─ PTYからのデータをUTF-8Decoderで処理

2. VTパーサーによる解析
   └─ Parser.next()で各バイトを状態機械で処理
   └─ Action（print, execute, csi_dispatch等）を生成

3. アクション実行
   └─ print: 文字をScreenに書き込み
   └─ execute: C0/C1制御文字の実行
   └─ csi_dispatch: CSIコマンドの実行
   └─ osc_dispatch: OSCコマンドの実行

4. 画面状態更新
   └─ カーソル位置の更新
   └─ スクロール処理
   └─ 文字属性の適用

5. レンダラーへの通知
   └─ dirty フラグの設定
```

### フローチャート

```mermaid
flowchart TD
    A[PTYからバイト受信] --> B[UTF-8デコード]
    B --> C[VTパーサー処理]
    C --> D{アクションタイプ}
    D -->|print| E[文字描画]
    D -->|execute| F[制御文字実行]
    D -->|csi_dispatch| G[CSIコマンド実行]
    D -->|osc_dispatch| H[OSCコマンド実行]
    D -->|esc_dispatch| I[ESCコマンド実行]
    E --> J[画面バッファ更新]
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[dirtyフラグ設定]
    K --> L[レンダラーに通知]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ECMA-48準拠 | 端末制御シーケンスはECMA-48規格に準拠する | すべての制御シーケンス処理時 |
| BR-002 | xterm互換 | xterm互換の拡張シーケンスをサポートする | CSI、OSC、DCSコマンド処理時 |
| BR-003 | 代替画面切り替え | SMCUPでメイン画面から代替画面に切り替え | アプリケーションが代替画面を要求時 |
| BR-004 | スクロール領域制限 | スクロールはscrolling_region内に制限される | スクロール操作時 |

### 計算ロジック

- スクロール領域: `scrolling_region.top` から `scrolling_region.bottom` の範囲
- カーソル位置: (x, y) で 0-indexed、範囲は (0..cols-1, 0..rows-1)

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

本機能はデータベースを使用しない。端末状態はメモリ内のデータ構造で管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-001 | メモリ不足 | PageList拡張時のメモリ確保失敗 | 古いスクロールバックを解放して再試行 |
| E-002 | 不正なシーケンス | 未知のCSI/OSCコマンド | 無視して処理を継続 |
| E-003 | UTF-8デコードエラー | 不正なUTF-8バイト列 | 置換文字で代替 |

### リトライ仕様

メモリ不足時は古いスクロールバックページを解放してリトライする。

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

端末エミュレーションはトランザクション処理を使用しない。各入力は即座に処理される。

## パフォーマンス要件

- 入力処理レイテンシ: 1ms以下
- スループット: 1GB/s以上のバイトストリーム処理
- メモリ効率: PageListによる効率的なメモリプール管理

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

- OSC 52（クリップボード操作）は設定で制限可能
- セキュア入力モード（パスワード入力時）のサポート
- 悪意のある制御シーケンスによるDoS攻撃への対策

## 備考

- Kitty拡張プロトコル（キーボード、グラフィックス）にも対応
- シェル統合機能（OSC 133）によるセマンティックプロンプトのサポート

---

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

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

### 推奨読解順序

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

端末エミュレーションの中核となるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Terminal.zig | `src/terminal/Terminal.zig` | Terminal構造体の定義、screens、tabstops、scrolling_region等のフィールド |
| 1-2 | Screen.zig | `src/terminal/Screen.zig` | Screen構造体、Cursor、PageListとの関連 |
| 1-3 | page.zig | `src/terminal/page.zig` | Page、Row、Cell構造体の定義 |

**読解のコツ**: Zigでは`@This()`で現在の構造体型を取得する。`pub const`で定義された型は外部からアクセス可能。

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

端末への入力処理の起点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Terminal.zig | `src/terminal/Terminal.zig` | init()関数、vtStream()メソッド |
| 2-2 | stream.zig | `src/terminal/stream.zig` | Stream構造体、バイトストリームの処理 |

**主要処理フロー**:
1. **218-251行目**: `Terminal.init()` - Terminal構造体の初期化
2. **264-271行目**: `vtStream()`/`vtHandler()` - VTストリームハンドラの取得
3. **278-292行目**: `printString()` - UTF-8文字列の出力処理

#### Step 3: VTパーサーを理解する

制御シーケンスの解析ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Parser.zig | `src/terminal/Parser.zig` | State enum、Action union、next()メソッド |
| 3-2 | parse_table.zig | `src/terminal/parse_table.zig` | 状態遷移テーブルの定義 |

**主要処理フロー**:
- **14-30行目**: `State` enum - パーサーの状態定義（ground, escape, csi_entry等）
- **51-185行目**: `Action` union - パーサーが生成するアクション型
- **248-300行目**: `next()` - 1バイトを処理して次のアクションを返す

#### Step 4: CSI/OSCコマンド処理を理解する

具体的なコマンド実行ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | csi.zig | `src/terminal/csi.zig` | CSIコマンドの定義と処理 |
| 4-2 | osc.zig | `src/terminal/osc.zig` | OSCコマンドの定義と処理 |
| 4-3 | ansi.zig | `src/terminal/ansi.zig` | ANSI関連の定数と型定義 |

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

```
Terminal
    |
    +-- init()
    |      |
    |      +-- ScreenSet.init()
    |      |      +-- Screen.init()
    |      |             +-- PageList.init()
    |      |
    |      +-- Tabstops.init()
    |
    +-- vtStream() / vtHandler()
    |      |
    |      +-- ReadonlyStream.init()
    |             +-- Parser処理
    |                    +-- Action生成
    |
    +-- print() / printString()
    |      |
    |      +-- Screen.write()
    |             +-- Page.setCell()
    |
    +-- linefeed() / carriageReturn()
           |
           +-- Screen.scroll()
```

### データフロー図

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

PTYバイトストリーム ──> UTF8Decoder ──> Parser ──> Action
                                                      |
                                                      v
                              Terminal.execute() <── Action.print
                              Terminal.csiDispatch() <── Action.csi_dispatch
                              Terminal.oscDispatch() <── Action.osc_dispatch
                                      |
                                      v
                              Screen (PageList)
                                      |
                                      v
                              Renderer (Metal/OpenGL)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | 端末エミュレーションのメインロジック |
| Parser.zig | `src/terminal/Parser.zig` | ソース | VT制御シーケンスパーサー |
| Screen.zig | `src/terminal/Screen.zig` | ソース | 画面バッファ管理 |
| PageList.zig | `src/terminal/PageList.zig` | ソース | ページリスト（スクロールバック含む）管理 |
| page.zig | `src/terminal/page.zig` | ソース | ページ、行、セルのデータ構造 |
| csi.zig | `src/terminal/csi.zig` | ソース | CSIコマンド定義 |
| osc.zig | `src/terminal/osc.zig` | ソース | OSCコマンド定義 |
| ansi.zig | `src/terminal/ansi.zig` | ソース | ANSI関連定数 |
| modes.zig | `src/terminal/modes.zig` | ソース | 端末モード管理 |
| UTF8Decoder.zig | `src/terminal/UTF8Decoder.zig` | ソース | UTF-8デコード処理 |
| stream.zig | `src/terminal/stream.zig` | ソース | バイトストリーム処理 |
| charsets.zig | `src/terminal/charsets.zig` | ソース | 文字セット定義 |
