# 機能設計書 37-macOSアプリ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける macOS向けのネイティブアプリケーション実装の設計を定義する。

### 本機能の処理概要

macOSアプリ機能は、SwiftUI/AppKitベースのネイティブmacOSアプリケーションを提供する。ウィンドウ管理、タブ、スプリット、タイトルバースタイル等のmacOSネイティブな体験を実現する。

**業務上の目的・背景**：macOSユーザーに対して、プラットフォームネイティブな外観と操作感を持つターミナルを提供する。SwiftUI/AppKitを使用することで、macOSの最新機能やアクセシビリティ機能との統合を実現。

**機能の利用シーン**：
- macOSでGhosttyを使用する場合
- Apple Silicon/Intel Macでターミナルを使用する場合
- macOSのネイティブ機能（Handoff、Service等）を活用する場合

**主要な処理内容**：
1. AppDelegateによるアプリケーション初期化
2. libghosttyとの連携（組み込みターミナルエンジン）
3. ターミナルウィンドウの作成と管理
4. macOS固有機能の提供（メニュー、サービス等）

**関連システム・外部連携**：
- SwiftUI / AppKit
- libghostty（Zigで実装されたターミナルコア）
- Sparkle（アップデート）
- macOS Accessibility API

**権限による制御**：セキュア入力モードではアクセシビリティ権限関連の制御がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | メインターミナルUI |
| 2 | クイックターミナル | 補助画面 | ドロップダウンターミナル |
| 4 | エラービュー | 補助画面 | 致命的エラー表示 |
| 11 | About画面 | 補助画面 | バージョン情報表示 |

## 機能種別

アプリケーションランタイム / GUI管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 起動時パラメータは設定ファイルとCLIオプションで指定 | - |

### 入力データソース

- コマンドライン引数
- 設定ファイル（~/.config/ghostty/config）
- 環境変数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | GUIウィンドウ表示 |

### 出力先

- 画面表示（macOSウィンドウ）

## 処理フロー

### 処理シーケンス

```
1. アプリケーション起動
   └─ AppDelegate.applicationDidFinishLaunching
       ├─ Ghostty.App初期化
       ├─ グローバルイベントタップ設定
       └─ 初期ウィンドウ作成
2. ターミナルウィンドウ作成
   └─ TerminalController.init
       ├─ ウィンドウNIB読み込み
       ├─ DerivedConfig設定
       └─ TerminalView配置
3. libghostty連携
   └─ embedded.zig経由でターミナルコア呼び出し
       ├─ サーフェス作成
       ├─ PTY管理
       └─ レンダリング
4. イベント処理
   └─ AppKit/SwiftUIイベントループ
5. 終了処理
   └─ applicationWillTerminate
```

### フローチャート

```mermaid
flowchart TD
    A[アプリ起動] --> B[AppDelegate初期化]
    B --> C[Ghostty.App作成]
    C --> D[libghostty初期化]
    D --> E{設定読み込み成功?}
    E -->|Yes| F[ターミナルウィンドウ作成]
    E -->|No| G[設定エラーダイアログ表示]
    F --> H[TerminalController]
    H --> I[TerminalView]
    I --> J[サーフェス作成]
    J --> K[PTY起動]
    K --> L[レンダリング開始]
    L --> M[イベントループ]
    G --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-01 | タイトルバースタイル | macos-titlebar-styleで4種類のスタイルをサポート | native/hidden/transparent/tabs |
| BR-37-02 | ウィンドウ復元 | NSRestorableを使用してウィンドウ状態を復元 | restorable=true |
| BR-37-03 | サービスプロバイダ | macOSサービスメニューに機能を提供 | 常時 |
| BR-37-04 | Sparkle更新 | アップデート確認にSparkleを使用 | リリースビルド |
| BR-37-05 | カスタムアイコン | アプリアイコンのカスタマイズをサポート | 設定有効時 |

### 計算ロジック

特になし。

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定読み込みエラー | 設定ファイル不正 | 設定エラーダイアログ表示 |
| - | libghostty初期化失敗 | ライブラリエラー | エラービュー表示 |

### リトライ仕様

設定エラー時は再読み込みボタンを提供。

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

トランザクションは使用しない。

## パフォーマンス要件

- 起動時間: 1秒以内
- Metal レンダリング: 60fps以上

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

- セキュア入力モード（toggle_secure_input）をサポート
- サンドボックス環境で動作可能

## 備考

- SwiftUI/AppKitのハイブリッド実装
- libghosttyを組み込みライブラリとして使用
- Apple Silicon (arm64) / Intel (x86_64) ユニバーサルバイナリ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | main.swift | `macos/Sources/App/macOS/main.swift` | アプリエントリーポイント |
| 1-2 | AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | アプリケーションデリゲート |

**主要処理フロー**:
- AppDelegate.applicationDidFinishLaunching でアプリ初期化

#### Step 2: Ghostty.Appを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppDelegate+Ghostty.swift | `macos/Sources/App/macOS/AppDelegate+Ghostty.swift` | Ghosttyアプリ拡張 |

#### Step 3: ターミナルコントローラーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalController.swift | `macos/Sources/Features/Terminal/TerminalController.swift` | メインコントローラー |
| 3-2 | BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | 基底クラス |
| 3-3 | TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | ターミナルビュー |

**主要処理フロー**:
- TerminalController.init でウィンドウNIB読み込み
- TerminalView で実際の描画処理

#### Step 4: libghostty連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | embedded.zig | `src/apprt/embedded.zig` | 組み込みランタイム |

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

```
main
    │
    └─ AppDelegate
           │
           ├─ applicationDidFinishLaunching
           │      ├─ Ghostty.App初期化
           │      │      └─ libghostty初期化 (embedded.zig)
           │      │              └─ Config読み込み
           │      │
           │      └─ 初期ウィンドウ作成
           │              └─ TerminalController.init
           │                      ├─ windowNibName決定
           │                      │      └─ タイトルバースタイル判定
           │                      └─ TerminalView作成
           │                              └─ サーフェス初期化
           │
           └─ イベントループ
                  ├─ キーイベント処理
                  ├─ マウスイベント処理
                  └─ レンダリング更新
```

### データフロー図

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

設定ファイル ───▶ Config読み込み ─────────────────────▶ Ghostty.Config
                         │
                    Ghostty.App初期化
                         │
                    TerminalController
                         │
                    TerminalView ────────────────────▶ 画面表示
                         │
libghostty ─────▶ サーフェス/PTY管理
(embedded.zig)           │
                    レンダリング (Metal)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.swift | `macos/Sources/App/macOS/main.swift` | ソース | アプリエントリーポイント |
| AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | ソース | アプリデリゲート |
| AppDelegate+Ghostty.swift | `macos/Sources/App/macOS/AppDelegate+Ghostty.swift` | ソース | Ghostty拡張 |
| TerminalController.swift | `macos/Sources/Features/Terminal/TerminalController.swift` | ソース | ターミナルコントローラー |
| BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ソース | 基底コントローラー |
| TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | ソース | ターミナルビュー |
| TerminalWindow.swift | `macos/Sources/Features/Terminal/Window Styles/TerminalWindow.swift` | ソース | ウィンドウクラス |
| Fullscreen.swift | `macos/Sources/Helpers/Fullscreen.swift` | ソース | フルスクリーン実装 |
| embedded.zig | `src/apprt/embedded.zig` | ソース | 組み込みランタイム |
| ServiceProvider.swift | `macos/Sources/Features/Services/ServiceProvider.swift` | ソース | サービスプロバイダ |
