# 機能設計書 32-ウィンドウ装飾

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるウィンドウ装飾（Window Decorations）機能の設計を定義する。

### 本機能の処理概要

ウィンドウ装飾機能は、ターミナルウィンドウのタイトルバー、ボタン、フレームなどの表示・非表示を制御する。ユーザーはシンプルな見た目を好む場合や、タイリングウィンドウマネージャーを使用する場合に装飾を非表示にできる。

**業務上の目的・背景**：ターミナルの作業領域を最大化し、視覚的なノイズを減らすことで、作業効率と集中力を向上させる。特にタイリングウィンドウマネージャー（i3, Sway等）との連携や、最小限のUIを好むユーザーに有効である。

**機能の利用シーン**：
- タイリングウィンドウマネージャーでウィンドウ枠が不要な場合
- 画面領域を最大限に活用したい場合
- ミニマリストな外観を好む場合
- 複数モニター環境で統一感のある見た目にしたい場合

**主要な処理内容**：
1. toggle_window_decorationsアクションの受信
2. 現在のウィンドウ装飾状態の確認
3. ウィンドウ装飾のオン/オフ切り替え
4. ウィンドウスタイルの再同期（syncAppearance）

**関連システム・外部連携**：
- Linux/GTK: GtkWindow.setDecorated()、CSS classes (ssd/csd)
- Wayland/X11: ウィンドウプロトコル固有の装飾設定

**権限による制御**：特に権限による制御はない。全ユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | ウィンドウ装飾の切り替え操作 |

## 機能種別

画面制御処理 / ウィンドウ外観管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | パラメータなし（トグル動作） | - |

### 入力データソース

- キーバインド設定（keybind = toggle_window_decorations）
- 設定ファイル（window-decoration）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| decorated | bool | 装飾表示状態 |
| windowDecoration | WindowDecoration | 装飾モード（auto/none/client/server） |

### 出力先

- ウィンドウ外観（タイトルバー、フレーム表示）
- CSSクラス（ssd/csd/solid-csd/no-border-radius）

## 処理フロー

### 処理シーケンス

```
1. toggle_window_decorationsアクション受信
   └─ キーバインドから呼び出される
2. toggleWindowDecorations()を呼び出し
   └─ Window.toggleWindowDecorations()
3. 現在の装飾状態をチェック
   ├─ window_decorationがnullでない場合: 設定をクリア（オーバーライド解除）
   └─ window_decorationがnullの場合: 新しい値を設定
4. syncAppearance()でウィンドウ外観を同期
   ├─ CSDが有効かどうかをチェック
   ├─ 適切なCSSクラスを設定（ssd/csd/solid-csd）
   └─ gtk.Window.setDecorated()を呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_window_decorations受信] --> B[toggleWindowDecorations呼び出し]
    B --> C{window_decoration設定済み?}
    C -->|Yes| D[設定をnullにリセット]
    C -->|No| E{現在の装飾設定は?}
    E -->|none| F[autoに変更]
    E -->|auto/client/server| G[noneに変更]
    D --> H[syncAppearance]
    F --> H
    G --> H
    H --> I{CSD有効?}
    I -->|Yes| J[csd/solid-csd CSSクラス設定]
    I -->|No| K[ssd CSSクラス設定]
    J --> L[setDecorated true]
    K --> M[setDecorated false]
    L --> N[完了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-01 | 自動モード | システムデフォルトの装飾を使用 | window-decoration=auto |
| BR-32-02 | 無装飾モード | タイトルバー・フレームを非表示 | window-decoration=none |
| BR-32-03 | クライアントサイド装飾 | GTKが装飾を描画（CSD） | window-decoration=client |
| BR-32-04 | サーバーサイド装飾 | ウィンドウマネージャーが装飾を描画（SSD） | window-decoration=server |
| BR-32-05 | トグル動作 | オーバーライドがあれば解除、なければnoneに設定 | toggle_window_decorations実行時 |
| BR-32-06 | Linux限定 | 本機能はLinux（GTK）でのみ実装 | Linux環境 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定取得失敗 | configがnil | 処理を中断 |
| - | winproto同期失敗 | ウィンドウプロトコル操作エラー | 警告ログ出力 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- 装飾切り替え: 即座に反映されること

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

特になし。

## 備考

- macOSでは未実装（macOSには独自のタイトルバースタイル設定がある）
- GTKでは、CSDとSSDの両方をサポート
- 非コンポジットウィンドウマネージャー（i3, dwm等）ではsolid-csdを使用

---

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

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

### 推奨読解順序

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

ウィンドウ装飾に関連する設定値とアクションの定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.zig | `src/apprt/action.zig` | toggle_window_decorationsアクション定義（112行目） |
| 1-2 | Binding.zig | `src/input/Binding.zig` | toggle_window_decorationsバインディング（705-708行目） |

**読解のコツ**: このアクションはパラメータを持たないシンプルなトグル動作である。

#### Step 2: GTK実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | window.zig | `src/apprt/gtk/class/window.zig` | toggleWindowDecorations関数（838-855行目）、getWindowDecoration関数（830-835行目） |
| 2-2 | window.zig | `src/apprt/gtk/class/window.zig` | syncAppearance関数（566-652行目）、CSD/SSDクラス設定 |

**主要処理フロー**:
1. **838-855行目**: toggleWindowDecorations - 装飾設定のトグル処理
2. **830-835行目**: getWindowDecoration - 現在の装飾設定を取得
3. **566-608行目**: syncAppearance内でCSD/SSD設定を行う

#### Step 3: ウィンドウプロトコル連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | winproto.zig | `src/apprt/gtk/winproto.zig` | clientSideDecorationEnabled関数 |

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

```
[キーバインド: toggle_window_decorations]
    │
    └─ [GTK]
           └─ Window.toggleWindowDecorations
                  ├─ window_decoration設定の更新
                  └─ syncAppearance
                          ├─ winproto.clientSideDecorationEnabled
                          ├─ CSSクラス設定 (ssd/csd/solid-csd)
                          └─ gtk.Window.setDecorated
```

### データフロー図

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

キーバインド ─────▶ toggle_window_decorations ────────▶ ウィンドウ状態変更
                    アクション処理
                         │
設定値 ────────────▶ toggleWindowDecorations ─────────▶ window_decoration更新
(window-decoration)      │
                         │
                    syncAppearance ───────────────────▶ CSSクラス設定
                         │                              setDecorated呼び出し
                         │
winproto ──────────▶ CSD有効判定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action.zig | `src/apprt/action.zig` | ソース | toggle_window_decorationsアクション定義 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインドアクション定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット用コマンド定義 |
| window.zig | `src/apprt/gtk/class/window.zig` | ソース | GTKウィンドウ実装（装飾制御） |
| winproto.zig | `src/apprt/gtk/winproto.zig` | ソース | ウィンドウプロトコル実装 |
| Config.zig | `src/config/Config.zig` | ソース | window-decoration設定定義 |
