# 画面設計書 1-メインターミナルウィンドウ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータのメインターミナルウィンドウの画面設計について記載する。メインターミナルウィンドウはGhosttyの中核となる画面であり、ターミナルエミュレーションの主要な機能を提供する。

### 本画面の処理概要

メインターミナルウィンドウは、Ghosttyアプリケーションの主要な操作画面であり、ユーザーがコマンドラインインターフェースを通じてシステムと対話するための機能を提供する。

**業務上の目的・背景**：ターミナルエミュレータとしてユーザーがシェルコマンドを実行し、システム管理やソフトウェア開発などの作業を行うための基盤を提供する。高速なGPUレンダリングと豊富な機能（スプリット、タブ、カラー表示など）により、効率的な作業環境を実現する。

**画面へのアクセス方法**：
- アプリケーション起動時に自動的に表示される
- メニューバーから「File > New Window」を選択
- キーボードショートカット（Cmd+N）で新規ウィンドウを開く

**主要な操作・処理内容**：
1. コマンドの入力と実行（ANSIエスケープシーケンスの解釈を含む）
2. テキストの選択とクリップボードへのコピー/ペースト
3. スクロールバックによる履歴の閲覧
4. スプリットによるウィンドウ分割（水平/垂直）
5. コマンドパレットによるコマンド検索・実行
6. フルスクリーンモードへの切り替え
7. フォントサイズの変更
8. 検索機能によるテキスト検索

**画面遷移**：
- スプリット操作 → スプリットビュー
- コマンドパレット表示 → コマンドパレット（オーバーレイ）
- 設定メニュー → 設定画面
- Aboutメニュー → About画面
- ペースト時（危険な内容） → クリップボード確認ダイアログ
- 閉じる時（プロセス実行中） → 閉じる確認ダイアログ
- 設定エラー → 設定エラーダイアログ
- アップデート確認 → アップデートポップオーバー

**権限による表示制御**：特になし。すべてのユーザーが同一の機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 端末エミュレーション | 主機能 | ANSIエスケープシーケンスの解釈、端末としての動作を提供 |
| 3 | スクリーン管理 | 主機能 | 端末画面のバッファ管理、メイン画面と代替画面の切り替え |
| 4 | スクロールバック | 主機能 | 履歴バッファの保持と過去の出力へのスクロールアクセス |
| 5 | 選択とコピー | 補助機能 | マウスまたはキーボードでのテキスト選択とクリップボードへのコピー |
| 6 | ハイパーリンク | 補助機能 | OSC 8エンコードされたハイパーリンクの認識とクリック |
| 7 | カラー対応 | 主機能 | 256色、True Color、X11色名の端末カラー表示 |
| 8 | SGR属性 | 主機能 | 太字、斜体、下線、取消線、点滅、反転などの文字属性表示 |
| 9 | Metal レンダラー | 主機能 | macOS向けMetalを使用した高性能GPUレンダリング |
| 13 | リガチャサポート | 補助機能 | プログラミングフォントのリガチャ(合字)表示 |
| 19 | キーバインド | 補助機能 | カスタマイズ可能なキーバインド設定 |
| 23 | マウス操作 | 補助機能 | マウスによるテキスト選択、スクロール、リンククリック |
| 25 | IME対応 | 補助機能 | 日本語等の入力メソッドエディタによる入力 |
| 28 | タブ | 遷移先機能 | タブ作成時の新規タブ画面への遷移 |
| 29 | スプリット(分割) | 遷移先機能 | ウィンドウ分割時のスプリットビューへの遷移 |
| 31 | フルスクリーン | 補助機能 | フルスクリーン表示への切り替え |
| 70 | クリップボード操作 | 補助機能 | コピー/ペースト操作時のシステムクリップボード連携 |
| 82 | カーソルスタイル | 補助機能 | カーソル形状(ブロック、アンダーライン、バー)の表示 |
| 87 | コマンドパレット | 遷移先機能 | コマンドパレット呼び出し時のオーバーレイ表示 |
| 89 | アップデート確認 | API連携 | アップデート通知オーバーレイの表示 |

## 画面種別

メイン操作画面（ターミナルエミュレーション）

## URL/ルーティング

N/A（ネイティブデスクトップアプリケーション）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| コマンド入力 | 入力 | String | - | ユーザーが入力するコマンドテキスト |
| 端末出力 | 出力 | String | - | コマンド実行結果やプログラム出力 |
| ウィンドウタイトル | 出力 | String | - | 現在の作業ディレクトリやプロセス名 |
| PWD | 出力 | URL | - | 現在の作業ディレクトリパス |
| セルサイズ | 出力 | NSSize | - | 端末セルの幅と高さ |

## 表示項目

| 項目名 | 表示位置 | データ型 | 説明 |
|--------|----------|----------|------|
| ターミナル表示領域 | 中央 | View | 端末出力を表示するメインエリア |
| タイトルバー | 上部 | String | ウィンドウタイトル、PWD表示 |
| スプリットディバイダー | 分割部分 | View | スプリット時の分割線 |
| コマンドパレット | オーバーレイ | View | コマンドパレット表示時 |
| アップデートオーバーレイ | 右下 | View | アップデート通知表示 |
| デバッグビルド警告 | 上部 | View | デバッグビルド時の警告バナー |

## イベント仕様

### 1-キーボード入力

ユーザーがキーボードでテキストを入力すると、入力内容がptyを通じてシェルプロセスに送信される。ANSIエスケープシーケンスは適切に解釈され、端末状態が更新される。

### 2-スプリット作成

Cmd+D（右分割）またはCmd+Shift+D（下分割）が押下されると、現在のサーフェスを基点に新しいスプリットが作成される。`newSplit`メソッドが呼び出され、SplitTreeに新しいノードが追加される。

### 3-コマンドパレット表示

Cmd+Shift+Pが押下されると、`commandPaletteIsShowing`がtrueに設定され、TerminalCommandPaletteViewがオーバーレイ表示される。

### 4-フォーカス移動

Tab/Shift+Tabまたは方向キーによるスプリット間のフォーカス移動。`splitMoveFocus`メソッドが呼び出され、SplitTreeのfocusTargetメソッドで次のフォーカス先が決定される。

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

Cmd+Wまたはウィンドウの閉じるボタンが押下されると、実行中のプロセスがある場合は確認ダイアログが表示される。確認後、ウィンドウが閉じられる。

### 6-フルスクリーン切り替え

Cmd+Enterまたはメニューからフルスクリーンを選択すると、`toggleFullscreen`メソッドが呼び出され、ネイティブまたは非ネイティブのフルスクリーンモードに切り替わる。

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

N/A（本アプリケーションはデータベースを使用しない）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG001 | 警告 | "Debug builds of Ghostty are very slow and you may experience performance problems." | デバッグビルド時 |
| MSG002 | 確認 | "Close Terminal? The terminal still has a running process." | プロセス実行中にクローズ時 |
| MSG003 | エラー | "Oh, no. Something went fatally wrong. Check the logs and restart Ghostty." | 致命的エラー発生時 |
| MSG004 | 情報 | "Cannot Create New Tab - Tabs aren't supported in the Quick Terminal." | クイックターミナルでタブ作成試行時 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| 致命的エラー | ErrorViewを表示し、ログの確認とアプリの再起動を案内 |
| 設定読み込みエラー | ConfigurationErrorsViewを表示し、リロードまたは無視を選択可能 |
| クリップボード確認要求 | ClipboardConfirmationViewを表示し、ユーザーの許可を求める |
| サーフェス未検出 | 操作をスキップし、エラーログを出力 |

## 備考

- macOSではSwiftUI + AppKitで実装、Linux/GTKではZigで実装
- GPUレンダリングはmacOSでMetal、LinuxでOpenGLを使用
- ウィンドウの状態（スプリット構成など）は復元可能（ステートリストア機能）
- Undo/Redo機能により、スプリットの閉じる/作成操作を取り消し可能

---

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

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

### 推奨読解順序

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

まず、スプリットツリーとサーフェスビューのデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SplitTree.swift | `macos/Sources/Features/Splits/SplitTree.swift` | スプリットの木構造、Node enum、Spatial表現を理解 |
| 1-2 | TerminalViewModel | `macos/Sources/Features/Terminal/TerminalView.swift` | surfaceTree、commandPaletteIsShowing等のViewModel定義（28-38行目） |

**読解のコツ**: SplitTreeはジェネリック型で、ViewTypeとしてGhostty.SurfaceViewを使用する。Node enumの`.leaf`と`.split`の2種類を理解することが重要。

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

処理の起点となるTerminalViewとBaseTerminalControllerを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | メインビューの構造、body変数（67-127行目）を理解 |
| 2-2 | BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ウィンドウコントローラーの基底クラス、surfaceTree管理を理解 |

**主要処理フロー**:
1. **67-73行目**: ghostty.readinessに応じてLoading/Error/Readyを分岐
2. **74-124行目**: ZStackでメインコンテンツ、コマンドパレット、アップデートオーバーレイを重ねる
3. **82-105行目**: TerminalSplitTreeViewでスプリット表示

#### Step 3: スプリット表示層を理解する

スプリットの表示とイベント処理を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalSplitTreeView.swift | `macos/Sources/Features/Splits/TerminalSplitTreeView.swift` | スプリットツリーのSwiftUI表示（28-45行目） |
| 3-2 | SplitView.swift | `macos/Sources/Features/Splits/SplitView.swift` | 実際のスプリットレイアウト、ドラッグジェスチャー |

**主要処理フロー**:
- **33行目**: zoomedまたはrootノードを表示
- **54-86行目**: ノードタイプに応じてleaf/splitを再帰的に表示

#### Step 4: コントローラー層を理解する

ウィンドウ管理とイベントハンドリングを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | newSplit（234-269行目）、closeSurface（390-427行目）を理解 |

**主要処理フロー**:
- **234行目**: newSplit - 新しいスプリット作成
- **468-511行目**: replaceSurfaceTree - ツリー置換とUndo管理

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

```
TerminalView (SwiftUI View)
    │
    ├─ TerminalSplitTreeView
    │      └─ TerminalSplitSubtreeView (再帰)
    │             ├─ TerminalSplitLeaf (Ghostty.SurfaceView)
    │             └─ SplitView
    │                    ├─ left: TerminalSplitSubtreeView
    │                    └─ right: TerminalSplitSubtreeView
    │
    ├─ TerminalCommandPaletteView (オーバーレイ)
    │
    └─ UpdateOverlay (条件付き表示)

BaseTerminalController (NSWindowController)
    │
    ├─ surfaceTree: SplitTree<Ghostty.SurfaceView>
    │      └─ Node: .leaf(view) / .split(Split)
    │
    ├─ focusedSurface: Ghostty.SurfaceView?
    │
    └─ TerminalViewDelegate
           ├─ focusedSurfaceDidChange
           ├─ pwdDidChange
           ├─ cellSizeDidChange
           └─ performSplitAction
```

### データフロー図

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

キーボード入力 ────────▶ Ghostty.SurfaceView ────────▶ pty → シェル
                              │
                              ▼
                        libghosttyKit
                              │
                              ▼
シェル出力 ◀──────────── ANSIパーサー ◀──────────── pty出力

スプリット操作 ────────▶ BaseTerminalController ────▶ SplitTree更新
                              │
                              ▼
                        TerminalSplitTreeView
                              │
                              ▼
                        画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | ソース | メインのSwiftUIビュー |
| BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ソース | ウィンドウコントローラー基底クラス |
| TerminalController.swift | `macos/Sources/Features/Terminal/TerminalController.swift` | ソース | 具象ウィンドウコントローラー |
| SplitTree.swift | `macos/Sources/Features/Splits/SplitTree.swift` | ソース | スプリット構造のデータモデル |
| SplitView.swift | `macos/Sources/Features/Splits/SplitView.swift` | ソース | スプリットのSwiftUIビュー |
| TerminalSplitTreeView.swift | `macos/Sources/Features/Splits/TerminalSplitTreeView.swift` | ソース | スプリットツリー表示ビュー |
| SplitView.Divider.swift | `macos/Sources/Features/Splits/SplitView.Divider.swift` | ソース | スプリットディバイダー |
| ErrorView.swift | `macos/Sources/Features/Terminal/ErrorView.swift` | ソース | エラー表示ビュー |
| window.zig | `src/apprt/gtk/window.zig` | ソース | GTK版のウィンドウ実装 |
