# 機能設計書 34-フローティングウィンドウ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるフローティングウィンドウ（常に最前面表示）機能の設計を定義する。

### 本機能の処理概要

フローティングウィンドウ機能は、ターミナルウィンドウを他のウィンドウよりも常に前面に表示する。フォーカスを失っても他のウィンドウの後ろに隠れないため、参照用のターミナルとして利用できる。

**業務上の目的・背景**：コマンドの実行結果やログを監視しながら他のアプリケーションで作業する場合に、ターミナルを常に視認できる状態に保つ。ペアプログラミングやデモンストレーションでも有効。

**機能の利用シーン**：
- ログ監視しながら他アプリで作業する場合
- ドキュメントを見ながらコマンドを入力する場合
- 小さいウィンドウで常時参照情報を表示したい場合
- チュートリアル動画を見ながらターミナル操作する場合

**主要な処理内容**：
1. toggle_window_float_on_topアクションの受信
2. 現在のフローティング状態を確認
3. float_windowアクションを発行（on/off/toggle）
4. ウィンドウレベルを変更（floating/normal）

**関連システム・外部連携**：
- macOS: NSWindow.level（.floating）

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

## 関連画面

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

## 機能種別

画面制御処理 / ウィンドウ状態管理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- キーバインド設定（keybind = toggle_window_float_on_top）
- コマンドパレット

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| isFloating | bool | フローティング状態かどうか |

### 出力先

- ウィンドウレベル（.floating/.normal）

## 処理フロー

### 処理シーケンス

```
1. toggle_window_float_on_topアクション受信
   └─ キーバインドまたはコマンドパレットから呼び出される
2. float_windowアクションに変換
   └─ FloatWindow.toggleとして発行
3. アプリケーションランタイムでアクション処理
   └─ macOSではfloatWindow関数を呼び出し
4. ウィンドウレベルを変更
   ├─ オンの場合: window.level = .floating
   └─ オフの場合: window.level = .normal
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_window_float_on_top受信] --> B[float_window:toggle発行]
    B --> C{現在のレベル判定}
    C -->|floating| D[レベルをnormalに変更]
    C -->|normal| E[レベルをfloatingに変更]
    D --> F[完了]
    E --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | トグル動作 | 現在のフローティング状態を反転 | toggle_window_float_on_top実行時 |
| BR-34-02 | 初期状態 | ウィンドウは常にノーマル状態で起動 | ウィンドウ初期化時 |
| BR-34-03 | macOS限定 | 本機能はmacOSでのみ実装 | macOS環境 |
| BR-34-04 | フローティングレベル | NSWindow.Level.floatingを使用 | フローティング有効時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | エラーケースなし |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- フローティング切り替え: 即座に反映されること

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

特になし。

## 備考

- macOSのみで実装されている
- Linux/GTKでは未実装
- ウィンドウが常に最前面にいることで、他のアプリケーションの操作を妨げる可能性がある

---

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

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

### 推奨読解順序

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

フローティングウィンドウに関連するアクションと型の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.zig | `src/apprt/action.zig` | FloatWindow enum定義（578-586行目）、float_windowアクション |
| 1-2 | Binding.zig | `src/input/Binding.zig` | toggle_window_float_on_topバインディング（710-716行目） |

**読解のコツ**: FloatWindow enumはon/off/toggleの3つの値を持つ。

#### Step 2: キーバインドからアクションへの変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Binding.zig | `src/input/Binding.zig` | toggle_window_float_on_topがfloat_window.toggleに変換される処理 |

**主要処理フロー**:
- キーバインドアクションtoggle_window_float_on_topはapprt.Action.float_window = .toggleに変換される

#### Step 3: macOS実装を理解する（Swift側）

macOS側での実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | floatWindow関数の実装 |

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

```
[キーバインド: toggle_window_float_on_top]
    │
    └─ [macOS]
           └─ apprt.Action.float_window = .toggle
                  └─ embedded.performAction
                          └─ Swift AppDelegate
                                  └─ BaseTerminalController.floatWindow
                                          └─ window.level = .floating / .normal
```

### データフロー図

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

キーバインド ─────▶ toggle_window_float_on_top ────────▶ ウィンドウレベル変更
                    │
                    ▼
              float_window: .toggle
                    │
                    ▼
              performAction
                    │
                    ▼
              floatWindow関数
                    │
                    ▼
              window.level設定 ────────────────────────▶ 最前面表示/解除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action.zig | `src/apprt/action.zig` | ソース | FloatWindow enum、float_windowアクション定義 |
| Binding.zig | `src/input/Binding.zig` | ソース | toggle_window_float_on_topキーバインド定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット用コマンド定義 |
| BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ソース | macOSでのウィンドウレベル制御 |
