# 通知設計書 12-ConEmuコメント

## 概要

本ドキュメントは、Ghosttyターミナルエミュレーターにおける「ConEmuコメント」通知機能の設計を記載するものである。OSC 9;11エスケープシーケンスを通じて、ConEmu互換のコメント通知を発行する機能について詳述する。

### 本通知の処理概要

**業務上の目的・背景**：ConEmuコメント通知は、ConEmuターミナルエミュレーターとの互換性を確保するために実装されている。主にデバッグ目的やログ記録の用途で使用され、アプリケーションやスクリプトがターミナルに対して補助的な情報を送信することを可能にする。通常のターミナル出力に影響を与えることなく、メタデータやデバッグ情報をターミナルエミュレーターに伝達するために設計されている。

**通知の送信タイミング**：アプリケーションまたはシェルスクリプトがOSC 9;11;commentの形式でエスケープシーケンスをターミナルに出力した時点でトリガーされる。具体的には`\033]9;11;コメントテキスト\007`または`\033]9;11;コメントテキスト\033\\`の形式である。このシーケンスは、プログラム実行中のデバッグポイント、状態変更の記録、処理フローの追跡など、様々な目的で使用される。

**通知の受信者**：ターミナルエミュレーター自体が主な受信者である。コメントはユーザーに直接表示されることを意図しておらず、ターミナルエミュレーターがログ記録やデバッグツールとの連携のために使用する。開発者がターミナルのインスペクター機能やログを確認する際に参照される。

**通知内容の概要**：OSC 9;11シーケンスで指定された任意のテキストがコメントとして記録される。内容に制限はなく、アプリケーションが任意の文字列を送信できる。UTF-8エンコーディングがサポートされる。

**期待されるアクション**：コメントはバックグラウンドで処理され、ユーザーの明示的なアクションは期待されない。デバッグ時には、ターミナルのログやインスペクターを通じてコメント内容を確認できることが期待される。現在のGhostty実装では、この機能は未実装（unimplemented）であり、OSCコマンドはログに記録されるのみである。

## 通知種別

内部ログ / デバッグ情報（ユーザー非表示）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（OSCパース時に即座に処理） |
| 優先度 | 低（デバッグ・ログ目的） |
| リトライ | 無し |

### 送信先決定ロジック

コメントは送信元ターミナルセッションに関連付けられる。将来的な実装では、インスペクター機能やログシステムに転送されることが想定される。

## 通知テンプレート

### コメント通知の場合

| 項目 | 内容 |
|-----|------|
| 種別 | 内部コメント |
| 内容 | OSC 9;11で指定されたコメント文字列 |
| 表示 | なし（内部処理のみ） |

### 本文テンプレート

```
{OSC 9;11で指定されたコメント文字列}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | コメントは添付ファイルをサポートしない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| comment | コメント文字列 | OSC 9;11パラメータ | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| エスケープシーケンス | OSC 9;11;comment受信 | OSCパーサーが有効なOSC 9;11シーケンスを検出 | ConEmu互換コメント通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 無効なOSC形式 | セミコロン区切りが正しくない場合はデスクトップ通知にフォールバック |
| 不完全なシーケンス | 9;11のみでセミコロンがない場合はデスクトップ通知として処理 |
| 現在の実装状態 | 未実装のためログ出力のみで実際のコメント処理は行われない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ターミナル入力受信] --> B[OSCパーサー処理]
    B --> C{OSC 9?}
    C -->|Yes| D{サブコマンド確認}
    C -->|No| E[他のOSC処理]
    D -->|9;11;| F[コメント抽出]
    D -->|その他| G[対応するConEmu処理]
    F --> H[ヌル終端処理]
    H --> I[conemu_commentコマンド生成]
    I --> J[Streamハンドラ呼び出し]
    J --> K{実装済み?}
    K -->|No| L[デバッグログ出力]
    K -->|Yes| M[コメント記録・処理]
    L --> N[終了]
    M --> N
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パースエラー | OSC 9;11形式が不正 | iTerm2デスクトップ通知としてフォールバック処理 |
| バッファオーバーフロー | コメントが2048バイトを超過 | パーサー状態をinvalidに設定し処理中断 |
| ヌル終端書き込み失敗 | writerへの書き込みエラー | パーサー状態をinvalidに設定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（OSC受信時に即座に処理）

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

- コメント内容はサニタイズされないため、悪意のあるコンテンツが含まれる可能性がある
- ログに記録される場合、機密情報の漏洩に注意が必要
- 大量のコメント送信によるリソース消費（ログファイル肥大化等）への配慮が必要

## 備考

- 現在のGhostty実装（2025年時点）では、この機能は「unimplemented」としてログ出力されるのみ
- ConEmuにおける本機能の主な用途はデバッグおよびログ記録
- OSC 9;11はOSC 9シリーズの中でも比較的マイナーな機能であり、実装優先度は低い可能性がある
- 不完全なシーケンス（`9;11`のみ）はデスクトップ通知として「11」という文字列を表示する

---

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

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

### 推奨読解順序

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

OSCコマンドの定義とConEmuコメントのデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | osc.zig | `src/terminal/osc.zig` | Command union内のconemu_commentフィールド（行152）を確認 |

**読解のコツ**: `conemu_comment: [:0]const u8`はヌル終端文字列へのスライスを表す。Zigでは`[:0]`がヌル終端を示す記法である。

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

OSCシーケンスのパース処理の入口を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | osc9.zig | `src/terminal/osc/parsers/osc9.zig` | parse関数内のOSC 9;11処理部分 |

**主要処理フロー**:
1. **行20-21**: data[0]が'1'の場合、OSC 9;1xシリーズの処理に入る
2. **行85-97**: data[1]が'1'の場合（9;11）、コメント処理
3. **行87-88**: セミコロン区切りの確認
4. **行89-92**: ヌル終端の書き込み
5. **行94-96**: conemu_commentコマンドの生成

#### Step 3: コマンド実行層を理解する

パースされたコマンドがどのように処理されるかを追跡する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stream.zig | `src/terminal/stream.zig` | OSCコマンドのディスパッチ処理 |

**主要処理フロー**:
- **行2045**: conemu_commentは現在unimplemented扱い
- **行2053**: デバッグログへの出力のみ

#### Step 4: テストケースを確認する

実装の意図と境界条件を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | osc9.zig | `src/terminal/osc/parsers/osc9.zig` | OSC 9;11のテストケース |

**主要テスト**:
- **行1088-1100**: 正常系テスト（"ab"というコメント）
- **行1102-1114**: 不完全シーケンスのフォールバックテスト

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

```
ターミナル入力
    |
    +-- Stream.next() [stream.zig]
           |
           +-- osc.Parser.next() [osc.zig]
                  |
                  +-- osc9.parse() [osc/parsers/osc9.zig]
                         |
                         +-- データ長チェック (data.len < 3)
                         |
                         +-- セミコロン確認 (data[2] != ';')
                         |
                         +-- ヌル終端書き込み (writeByte(0))
                         |
                         +-- Command生成 (conemu_comment)
                                |
                                +-- [未実装] ログ出力
```

### データフロー図

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

OSC 9;11;comment  --->  OSCパーサー        --->   Command構造体
シーケンス               (osc9.zig)               (conemu_comment)
                              |
                              v
                         文字列処理
                         - セミコロン検証
                         - ヌル終端追加
                         - スライス生成
                              |
                              v
                         Streamハンドラ
                         (stream.zig)
                              |
                              v
                         [現在] ログ出力
                         [将来] インスペクター/ログ連携
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| osc.zig | `src/terminal/osc.zig` | ソース | OSCコマンド定義とパーサー基盤 |
| osc9.zig | `src/terminal/osc/parsers/osc9.zig` | ソース | OSC 9（ConEmu/iTerm2）パーサー実装 |
| stream.zig | `src/terminal/stream.zig` | ソース | ターミナルストリーム処理とコマンドディスパッチ |
| parsers.zig | `src/terminal/osc/parsers.zig` | ソース | OSCパーサーのインデックス |
