# 機能設計書 94-行スクロール

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「行スクロール」機能の設計を記述する。本機能により、ユーザーは指定した行数だけターミナル画面をスクロールできる。

### 本機能の処理概要

行スクロール機能は、ターミナルのビューポートを指定した行数だけ上下に移動させる機能である。ページスクロールより細かい粒度でスクロール位置を調整できる。

**業務上の目的・背景**：ページ単位のスクロールでは大きすぎ、マウススクロールでは不正確な場合がある。行単位でのスクロールにより、正確な位置への移動が可能になる。特定の行を画面内に表示させたい場合や、微調整が必要な場合に有用。

**機能の利用シーン**：
- 特定のログ行を画面内に収めたい場合
- ページスクロール後の微調整
- カスタムキーバインドでの独自スクロール動作の実装

**主要な処理内容**：
1. ユーザーがscroll_page_linesアクションをパラメータ付きで実行
2. 正の値で下方向、負の値で上方向にスクロール
3. ビューポートが指定行数分移動
4. 画面が再描画される

**関連システム・外部連携**：特になし

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | スクロール操作が行われる画面 |

## 機能種別

UI制御 / ビューポート操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| lines | i16 | Yes | スクロール行数（正=下、負=上） | 符号付き16bit整数 |

### 入力データソース

- キーバインド設定（例: `keybind = ctrl+up=scroll_page_lines:-3`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ビューポート位置 | isize | 新しいスクロール位置（行数） |

### 出力先

- 画面表示（ビューポートの移動）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがscroll_page_lines:Nを実行
   └─ Nは正負の整数（例: 3, -10）
2. Surface.performBindingActionでアクションを処理
   └─ パラメータから行数を取得
3. queueIoでscroll_viewportメッセージを送信
   └─ delta = lines（そのまま渡す）
4. termioがビューポートを移動
   └─ 正の値で下方向、負の値で上方向
5. 画面が再描画される
```

### フローチャート

```mermaid
flowchart TD
    A[scroll_page_lines:N実行] --> B{Nの符号}
    B -->|正| C[下方向にN行スクロール]
    B -->|負| D[上方向にabs(N)行スクロール]
    B -->|0| E[スクロールなし]
    C --> F[scroll_viewportメッセージ送信]
    D --> F
    E --> G[処理終了]
    F --> H[ビューポート位置更新]
    H --> I[画面再描画]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-1 | 正の値 | 下方向（新しい出力方向）にスクロール | lines > 0 |
| BR-94-2 | 負の値 | 上方向（古い出力方向）にスクロール | lines < 0 |
| BR-94-3 | 上限制限 | スクロールバックの先頭で停止 | 上方向スクロール時 |
| BR-94-4 | 下限制限 | 最新出力位置で停止 | 下方向スクロール時 |

### 計算ロジック

```
delta = lines（パラメータの値をそのまま使用）

例:
  scroll_page_lines:3   → 3行下にスクロール
  scroll_page_lines:-10 → 10行上にスクロール
```

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

### 操作別データベース影響一覧

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | なし | スクロール範囲外へのスクロール要求 | 自動的に範囲内に制限される |

### リトライ仕様

リトライ不要

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

トランザクション不要（メモリ上の状態更新のみ）

## パフォーマンス要件

スクロール操作は即座に反映されること（16ms以内、60fps相当）

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

特になし

## 備考

- `scroll_page_up`/`scroll_page_down`（ページスクロール）との違いは、固定行数 vs 画面行数
- `scroll_page_fractional`（小数ページスクロール）と組み合わせて柔軟なスクロール設定が可能

---

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

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

### 推奨読解順序

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

スクロール関連のアクション定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | scroll_page_lines定義（448-451行目） |

**読解のコツ**: `scroll_page_lines: i16`はパラメータ付きアクション。i16は符号付き16bit整数で、正の値が下方向、負の値が上方向を表す。

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

Surfaceでのアクション処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | scroll_page_lines処理（5549-5553行目） |

**主要処理フロー**:
1. **5549行目**: scroll_page_linesアクションのマッチング、linesパラメータを取得
2. **5550-5552行目**: queueIo(.scroll_viewport = .{ .delta = lines })でメッセージ送信

#### Step 3: termioの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Termio.zig | `src/termio/Termio.zig` | scroll_viewportメッセージの処理 |

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

```
Surface.performBindingAction
    │
    └─ scroll_page_linesアクションを検出
           │
           ├─ lines = パラメータ値（i16）
           │
           └─ queueIo(.scroll_viewport = .{ .delta = lines })
                  │
                  └─ termio.scrollViewport(lines)
                         │
                         └─ Screen.scroll(.delta = lines)
```

### データフロー図

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

キーバインド ───▶ Surface.performBindingAction ───▶ IOメッセージキュー
(scroll_page_lines:N)     │
                          ▼
                    N行分のdelta値取得
                          │
                          ▼
                    scroll_viewportメッセージ ───▶ ビューポート移動
                                                       │
                                                       ▼
                                                 画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | scroll_page_lines定義（パラメータ付き） |
| Surface.zig | `src/Surface.zig` | ソース | アクション処理のエントリーポイント |
| Termio.zig | `src/termio/Termio.zig` | ソース | IOスレッドでのスクロール処理 |
| Screen.zig | `src/terminal/Screen.zig` | ソース | スクリーンのスクロール状態管理 |
