# 機能設計書 41-設定リロード

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「設定リロード」機能の設計を記述する。この機能により、ユーザーはアプリケーションを再起動することなく、設定ファイルの変更を実行中のGhosttyインスタンスに反映させることができる。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルエミュレータの設定を変更するたびにアプリケーションを再起動することは、作業効率を低下させ、実行中のセッションを中断する原因となる。設定リロード機能は、この課題を解決し、ユーザーがシームレスに設定を調整できるようにすることで、開発体験を向上させる。特にフォントサイズ、カラーテーマ、キーバインドなどの視覚的・操作的な設定を頻繁に変更するユーザーにとって重要な機能である。

**機能の利用シーン**：
- 設定ファイルを外部エディタで編集した後、変更を即座に反映させたい場合
- テーマやカラースキームを試行錯誤しながら調整する場合
- キーバインドの設定を変更してすぐに動作確認したい場合
- 条件付き設定（ライト/ダークモード切り替え時）を適用する場合

**主要な処理内容**：
1. キーバインド（デフォルト: Ctrl+Shift+,）またはメニューからのリロード要求を受信
2. 設定ファイルの再読み込みとパース処理
3. 新しい設定の検証と診断エラーの収集
4. アプリケーション全体への設定変更の伝播
5. 各ターミナルサーフェスへの設定更新の適用
6. 設定エラーがある場合のダイアログ表示

**関連システム・外部連携**：
- ファイルシステム（設定ファイルの読み込み）
- XDG Base Directory仕様（設定ファイルのパス解決）
- OSのシグナルハンドリング（SIGUSR2によるリロード）

**権限による制御**：特になし。すべてのユーザーが設定リロードを実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | 設定エラーダイアログ | 結果表示画面 | 設定ファイルのエラー表示、リロードボタン押下時の再読み込み |

## 機能種別

イベント処理 / 設定管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| soft | bool | No | ソフトリロードかどうか（条件付き設定の再評価のみ） | デフォルト: false |

### 入力データソース

- キーバインドアクション: `reload_config`
- メニューアクション: GTKの`app.reload-config`
- シグナル: SIGUSR2（Linux/GTK環境）
- 設定ファイル: `~/.config/ghostty/config` またはプラットフォーム固有のパス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 更新された設定 | Config | パース・検証済みの新しい設定オブジェクト |
| 診断エラー | DiagnosticList | 設定パース時のエラーリスト |

### 出力先

- アプリケーション全体への設定伝播
- 各ターミナルサーフェスへの設定更新
- エラー時: 設定エラーダイアログへの表示

## 処理フロー

### 処理シーケンス

```
1. リロード要求の受信
   └─ キーバインド、メニュー、またはシグナルからの呼び出し

2. 設定ファイルの再読み込み
   └─ Config.load()による設定ファイルのパース

3. 条件付き状態の適用
   └─ ライト/ダークモードなどの条件に基づく設定の調整

4. アプリケーション全体への設定伝播
   └─ updateConfig()による全サーフェスへの通知

5. 各サーフェスへの設定変更メッセージ送信
   └─ .change_config メッセージの送信

6. エラー処理
   └─ 診断エラーがある場合はダイアログ表示
```

### フローチャート

```mermaid
flowchart TD
    A[リロード要求受信] --> B{ソフトリロード?}
    B -->|Yes| C[条件付き設定の再評価]
    B -->|No| D[設定ファイル読み込み]
    D --> E[Config.load 実行]
    E --> F{パースエラー?}
    F -->|Yes| G[エラーダイアログ表示]
    F -->|No| H[条件付き状態適用]
    C --> H
    H --> I[アプリ設定更新]
    I --> J[全サーフェスに通知]
    J --> K[config_change アクション実行]
    K --> L[完了]
    G --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | 部分的リロード | 一部の設定は実行時に変更不可（例: フォントディスカバリ、言語設定） | 設定項目依存 |
| BR-41-02 | フォントサイズ保持 | 手動でフォントサイズを変更したサーフェスはリロード時に設定値を保持しない | サーフェスのfont_size_modified フラグがtrue |
| BR-41-03 | ソフトリロード | softフラグがtrueの場合、ファイル再読み込みせず条件付き設定のみ再評価 | soft = true |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | 設定ファイルの構文エラー | 設定エラーダイアログに詳細を表示 |
| - | ファイル読み込みエラー | 設定ファイルが存在しないまたはアクセス不可 | デフォルト設定を使用 |
| OutOfMemory | メモリ不足 | 設定のパースまたは適用時にメモリ不足 | エラーログ出力、処理中断 |

### リトライ仕様

リトライなし。ユーザーが再度リロードを実行する必要がある。

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

トランザクションは使用しない。設定の適用は各サーフェスごとに独立して行われる。

## パフォーマンス要件

- 設定ファイルの再読み込みは100ms以内に完了すること
- UIのブロッキングを最小限に抑えること

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

- 設定ファイルはユーザー権限でのみ読み取り可能であること
- 設定ファイルのパス解決時にシンボリックリンク攻撃を考慮すること

## 備考

- SIGUSR2シグナルによるリロードはLinux/GTK環境でのみサポート
- macOSではメニューまたはキーバインドからのリロードのみサポート

---

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

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

### 推奨読解順序

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

まず、リロードアクションと設定構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.zig | `src/apprt/action.zig` | ReloadConfig構造体の定義（272行目付近） |
| 1-2 | Config.zig | `src/config/Config.zig` | 設定の主要構造体定義 |
| 1-3 | Binding.zig | `src/input/Binding.zig` | reload_configアクションの定義（666行目） |

**読解のコツ**: Zigでは構造体のフィールドと関数が同じファイル内に定義される。`pub const`や`pub fn`に注目してAPIを理解する。

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

キーバインドからリロードが呼び出される流れを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Binding.zig | `src/input/Binding.zig` | reload_configアクションの定義 |
| 2-2 | command.zig | `src/input/command.zig` | コマンドとアクションのマッピング（570-574行目） |

**主要処理フロー**:
1. **666行目**: `reload_config`アクションのenum定義
2. **1290行目**: アプリケーションレベルのアクションとしてカテゴリ分類

#### Step 3: アプリケーション層の処理

App.zigでのリロード処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | App.zig | `src/App.zig` | メールボックス経由でのリロード要求処理（447行目） |
| 3-2 | App.zig | `src/App.zig` | updateConfig関数による設定の伝播（137-162行目） |

**主要処理フロー**:
- **428-430行目**: colorChange時のソフトリロード
- **447行目**: reload_configメッセージの処理
- **137-162行目**: 全サーフェスへの設定変更通知

#### Step 4: プラットフォーム固有の実装（GTK）

GTKアプリケーションでのリロード実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | application.zig | `src/apprt/gtk/class/application.zig` | reloadConfig関数の実装（2296行目付近） |
| 4-2 | application.zig | `src/apprt/gtk/class/application.zig` | SIGUSR2シグナルハンドリング（1486-1492行目） |

**主要処理フロー**:
- **730行目**: performActionでのreload_config処理
- **1128行目**: メニューアクセラレータの同期
- **1489行目**: SIGUSR2受信時のリロード実行
- **1573行目**: 設定エラーダイアログからのリロード
- **1648行目**: gActionReloadConfigの実装

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

```
[キーバインド/メニュー/SIGUSR2]
    │
    ├─ input.Binding (アクション解決)
    │      └─ reload_config アクション
    │
    ├─ App.drainMailbox (メールボックス処理)
    │      └─ performAction(.reload_config)
    │
    └─ apprt.gtk.Application (GTK実装)
           ├─ Action.reloadConfig
           │      ├─ Config.load
           │      └─ app.updateConfig
           │
           └─ 各Surface.handleMessage
                  └─ .change_config
```

### データフロー図

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

設定ファイル ────────▶ Config.load() ────────▶ Config構造体
(~/.config/ghostty/)     ↓
                    DiagnosticList ────────▶ エラーダイアログ
                         ↓
                    updateConfig() ────────▶ 各サーフェス更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| App.zig | `src/App.zig` | ソース | アプリケーションコア、設定更新の伝播 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインドアクションの定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドメタデータ |
| action.zig | `src/apprt/action.zig` | ソース | アクションタイプの定義 |
| Config.zig | `src/config/Config.zig` | ソース | 設定構造体とロード処理 |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTKアプリケーションのリロード実装 |
| Surface.zig | `src/Surface.zig` | ソース | サーフェス単位の設定適用 |
