# 画面設計書 14-インスペクターウィンドウ

## 概要

本ドキュメントは、Ghosttyアプリケーションのインスペクターウィンドウの設計仕様を定義する。インスペクターウィンドウは、ターミナルの内部状態を調査・デバッグするためのGTK専用開発者ツールであり、Dear ImGuiを使用してレンダリングされる。キーボードイベント、PTYデータストリーム、VTシーケンス、マウス状態、レンダラー情報などを可視化し、ターミナルアプリケーション開発者やGhostty自体のデバッグに活用できる。

### 本画面の処理概要

インスペクターウィンドウは、ターミナルの低レベル内部状態をリアルタイムで表示し、開発者がデバッグや問題調査を行うための画面である。

**業務上の目的・背景**：ターミナルエミュレータの開発やデバッグにおいて、エスケープシーケンスの解析、キーボード入力の追跡、PTYデータの監視が必要になる場面が多い。このインスペクターは、ターミナルアプリケーション開発者がアプリの挙動を確認したり、Ghostty自体の問題を調査したりするための強力なツールを提供する。デバッグビルドで使用することを前提としており、本番環境では通常無効化されている。

**画面へのアクセス方法**：
1. デバッグビルドのメニューから「Debug > Inspector」を選択
2. キーボードショートカット（設定による）でインスペクター表示をトグル
3. プログラムからactivateInspector()メソッドを呼び出し

**主要な操作・処理内容**：
1. キーボードイベントストリームの表示（最新50件まで保持）
2. PTYデータストリームの監視とVTシーケンスの解析
3. マウス状態（位置、ボタン、修飾キー）の表示
4. レンダラー情報の表示
5. ターミナルスクリーン状態の調査
6. ページリスト（履歴）の表示
7. Dear ImGuiのドッキング機能によるパネルレイアウトのカスタマイズ

**画面遷移**：
- 遷移元：メインターミナルウィンドウ（デバッグメニューまたはショートカットから）
- 遷移先：なし（独立ウィンドウとして動作、対象Surfaceがクローズされるとウィンドウも閉じる）

**権限による表示制御**：デバッグビルド（build_config.is_debug == true）の場合のみ完全機能が利用可能。リリースビルドでは表示が制限される可能性がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 75 | ターミナルインスペクター | 主機能 | ターミナル内部状態の調査・デバッグ表示 |

## 画面種別

独立ウィンドウ（デバッグツール）

## URL/ルーティング

GTKネイティブアプリケーションのため、URLルーティングは存在しない。InspectorWindow.new(surface)でウィンドウインスタンスを作成し、present()メソッドで表示する。

## 入出力項目

| 項目名 | 入出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| surface | 入力 | *Surface | Yes | 調査対象のターミナルサーフェス |

## 表示項目

| 項目名 | データ型 | ソース | 説明 |
|--------|----------|--------|------|
| ウィンドウタイトル | String | 固定値 | 「Ghostty: Terminal Inspector」 |
| デバッグ警告 | Widget | build_config.is_debug | デバッグビルドを示す警告表示 |
| キーイベントストリーム | Ring Buffer | Inspector.gui.key_stream | 最新50件のキーボードイベント |
| VTストリーム | Widget | Inspector.gui.vt_stream | PTYデータとVTシーケンス |
| マウス状態 | Struct | Inspector.mouse | カーソル位置、ボタン状態 |
| レンダラー情報 | Widget | Inspector.gui.renderer_info | GPUレンダリング状態 |
| スクリーン状態 | Widget | widgets.screen | ターミナルスクリーンバッファ |
| ページリスト | Widget | widgets.pagelist | 履歴ページ一覧 |

## イベント仕様

### 1-ウィンドウ作成

InspectorWindow.new(surface)が呼び出され、GObjectインスタンスが作成される。surfaceプロパティに対象Surfaceが設定される。

### 2-ウィンドウ表示

InspectorWindow.present()が呼び出され、gtk.Window.present()を実行してウィンドウをフォアグラウンドに表示する。

### 3-サーフェス変更通知（propInspectorSurface）

InspectorWidgetのsurfaceプロパティが変更されると、propInspectorSurface関数（160-171行目）が呼び出される。Surfaceがnullになった場合、ウィンドウを破棄する。

### 4-インスペクターレンダリング（imguiRender）

InspectorWidgetのimguiRender関数（85-93行目）が毎フレーム呼び出され、Inspector.render()を実行してDear ImGuiでUIを描画する。

### 5-レンダリングキュー（queueRender）

外部からqueueRender()が呼び出されると、ImguiWidgetにレンダリング要求を伝播し、次フレームでUIを再描画する。

### 6-ウィンドウクローズ

ウィンドウが閉じられる際、dispose関数でサーフェスのweakrefをクリアし、テンプレートをdisposeする。

### 7-サーフェスクローズ（surfaceWeakNotify）

対象Surfaceが破棄されると、InspectorWidgetのsurfaceWeakNotify（177-203行目）が呼び出され、インスペクターを非アクティブ化する。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | データベース操作なし（メモリ内状態表示のみ） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG-01 | 警告 | デバッグビルド警告 | build_config.is_debug == true の場合 |

## 例外処理

| 例外状態 | 画面の振る舞い |
|---------|---------------|
| Surfaceがnull | ウィンドウを自動破棄（propInspectorSurface） |
| インスペクター初期化失敗 | ログ出力してウィンドウを表示しない |
| core_surfaceがnull | レンダリングをスキップ |

## 備考

- GTK専用画面（macOSには対応するインスペクターは存在しない）
- Dear ImGui（cimgui）を使用してレンダリング
- ImguiWidgetを継承したInspectorWidgetを使用
- デフォルトウィンドウサイズは1000x600px
- ドッキング機能が有効化されており、パネルの再配置が可能
- sRGBカラースペースを使用
- 埋め込みフォント（font.embedded.regular）を使用
- キーイベントは最大50件のリングバッファで保持
- PTYデータストリームはリアルタイムで監視

---

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

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

### 推奨読解順序

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

Inspector構造体がインスペクターの状態を管理し、widgetsモジュールが各種デバッグ情報のUIを提供する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Inspector.zig | `src/inspector/Inspector.zig` | Inspector構造体（1-131行目）の全体構成、mouseとguiフィールド |

**読解のコツ**: Zigのimportとモジュール構造を理解すること。cimgui（Dear ImGui）のラッパーAPIを通じてUIを構築している。

#### Step 2: GTKウィンドウ層を理解する

InspectorWindowがGTKウィンドウとしてインスペクターをホストする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inspector_window.zig | `src/apprt/gtk/class/inspector_window.zig` | InspectorWindow構造体全体（1-217行目） |

**主要処理フロー**:
1. **82-93行目**: init関数でテンプレート初期化、デバッグビルドでCSSクラス追加
2. **95-112行目**: dispose関数でsurfaceをnull化、テンプレートdispose
3. **117-121行目**: new関数でインスタンス生成
4. **124-126行目**: present関数でウィンドウ表示
5. **160-171行目**: propInspectorSurfaceでsurfaceがnullになった時のウィンドウ破棄

#### Step 3: InspectorWidgetを理解する

InspectorWidgetがImguiWidgetを継承し、Dear ImGuiでUIをレンダリングする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | inspector_widget.zig | `src/apprt/gtk/class/inspector_widget.zig` | InspectorWidget構造体全体（1-246行目） |

**主要処理フロー**:
- **78-82行目**: imguiSetup - Inspector.setup()を呼び出してImGui初期化
- **85-93行目**: imguiRender - Inspector.render()を呼び出してUI描画
- **124-172行目**: setSurface - サーフェス設定とインスペクター有効化/無効化
- **177-203行目**: surfaceWeakNotify - サーフェス破棄時のクリーンアップ

#### Step 4: UIテンプレートを理解する

Blueprintテンプレートがウィンドウ構成を定義する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | inspector-window.blp | `src/apprt/gtk/ui/1.5/inspector-window.blp` | ウィンドウ構成（39行） |
| 4-2 | inspector-widget.blp | `src/apprt/gtk/ui/1.5/inspector-widget.blp` | ウィジェット構成（11行） |

**主要処理フロー**:
- **inspector-window.blp 4-8行目**: ウィンドウタイトル、アイコン、デフォルトサイズ
- **inspector-window.blp 14-36行目**: ToolbarViewでヘッダーバーとコンテンツを構成
- **inspector-window.blp 28-29行目**: GhosttyDebugWarningの条件表示
- **inspector-window.blp 32-35行目**: GhosttyInspectorWidgetのsurfaceバインディング

#### Step 5: Inspector内部実装を理解する

Inspectorがどのようにデータを収集・表示するかを理解する。

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

**主要処理フロー**:
- **25-56行目**: setup - ImGuiの初期設定（ドッキング有効化、sRGB、フォント設定）
- **58-62行目**: init - Inspector初期化
- **115-131行目**: render - UIの描画とレンダラースレッド通知

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

```
InspectorWindow (AdwApplicationWindow)
    │
    ├─ properties
    │      ├─ surface ─────────▶ InspectorWidget.surface
    │      └─ debug ───────────▶ GhosttyDebugWarning.visible
    │
    ├─ InspectorWidget (ImguiWidget)
    │      │
    │      ├─ imguiSetup() ────▶ Inspector.setup()
    │      │                          └─ cimgui.c.ImGui_GetIO()
    │      │                          └─ ConfigFlags設定
    │      │                          └─ フォント設定
    │      │
    │      ├─ imguiRender() ───▶ Inspector.render(surface)
    │      │                          └─ self.gui.draw()
    │      │                          └─ surface.renderer_thread.wakeup.notify()
    │      │
    │      └─ surfaceWeakNotify() ─▶ deactivateInspector()
    │
    └─ GhosttyDebugWarning
           └─ build_config.is_debug で表示制御
```

### データフロー図

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

Surface                       InspectorWidget                     ImGui Render
- core_surface      ───▶      - setSurface()        ───▶          - ウィンドウ描画
- inspector                   - activateInspector()               - パネル配置
                              - imguiRender()

Terminal Events               Inspector                           UI Widgets
- KeyEvent          ───▶      - recordKeyEvent()    ───▶          - key_stream表示
- PTY Data                    - recordPtyRead()                    - vt_stream表示
- Mouse State                 - render()                           - mouse表示

build_config                  InspectorWindow                     Debug Warning
- is_debug          ───▶      - debugプロパティ     ───▶          - 警告表示/非表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inspector_window.zig | `src/apprt/gtk/class/inspector_window.zig` | ソース | インスペクターウィンドウ |
| inspector_widget.zig | `src/apprt/gtk/class/inspector_widget.zig` | ソース | ImGuiウィジェット |
| inspector-window.blp | `src/apprt/gtk/ui/1.5/inspector-window.blp` | テンプレート | ウィンドウUI定義 |
| inspector-widget.blp | `src/apprt/gtk/ui/1.5/inspector-widget.blp` | テンプレート | ウィジェットUI定義 |
| Inspector.zig | `src/inspector/Inspector.zig` | ソース | インスペクターコア |
| main.zig | `src/inspector/main.zig` | ソース | インスペクターモジュール |
| widgets.zig | `src/inspector/widgets.zig` | ソース | UIウィジェット集約 |
| surface.zig | `src/inspector/widgets/surface.zig` | ソース | サーフェスインスペクター |
| screen.zig | `src/inspector/widgets/screen.zig` | ソース | スクリーンインスペクター |
| pagelist.zig | `src/inspector/widgets/pagelist.zig` | ソース | ページリストインスペクター |
| imgui_widget.zig | `src/apprt/gtk/class/imgui_widget.zig` | ソース | ImGui GTKウィジェット基底 |
| debug_warning.zig | `src/apprt/gtk/class/debug_warning.zig` | ソース | デバッグ警告ウィジェット |
| surface.zig | `src/apprt/gtk/class/surface.zig` | ソース | Surfaceウィジェット |
