# 機能設計書 73-デスクトップ通知

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるデスクトップ通知機能の設計について記載する。この機能はOSC 9およびOSC 777エスケープシーケンスを解釈し、端末上で実行されるアプリケーションからのデスクトップ通知をシステムの通知機能に転送する。

### 本機能の処理概要

**業務上の目的・背景**：
CLIツールやスクリプトが長時間実行される場合、完了時にユーザーに通知を送りたい場面がある。従来は端末を常に監視する必要があったが、デスクトップ通知機能により、バックグラウンドで実行中のタスクの完了を見逃すことなく通知を受け取ることができる。これはiTerm2やその他の端末エミュレータで標準的な機能として提供されている。

**機能の利用シーン**：
- 長時間実行されるビルドやテストの完了通知
- スクリプトからの重要なアラート通知
- シェル統合による長時間コマンド完了通知
- CI/CDパイプラインの実行結果通知

**主要な処理内容**：
1. OSC 9またはOSC 777エスケープシーケンスの解析
2. 通知タイトルと本文の抽出
3. アプリケーションランタイム（apprt）への通知アクション送信
4. プラットフォーム固有の通知APIによる表示

**関連システム・外部連携**：
- OSC 9: 通知内容のみを含むシンプルな形式
- OSC 777: `notify;title;body`形式（rxvt-unicode拡張）
- macOS: UserNotifications.framework
- Linux/GTK: libnotify / GNotification

**権限による制御**：
- `desktop-notifications`設定でデスクトップ通知の有効/無効を制御

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 通知トリガーとなるエスケープシーケンスの処理 |

## 機能種別

通知処理 / OSエスケープシーケンス処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| title | []const u8 | No | 通知タイトル（最大63文字） | 長さ制限あり |
| body | []const u8 | Yes | 通知本文（最大255文字） | 長さ制限あり |

### 入力データソース

- PTYからのエスケープシーケンス
  - OSC 9: `\033]9;body\033\\`
  - OSC 777: `\033]777;notify;title;body\033\\`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| desktop_notification | Message | タイトルと本文を含む通知メッセージ |

### 出力先

- システムデスクトップ通知
  - macOS: Notification Center
  - Linux: デスクトップ環境の通知デーモン

## 処理フロー

### 処理シーケンス

```
1. PTYからのデータ受信
   └─ terminal streamでエスケープシーケンスを解析
2. OSC 9/777パーサーによる解析
   └─ タイトルと本文を抽出
3. StreamHandlerへのコールバック
   └─ show_desktop_notificationが呼び出される
4. showDesktopNotification処理
   └─ Messageを構築してsurfaceMessageWriterで送信
5. Surfaceでのメッセージ受信
   └─ desktop_notificationアクションとしてapprに転送
6. プラットフォーム固有の通知表示
   └─ GTKまたはmacOS通知APIで表示
```

### フローチャート

```mermaid
flowchart TD
    A[PTYからエスケープシーケンス受信] --> B{シーケンス種別?}
    B -->|OSC 9| C[OSC9パーサー]
    B -->|OSC 777| D[rxvt_extensionパーサー]
    C --> E[通知本文抽出]
    D --> F[タイトル・本文抽出]
    E --> G[showDesktopNotification]
    F --> G
    G --> H[Message構築]
    H --> I{desktop-notifications有効?}
    I -->|Yes| J[surfaceMessageWriter送信]
    I -->|No| K[処理スキップ]
    J --> L[apprのdesktop_notificationアクション]
    L --> M{プラットフォーム?}
    M -->|macOS| N[UserNotifications API]
    M -->|GTK| O[GNotification API]
    N --> P[システム通知表示]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-1 | タイトル長制限 | タイトルは最大63文字に切り詰め | 常時 |
| BR-73-2 | 本文長制限 | 本文は最大255文字に切り詰め | 常時 |
| BR-73-3 | NULL終端 | 文字列はNULL終端される | 常時 |
| BR-73-4 | 設定による無効化 | desktop-notifications=false時は通知を送信しない | 設定時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パース失敗 | 不正なOSCシーケンス | シーケンスを無視 |
| - | 通知API失敗 | OS通知APIのエラー | エラーログ出力 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- 通知送信は非同期で行われ、端末処理をブロックしない
- 大量の通知が発生した場合はOSの通知システムに委任

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

- 悪意のあるスクリプトによる大量通知攻撃の可能性
- `desktop-notifications`設定で機能を無効化可能
- 通知内容にはユーザー入力が含まれる可能性があるため、サニタイズはOSに委任

## 備考

- OSC 9はiTerm2互換形式
- OSC 777はrxvt-unicode互換形式
- シェル統合による長時間コマンド完了通知は別機能（command_finished）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | surface.zig | `src/apprt/surface.zig` | Message.desktop_notification構造体（55-61行目） |
| 1-2 | action.zig | `src/apprt/action.zig` | DesktopNotificationアクション定義 |

**読解のコツ**: `desktop_notification`メッセージは固定サイズのバッファ（title: 63文字、body: 255文字）を持つ。

#### Step 2: エスケープシーケンス解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | osc9.zig | `src/terminal/osc/parsers/osc9.zig` | OSC 9パーサーの実装 |
| 2-2 | rxvt_extension.zig | `src/terminal/osc/parsers/rxvt_extension.zig` | OSC 777パーサーの実装 |
| 2-3 | osc.zig | `src/terminal/osc.zig` | OSCコマンドのディスパッチ |

**主要処理フロー**:
- OSC 9: 本文のみをパース
- OSC 777: `notify;title;body`形式をパース

#### Step 3: 通知送信処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stream_handler.zig | `src/termio/stream_handler.zig` | showDesktopNotification関数（1427-1443行目） |

**主要処理フロー**:
1. **1427-1431行目**: 関数シグネチャとMessage構築開始
2. **1432-1440行目**: タイトルと本文をバッファにコピー（長さ制限適用）
3. **1442行目**: surfaceMessageWriterで送信

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

```
PTY入力
    │
    └─ terminal/stream.zig (VTパーサー)
           │
           └─ osc.zig (OSCハンドラー)
                  │
                  ├─ osc9.zig (OSC 9パース)
                  └─ rxvt_extension.zig (OSC 777パース)
                         │
                         └─ stream_handler.zig
                                │
                                └─ showDesktopNotification
                                       │
                                       └─ surfaceMessageWriter
                                              │
                                              └─ Surface.zig
                                                     │
                                                     └─ apprt.action (desktop_notification)
                                                            │
                                                            ├─ GTK: GNotification
                                                            └─ macOS: UNUserNotificationCenter
```

### データフロー図

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

PTY ────────▶ VTパーサー ────▶ OSCハンドラー
                                    │
              ┌────────────────────┴────────────────────┐
              │                                          │
         OSC 9パーサー                          OSC 777パーサー
              │                                          │
              └────────────────────┬────────────────────┘
                                   │
                                   ▼
                         showDesktopNotification
                                   │
                                   ▼
                      Message.desktop_notification
                                   │
                                   ▼
                         desktop_notification アクション
                                   │
                                   ▼
                         システム通知 API
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stream_handler.zig | `src/termio/stream_handler.zig` | ソース | showDesktopNotification実装 |
| osc.zig | `src/terminal/osc.zig` | ソース | OSCコマンドディスパッチ |
| osc9.zig | `src/terminal/osc/parsers/osc9.zig` | ソース | OSC 9パーサー |
| rxvt_extension.zig | `src/terminal/osc/parsers/rxvt_extension.zig` | ソース | OSC 777パーサー |
| surface.zig | `src/apprt/surface.zig` | ソース | Messageの定義 |
| action.zig | `src/apprt/action.zig` | ソース | アクション定義 |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTK通知実装 |
| Ghostty.App.swift | `macos/Sources/Ghostty/Ghostty.App.swift` | ソース | macOS通知実装 |
