# 機能設計書 24-マウスレポーティング

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「マウスレポーティング」機能の設計を記述する。マウスレポーティングは、端末内で実行中のアプリケーション（vim、tmux等）にマウスイベントを転送するための機能であり、複数のマウスプロトコル（X10、SGR等）をサポートする。

### 本機能の処理概要

**業務上の目的・背景**：
TUIアプリケーション（vim、tmux、htop等）は、マウス入力を活用することでユーザーエクスペリエンスを向上させることができる。マウスレポーティング機能は、端末内で実行中のアプリケーションがマウスイベントを受信できるようにするための標準化されたプロトコルを実装する。これにより、ターミナルアプリケーションとGUIアプリケーションの操作感の差を縮小できる。

**機能の利用シーン**：
- vim/neovimでのマウスによるカーソル移動、テキスト選択
- tmuxでのペイン選択、リサイズ
- レンジャーなどのファイルマネージャでのナビゲーション
- htop等の監視ツールでのプロセス選択

**主要な処理内容**：
1. アプリケーションからのマウスモード設定シーケンス受信（CSI ? Pm h/l）
2. マウスイベント形式の設定（X10、UTF-8、SGR、URXVT、SGR-Pixels）
3. マウスイベントのキャプチャとエンコード
4. エンコードされたシーケンスのPTY送信
5. toggle_mouse_reportingによる手動切り替え

**関連システム・外部連携**：
- 端末エスケープシーケンスパーサー
- PTY出力システム
- マウス操作機能（No.23）との連携

**権限による制御**：
本機能に特別な権限制御はない。設定の`mouse-reporting`でグローバルに有効/無効を切り替え可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | TUIアプリケーションへのマウスイベント転送 |

## 機能種別

プロトコル処理 / イベント変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mode | MouseEvents | Yes | マウスイベントモード | none/x10/normal/button/any |
| format | MouseFormat | Yes | マウスイベント形式 | x10/utf8/sgr/urxvt/sgr_pixels |
| button | MouseButton | Yes | マウスボタン | left/middle/right/wheel等 |
| x | u16 | Yes | X座標（セル） | 1以上 |
| y | u16 | Yes | Y座標（セル） | 1以上 |
| mods | Mods | Yes | 修飾キー | shift/ctrl/alt |

### 入力データソース

- アプリケーションからのCSIシーケンス（モード設定）
- OSからのマウスイベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| sequence | []const u8 | エンコードされたマウスシーケンス |

### 出力先

- PTY（実行中アプリケーションへ）

## 処理フロー

### 処理シーケンス

```
1. マウスモード設定シーケンス受信
   └─ CSI ? 9 h (X10) / CSI ? 1000 h (Normal) / etc.

2. マウスイベント受信
   └─ クリック、ドラッグ、スクロール

3. モード確認
   └─ mouse_event != none かつ mouse-reporting設定有効

4. イベントエンコード
   └─ フォーマットに応じたエンコード

5. PTY送信
   └─ エンコードされたシーケンスを出力
```

### フローチャート

```mermaid
flowchart TD
    A[マウスイベント受信] --> B{mouse_event != none?}
    B -->|No| C[通常のマウス処理]
    B -->|Yes| D{mouse-reporting有効?}

    D -->|No| C
    D -->|Yes| E{Shift押下でオーバーライド?}

    E -->|Yes| C
    E -->|No| F[イベントエンコード]

    F --> G{mouse_format}
    G -->|x10| H[X10形式エンコード]
    G -->|utf8| I[UTF-8形式エンコード]
    G -->|sgr| J[SGR形式エンコード]
    G -->|urxvt| K[URXVT形式エンコード]
    G -->|sgr_pixels| L[SGR-Pixels形式エンコード]

    H --> M[PTY送信]
    I --> M
    J --> M
    K --> M
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-24-1 | X10モード（9） | ボタンプレスのみレポート | CSI ? 9 h |
| BR-24-2 | Normalモード（1000） | プレスとリリースをレポート | CSI ? 1000 h |
| BR-24-3 | Buttonモード（1002） | ボタン押下中のモーションをレポート | CSI ? 1002 h |
| BR-24-4 | Anyモード（1003） | すべてのモーションをレポート | CSI ? 1003 h |
| BR-24-5 | Shiftオーバーライド | Shift押下時はマウスレポーティングを無効化 | mouse-shift-capture設定依存 |

### 計算ロジック

**X10形式エンコード**:
```
ESC [ M Cb Cx Cy
Cb = button + 32
Cx = x + 32 (最大223)
Cy = y + 32 (最大223)
```

**SGR形式エンコード**:
```
ESC [ < Cb ; Cx ; Cy M (プレス)
ESC [ < Cb ; Cx ; Cy m (リリース)
```

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 座標オーバーフロー | X10形式で座標が223を超える | SGR形式へのフォールバックまたは無視 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- マウスイベントのエンコードと送信: 即時（ミリ秒以下）
- ドラッグ中のanyモードでも滑らかな追従が必要

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

- マウスイベントはPTYを通じてアプリケーションに送信されるため、悪意のあるアプリケーションがマウス位置を追跡する可能性がある
- mouse-reporting設定でグローバルに無効化可能

## 備考

- toggle_mouse_reportingアクションで手動切り替え可能
- Shiftキーでのオーバーライドはmouse-shift-capture設定で制御

---

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

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

### 推奨読解順序

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

マウスイベントモードと形式の定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Terminal.zig | `src/terminal/Terminal.zig` | MouseEvents enum定義（169-180行目） |
| 1-2 | Terminal.zig | `src/terminal/Terminal.zig` | MouseFormat enum定義（184-190行目） |
| 1-3 | Terminal.zig | `src/terminal/Terminal.zig` | flags内のmouse_event/mouse_format（96-97行目） |

**読解のコツ**: MouseEventsの各値とCSIモード番号の対応を理解する（コメント参照）。

#### Step 2: モード設定を理解する

アプリケーションからのモード設定シーケンスの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | modes.zig | `src/terminal/modes.zig` | DECプライベートモードの定義 |

**主要処理フロー**:
1. CSI ? Pm h でモード有効化
2. Terminal.flags.mouse_eventを更新
3. CSI ? Pm l でモード無効化

#### Step 3: イベントエンコードを理解する

マウスイベントのエンコード処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Binding.zig | `src/input/Binding.zig` | toggle_mouse_reportingアクション定義（738行目） |

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

```
アプリケーション ──── CSI ? 1000 h ───▶ Terminal.setMode()
                                             │
                                             ▼
                                      flags.mouse_event = .normal
                                      flags.mouse_format = .x10

マウスイベント
    │
    └─ Surface.mouseButtonCallback()
           │
           ├─ checkMouseReporting() ─── モード確認
           │
           └─ encodeMouseEvent() ───▶ PTY送信
```

### データフロー図

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

CSI ? Pm h ────────▶ Terminal.setMode() ────────▶ flags.mouse_event更新
                                                  flags.mouse_format更新

マウスクリック ────▶ Surface ────▶ encodeMouseEvent() ────▶ PTY
    │                                    │
    │                                    ▼
    │                            MouseFormat判定
    │                                    │
    │                          ┌─────────┼─────────┐
    │                          ▼         ▼         ▼
    │                        X10       SGR    SGR-Pixels
    │                          │         │         │
    │                          └─────────┴─────────┘
    │                                    │
    └────────────────────────────────────▼
                                   ESC [ < Cb ; Cx ; Cy M
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | MouseEvents/MouseFormat定義、flags管理 |
| modes.zig | `src/terminal/modes.zig` | ソース | DECモード定義 |
| Surface.zig | `src/Surface.zig` | ソース | マウスイベント処理、エンコード |
| Binding.zig | `src/input/Binding.zig` | ソース | toggle_mouse_reportingアクション |
| Config.zig | `src/config/Config.zig` | ソース | mouse-reporting/mouse-shift-capture設定 |
