# 機能設計書 95-先頭/末尾へスクロール

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「先頭/末尾へスクロール」機能の設計を記述する。本機能により、ユーザーはスクロールバックの先頭（最も古い出力）または末尾（最新の出力）へ即座にジャンプできる。

### 本機能の処理概要

先頭/末尾へスクロール機能は、ターミナルのビューポートをスクロールバック履歴の先頭（top）または現在の出力位置（bottom）へ瞬時に移動させる機能である。

**業務上の目的・背景**：長いログやビルド出力を確認する際、先頭に戻って最初から確認したい場合や、最新の出力に戻りたい場合がある。ページスクロールや行スクロールで何度もスクロールするのは非効率であるため、一発で目的の位置にジャンプできる機能が必要。

**機能の利用シーン**：
- ログの先頭からエラーを探す場合（scroll_to_top）
- スクロールバック確認後に最新出力に戻る場合（scroll_to_bottom）
- Home/Endキーによる素早いナビゲーション

**主要な処理内容**：
1. ユーザーがscroll_to_topまたはscroll_to_bottomアクションを実行
2. ビューポートが先頭または末尾に移動
3. 画面が再描画される

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | scroll_to_top/scroll_to_bottomはパラメータなし | - |

### 入力データソース

- キーバインド設定（例: `keybind = shift+home=scroll_to_top`）
- コマンドパレットからの選択

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ビューポート位置 | Pin | 先頭または末尾のスクロール位置 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ユーザーがscroll_to_top/scroll_to_bottomを実行
   └─ キーバインド経由（通常Shift+Home/Shift+End）
2. Surface.performBindingActionでアクションを処理
3. queueIoでscroll_viewportメッセージを送信
   └─ .topまたは.bottomを指定
4. termioがビューポートを移動
   └─ スクロールバックの先頭または末尾へ
5. 画面が再描画される
```

### フローチャート

```mermaid
flowchart TD
    A[scroll_to_top/bottom実行] --> B{アクション種別}
    B -->|scroll_to_top| C[.top指定でメッセージ送信]
    B -->|scroll_to_bottom| D[.bottom指定でメッセージ送信]
    C --> E[ビューポートを先頭に移動]
    D --> F[ビューポートを末尾に移動]
    E --> G[画面再描画]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-95-1 | 先頭ジャンプ | スクロールバックの最も古い行に移動 | scroll_to_top |
| BR-95-2 | 末尾ジャンプ | 現在の出力位置（最新行）に移動 | scroll_to_bottom |
| BR-95-3 | 自動スクロール復帰 | scroll_to_bottomで自動スクロールモードが復帰 | scroll_to_bottom時 |

### 計算ロジック

```
scroll_to_top:    scroll_viewport = .{ .top = {} }
scroll_to_bottom: scroll_viewport = .{ .bottom = {} }
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | なし | スクロールバックが空の場合 | 現在位置を維持 |

### リトライ仕様

リトライ不要

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

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

## パフォーマンス要件

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

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

特になし

## 備考

- `scroll-to-bottom`設定（設定ファイル）でキーストローク時の自動スクロール動作を制御可能
- `scroll_to_selection`アクションで選択範囲へのジャンプも可能

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: scroll_to_topとscroll_to_bottomはパラメータなしのアクション。内部で.topまたは.bottomを指定する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | scroll_to_top処理（5492-5496行目） |
| 2-2 | Surface.zig | `src/Surface.zig` | scroll_to_bottom処理（5498-5502行目） |

**主要処理フロー**:
1. **5492行目**: scroll_to_topアクションのマッチング
2. **5493-5495行目**: queueIo(.scroll_viewport = .{ .top = {} })でメッセージ送信
3. **5498行目**: scroll_to_bottomアクションのマッチング
4. **5499-5501行目**: queueIo(.scroll_viewport = .{ .bottom = {} })でメッセージ送信

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

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

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

```
Surface.performBindingAction
    │
    ├─ scroll_to_topアクションを検出
    │      │
    │      └─ queueIo(.scroll_viewport = .{ .top = {} })
    │
    └─ scroll_to_bottomアクションを検出
           │
           └─ queueIo(.scroll_viewport = .{ .bottom = {} })
                  │
                  └─ termio.scrollViewport(.top/.bottom)
                         │
                         └─ Screen.scroll(.top/.bottom)
```

### データフロー図

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

キーバインド ───▶ Surface.performBindingAction ───▶ IOメッセージキュー
(Shift+Home/End)         │
                         ▼
                    .top/.bottom指定
                         │
                         ▼
                    scroll_viewportメッセージ ───▶ ビューポート移動
                                                       │
                                                       ▼
                                                 画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | scroll_to_top/bottom定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット用コマンド（244-260行目） |
| Surface.zig | `src/Surface.zig` | ソース | アクション処理のエントリーポイント |
| Termio.zig | `src/termio/Termio.zig` | ソース | IOスレッドでのスクロール処理 |
| Screen.zig | `src/terminal/Screen.zig` | ソース | スクリーンのスクロール状態管理 |
| Config.zig | `src/config/Config.zig` | ソース | scroll-to-bottom設定の定義 |
