# 機能設計書 74-ベル

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける端末ベル（BEL文字）の処理機能について記載する。この機能はASCII BEL文字（0x07）を受信した際に、ユーザーに対して音声または視覚的な通知を行う。

### 本機能の処理概要

**業務上の目的・背景**：
端末ベルは古くからある機能であり、プログラムがユーザーの注意を引くために使用する。コマンドライン補完の失敗、エラー発生、タイマー完了など様々な場面で利用される。Ghosttyはこのベル信号を受信した際に、アプリケーションランタイムに通知し、プラットフォーム固有の方法で音声または視覚的なフィードバックを提供する。

**機能の利用シーン**：
- シェルのタブ補完が候補なしで失敗した場合
- `echo -e '\a'`などでプログラムから明示的にベルを鳴らす場合
- バックグラウンドウィンドウでのベル発生時のウィンドウバッジ表示
- 視覚的ベル（画面フラッシュ）での通知

**主要な処理内容**：
1. BEL文字（0x07）の検出
2. レートリミット処理（連続ベルの抑制）
3. `ring_bell`アクションの発行
4. プラットフォーム固有の通知処理

**関連システム・外部連携**：
- macOS: NSSound（システムベル音）/ 視覚ベル
- GTK/Linux: GTKベルAPI / Waylandプロトコル
- ウィンドウマネージャー: アテンション要求（タスクバーバッジ等）

**権限による制御**：
- 特に権限制御は不要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | ベル処理のトリガーおよび視覚的ベル表示 |

## 機能種別

通知処理 / 制御文字処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | BEL文字（0x07）として受信 | - |

### 入力データソース

- PTYからのASCII BEL文字（0x07）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ring_bell | Message | ベル通知メッセージ |

### 出力先

- システムサウンド（音声ベル）
- ウィンドウマネージャー（視覚的ベル、アテンション要求）

## 処理フロー

### 処理シーケンス

```
1. PTYからのデータ受信
   └─ BEL文字（0x07）を検出
2. VTパーサーでのBEL処理
   └─ bell()関数が呼び出される
3. StreamHandlerでのベル処理
   └─ surfaceMessageWriter(.ring_bell)を呼び出し
4. Surfaceでのメッセージ受信
   └─ レートリミットチェック
5. ring_bellアクション発行
   └─ apprへ転送
6. プラットフォーム固有処理
   └─ システムサウンドまたは視覚的ベル
```

### フローチャート

```mermaid
flowchart TD
    A[PTYからBEL文字受信] --> B[VTパーサー bell 関数]
    B --> C[surfaceMessageWriter ring_bell]
    C --> D[Surface メッセージ受信]
    D --> E{last_bell_time チェック}
    E -->|レート制限内| F[ring_bell アクション発行]
    E -->|レート超過| G[処理スキップ]
    F --> H{プラットフォーム?}
    H -->|macOS| I[NSSound / 視覚ベル]
    H -->|GTK| J[GTK ベルAPI]
    I --> K[ユーザーへ通知]
    J --> K
    G --> L[終了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-1 | BEL文字検出 | ASCII 0x07をベルとして解釈 | 常時 |
| BR-74-2 | レートリミット | 連続するベルを抑制する | last_bell_timeに基づく |
| BR-74-3 | 非フォーカスベル | 非フォーカスウィンドウではアテンション要求 | ウィンドウ非フォーカス時 |
| BR-74-4 | 視覚ベル | 設定により画面フラッシュで通知 | 設定時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | サウンド再生失敗 | システムサウンドAPIエラー | エラーログ出力（処理続行） |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- ベル処理は非同期で行われ、端末処理をブロックしない
- レートリミットにより大量のベルが発生しても処理負荷を軽減

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

- 悪意のあるスクリプトによる大量ベル攻撃はレートリミットで軽減
- ベル音量はシステム設定に委任

## 備考

- BEL文字はCtrl+G（^G）としても送信可能
- tmuxなどのマルチプレクサ内でもベルは正しく転送される
- 視覚ベルは`visual-bell`設定で制御（実装による）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | surface.zig | `src/apprt/surface.zig` | Message.ring_bell定義（88-89行目） |
| 1-2 | action.zig | `src/apprt/action.zig` | ring_bellアクション定義（291-293行目） |

**読解のコツ**: `ring_bell`はパラメータなしの単純なメッセージ/アクション。

#### Step 2: BEL文字処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | stream_handler.zig | `src/termio/stream_handler.zig` | bell関数（555-557行目） |

**主要処理フロー**:
1. **555行目**: `inline fn bell` - BEL文字のハンドラ
2. **556行目**: `surfaceMessageWriter(.ring_bell)` - メッセージ送信

#### Step 3: レートリミット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Surface.zig | `src/Surface.zig` | last_bell_time フィールド（169行目） |

**主要処理フロー**:
- `last_bell_time`で前回のベル時刻を記録
- 一定間隔以内の連続ベルは抑制

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

```
PTY入力
    │
    └─ terminal/stream.zig (VTパーサー)
           │
           └─ BEL文字検出 (0x07)
                  │
                  └─ stream_handler.zig
                         │
                         └─ bell()
                                │
                                └─ surfaceMessageWriter(.ring_bell)
                                       │
                                       └─ Surface.zig
                                              │
                                              ├─ レートリミットチェック
                                              │
                                              └─ apprt.action (ring_bell)
                                                     │
                                                     ├─ GTK: gtk_widget_error_bell
                                                     └─ macOS: NSSound
```

### データフロー図

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

PTY ────────▶ VTパーサー ────▶ BEL検出
                                  │
                                  ▼
                            bell() 関数
                                  │
                                  ▼
                         ring_bell メッセージ
                                  │
                                  ▼
                     レートリミット チェック
                                  │
                          ┌───────┴───────┐
                          │               │
                       [通過]          [抑制]
                          │               │
                          ▼               ▼
                   ring_bell アクション   終了
                          │
                          ▼
                   システム ベル音/視覚ベル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stream_handler.zig | `src/termio/stream_handler.zig` | ソース | bell関数（BELハンドラ） |
| Surface.zig | `src/Surface.zig` | ソース | レートリミット処理、last_bell_time |
| surface.zig | `src/apprt/surface.zig` | ソース | Message.ring_bell定義 |
| action.zig | `src/apprt/action.zig` | ソース | ring_bellアクション定義 |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTKベル実装 |
| actions.zig | `src/apprt/gtk/ext/actions.zig` | ソース | GTKアクション実装 |
