# 機能設計書 75-ターミナルインスペクター

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるターミナルインスペクター機能の設計について記載する。この機能は端末の内部状態をリアルタイムで可視化・デバッグするための開発者向けツールであり、ターミナルアプリケーション開発者やGhostty自体のデバッグに有用である。

### 本機能の処理概要

**業務上の目的・背景**：
ターミナルエミュレータは複雑な状態を持つソフトウェアであり、エスケープシーケンスの解釈、カーソル位置、モード設定、カラーパレット、マウス状態など多くの内部状態が存在する。インスペクターはこれらの状態をリアルタイムで表示し、端末アプリケーション開発者が問題をデバッグしたり、Ghosttyの動作を確認したりするのに役立つ。

**機能の利用シーン**：
- ターミナルアプリケーションのデバッグ
- エスケープシーケンスの動作確認
- Ghostty自体の開発・デバッグ
- 端末状態の学習・理解

**主要な処理内容**：
1. インスペクターウィンドウの表示/非表示切り替え
2. 端末状態（Terminal Info）の表示
3. キーボードイベントストリームの表示
4. PTY入出力（Terminal IO）の表示
5. レンダラー情報の表示
6. サーフェス情報の表示

**関連システム・外部連携**：
- ImGui（Dear ImGui）: UIレンダリングライブラリ
- dcimgui: ImGuiのZigバインディング
- Metalレンダラー / OpenGLレンダラー: インスペクターUIの描画

**権限による制御**：
- 特に権限制御は不要（開発者向け機能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | インスペクターウィンドウ | 主画面 | 端末状態のデバッグ・インスペクション表示 |
| 1 | メインターミナルウィンドウ | 参照画面 | インスペクター起動元 |

## 機能種別

デバッグ / 状態表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mode | InspectorMode | Yes | toggle/show/hide | enum値のみ |

### 入力データソース

- キーバインド`inspector`アクション
- 端末状態（Terminal構造体）
- キーボードイベント
- PTYデータストリーム
- レンダラー状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Terminal Info | 表示 | 端末モード、カーソル位置、カラー等 |
| Surface Info | 表示 | サーフェス状態、マウス位置 |
| Keyboard Stream | 表示 | キーイベント履歴 |
| Terminal IO | 表示 | VTシーケンス解析結果 |
| Renderer Info | 表示 | レンダラー統計情報 |

### 出力先

- インスペクターウィンドウ（オーバーレイまたは別ウィンドウ）

## 処理フロー

### 処理シーケンス

```
1. inspectorアクション受付
   └─ mode: toggle/show/hide
2. Inspector構造体の初期化または状態変更
   └─ ImGuiコンテキストのセットアップ
3. 定期的なレンダリング
   └─ 端末状態のミューテックスを取得
4. 各ウィジェットの描画
   └─ Terminal Info, Surface Info, Keyboard, Terminal IO, Renderer
5. レンダラーへの描画要求
   └─ ImGuiの描画コマンドを処理
```

### フローチャート

```mermaid
flowchart TD
    A[inspector アクション] --> B{mode?}
    B -->|toggle| C{現在表示中?}
    B -->|show| D[表示開始]
    B -->|hide| E[非表示]
    C -->|Yes| E
    C -->|No| D
    D --> F[Inspector.init]
    F --> G[ImGui セットアップ]
    G --> H[レンダリングループ]
    H --> I[mutex.lock]
    I --> J[各ウィジェット描画]
    J --> K[mutex.unlock]
    K --> L[描画要求]
    L --> H
    E --> M[Inspector.deinit]
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-1 | ドッキング対応 | ImGuiDockingを使用してウィンドウ配置を柔軟に | 常時 |
| BR-75-2 | ミューテックス必須 | 端末状態へのアクセスはrenderer_state.mutex保持時のみ | 状態参照時 |
| BR-75-3 | キーイベント履歴 | 最大50件のキーイベントを保持 | 常時 |
| BR-75-4 | sRGB色空間 | ImGuiはsRGB色空間で動作 | 常時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OutOfMemory | メモリ不足 | キーイベントリング拡張時 | 古いイベントを削除 |
| - | 初期化失敗 | ImGuiセットアップ失敗 | エラーログ出力 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- インスペクター表示中はCPU/GPU負荷が増加する（開発ツールとして許容）
- renderer_state.mutexのロック時間を最小化
- 端末状態変更時は常にリドローをトリガー

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

- インスペクターは端末の内部状態を完全に公開するため、開発用途のみを想定
- 本番環境での使用は推奨しない

## 備考

- デバッグビルドではImGuiデモウィンドウも表示される
- レイアウト設定は保存されない（IniFilename = null）
- 埋め込みフォント（JetBrains Mono相当）を使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Inspector.zig | `src/inspector/Inspector.zig` | Inspector構造体の定義 |
| 1-2 | main.zig | `src/inspector/main.zig` | モジュールエクスポート |
| 1-3 | widgets.zig | `src/inspector/widgets.zig` | ウィジェット定義のエクスポート |

**読解のコツ**: InspectorはImGuiベースのUIで、各種ウィジェット（terminal, surface, key, termio, renderer）で構成される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Inspector.zig | `src/inspector/Inspector.zig` | init/deinit/render関数 |

**主要処理フロー**:
1. **25-56行目**: setup関数 - ImGuiの初期設定
2. **58-62行目**: init関数 - Inspector構造体の初期化
3. **114-131行目**: render関数 - フレーム描画

#### Step 3: ウィジェット実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | surface.zig | `src/inspector/widgets/surface.zig` | Inspectorウィジェット（メインUI） |
| 3-2 | terminal.zig | `src/inspector/widgets/terminal.zig` | Terminal Info ウィジェット |
| 3-3 | key.zig | `src/inspector/widgets/key.zig` | Keyboard Streamウィジェット |
| 3-4 | termio.zig | `src/inspector/widgets/termio.zig` | Terminal IOウィジェット |
| 3-5 | renderer.zig | `src/inspector/widgets/renderer.zig` | Renderer Infoウィジェット |

**主要処理フロー**:
- **surface.zig 47-131行目**: draw関数 - ドッキングスペース作成と各ウィジェットの描画

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

```
inspector アクション (Surface.zig)
    │
    └─ inspector フィールド操作
           │
           ├─ Inspector.init()
           │      └─ widgets.surface.Inspector.init()
           │
           └─ Inspector.render()
                  │
                  └─ gui.draw()
                         │
                         ├─ terminal_info.draw() - Terminal Info
                         │
                         ├─ surface_info.draw() - Surface Info
                         │
                         ├─ key_stream.draw() - Keyboard
                         │
                         ├─ vt_stream.draw() - Terminal IO
                         │
                         └─ renderer_info.draw() - Renderer
```

### データフロー図

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

キーバインド ───▶ inspector アクション
                        │
                        ▼
                   Inspector 初期化
                        │
              ┌─────────┴─────────┐
              │                   │
         Terminal           PTY データ
         状態               ストリーム
              │                   │
              ▼                   ▼
    ┌─────────────────────────────────┐
    │         Inspector GUI           │
    ├─────────────────────────────────┤
    │ Terminal Info | Surface Info    │
    │ Keyboard      | Terminal IO     │
    │ Renderer                        │
    └─────────────────────────────────┘
                        │
                        ▼
               インスペクター ウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Inspector.zig | `src/inspector/Inspector.zig` | ソース | メインInspector実装 |
| main.zig | `src/inspector/main.zig` | ソース | モジュールエントリ |
| widgets.zig | `src/inspector/widgets.zig` | ソース | ウィジェット集約 |
| surface.zig | `src/inspector/widgets/surface.zig` | ソース | Inspectorウィジェット |
| terminal.zig | `src/inspector/widgets/terminal.zig` | ソース | Terminal Infoウィジェット |
| key.zig | `src/inspector/widgets/key.zig` | ソース | Keyboard Streamウィジェット |
| termio.zig | `src/inspector/widgets/termio.zig` | ソース | Terminal IOウィジェット |
| renderer.zig | `src/inspector/widgets/renderer.zig` | ソース | Renderer Infoウィジェット |
| screen.zig | `src/inspector/widgets/screen.zig` | ソース | Screen詳細ウィジェット |
| page.zig | `src/inspector/widgets/page.zig` | ソース | Pageウィジェット |
| pagelist.zig | `src/inspector/widgets/pagelist.zig` | ソース | PageListウィジェット |
| style.zig | `src/inspector/widgets/style.zig` | ソース | スタイル表示 |
| units.zig | `src/inspector/units.zig` | ソース | 単位変換ユーティリティ |
| Binding.zig | `src/input/Binding.zig` | ソース | inspectorアクション定義 |
