# 機能設計書 33-ジャンプ時のハイライトフラッシュ

## 概要

本ドキュメントは、Doom Emacsにおけるジャンプ時のハイライトフラッシュ機能の設計を記載する。この機能は、カーソルが大きく移動した際に、移動先の行を一時的にハイライト表示し、ユーザーが現在位置を見失わないようにする。

### 本機能の処理概要

**業務上の目的・背景**：大規模なファイルを編集する際、ジャンプやウィンドウ切り替えを行うと、カーソルがどこに移動したか見失うことがある。ナビゲーションフラッシュ機能は、移動先の行を短時間ハイライトすることで、ユーザーの視線を誘導し、作業効率を向上させる。

**機能の利用シーン**：
- imenu-after-jump-hook（imenuジャンプ後）
- better-jumper-post-jump-hook（ジャンパー使用後）
- counsel-grep-post-action-hook（grep結果からジャンプ時）
- consult-after-jump-hook（consult使用後）
- dumb-jump-after-jump-hook（定義ジャンプ後）
- doom-switch-window-hook（ウィンドウ切り替え時）
- org-follow-link-hook（Orgリンク追跡時）
- save-place-find-file-hook（保存位置復元時）
- evil-window-top/middle/bottom（Evilウィンドウ移動コマンド）

**主要な処理内容**：
1. 各種ジャンプフックへのハイライト関数登録
2. nav-flashパッケージによる行ハイライト表示
3. 除外コマンド・モードのチェック
4. 同一位置への連続フラッシュ防止

**関連システム・外部連携**：
- nav-flashパッケージ
- better-jumper、consult、counsel等の補完パッケージ
- Evilモード
- Org-mode

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | Nav Flash | 主機能 | カーソル移動先行のハイライト表示 |

## 機能種別

UI表示 / ナビゲーション支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +nav-flash-exclude-commands | list | No | フラッシュを除外するコマンドリスト | シンボルのリスト |
| +nav-flash-exclude-modes | list | No | フラッシュを除外するメジャーモードリスト | シンボルのリスト |

### 入力データソース

- カーソル移動イベント
- 各種ジャンプフック

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| compilation-highlight-overlay | overlay | ハイライト表示用のオーバーレイ |

### 出力先

現在のバッファの該当行

## 処理フロー

### 処理シーケンス

```
1. ジャンプ操作の検出
   └─ 各種フックから呼び出し
2. 除外条件のチェック
   └─ 除外コマンド・モードの確認
3. 同一位置チェック
   └─ 前回と同じ位置なら処理スキップ
4. ハイライト表示
   └─ nav-flash-showによるオーバーレイ表示
5. オーバーレイをカレントウィンドウに限定
   └─ 他ウィンドウには表示しない
```

### フローチャート

```mermaid
flowchart TD
    A[ジャンプ操作発生] --> B{ミニバッファ?}
    B -->|Yes| C[処理終了]
    B -->|No| D{除外コマンド?}
    D -->|Yes| C
    D -->|No| E{除外モード?}
    E -->|Yes| C
    E -->|No| F{同一位置?}
    F -->|Yes| C
    F -->|No| G[nav-flash-show]
    G --> H[オーバーレイ表示]
    H --> I[ウィンドウ限定設定]
    I --> J[位置を記録]
    J --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-33-1 | ミニバッファ除外 | ミニバッファではフラッシュしない | minibufferp が true |
| BR-33-2 | 除外コマンド | mouse-set-point等のマウス操作は除外 | +nav-flash-exclude-commands に含まれる |
| BR-33-3 | 除外モード | so-long-mode、special-mode、term-mode等は除外 | +nav-flash-exclude-modes に含まれる |
| BR-33-4 | 同一位置スキップ | 同じウィンドウ・バッファ・位置への移動はフラッシュしない | +nav-flash--last-point と一致 |
| BR-33-5 | 遅延フラッシュ | org-follow-link等では0.1秒後にフラッシュ | 位置確定に時間がかかる場合 |

### 計算ロジック

特になし（単純なオーバーレイ表示）

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | オーバーレイなし | compilation-highlight-overlayが未定義 | overlayp チェックで回避 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- フラッシュ処理がジャンプ操作を妨げないこと
- 連続ジャンプ時に過剰なオーバーレイ生成を避けること

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

特になし

## 備考

- nav-flashパッケージのピン留めバージョン: 5d4b48567862f6be0ca973d6b1dca90e4815cb9b
- 将来的にEmacs 28以降ではpulsar.elに置き換え予定

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.el | `modules/ui/nav-flash/packages.el` | nav-flashパッケージの依存定義 |

**読解のコツ**: `:pin`でコミットハッシュが固定されている。

#### Step 2: 設定ファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/nav-flash/config.el` | フック登録とパッケージ設定 |

**主要処理フロー**:
- **3-6行目**: `+nav-flash-exclude-commands`変数定義（除外コマンドリスト）
- **8-10行目**: `+nav-flash-exclude-modes`変数定義（除外モードリスト）
- **17-19行目**: `use-package!`によるnav-flash設定
- **22-27行目**: 各種ジャンプフックへの`+nav-flash-blink-cursor-maybe-h`登録
- **29行目**: `doom-switch-window-hook`への登録
- **32行目**: `org-follow-link-hook`への遅延フラッシュ登録
- **35-36行目**: `persp-mode`統合
- **39行目**: `save-place-find-file-hook`へのアドバイス
- **42-44行目**: Evil window コマンドへのアドバイス
- **47行目**: `what-cursor-position`へのアドバイス（ga キー用）

#### Step 3: autoload関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload.el | `modules/ui/nav-flash/autoload.el` | 実際のフラッシュ処理関数 |

**主要処理フロー**:
- **3行目**: `+nav-flash--last-point`変数（前回のフラッシュ位置記録）
- **6-14行目**: `+nav-flash-blink-cursor`関数（基本フラッシュ処理）
  - **10行目**: ミニバッファ除外チェック
  - **11行目**: `nav-flash-show`呼び出し
  - **13-14行目**: オーバーレイを現在ウィンドウに限定
- **17-28行目**: `+nav-flash-blink-cursor-maybe`関数（条件付きフラッシュ）
  - **20行目**: 除外コマンドチェック
  - **21行目**: so-long-minor-modeチェック
  - **22行目**: 除外モードチェック
  - **23-26行目**: 同一位置チェック
- **31-35行目**: `+nav-flash-delayed-blink-cursor-h`関数（遅延フラッシュ）
  - **35行目**: 0.1秒後に実行
- **38-42行目**: 関数エイリアス定義
- **45-48行目**: インタラクティブコマンド定義

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

```
各種フック
    │
    ├─ imenu-after-jump-hook
    ├─ better-jumper-post-jump-hook
    ├─ counsel-grep-post-action-hook
    ├─ consult-after-jump-hook
    ├─ dumb-jump-after-jump-hook
    └─ doom-switch-window-hook
           │
           ▼
    +nav-flash-blink-cursor-maybe-h
           │
           ├─ 除外チェック
           │
           └─ +nav-flash-blink-cursor
                  │
                  └─ nav-flash-show (外部パッケージ)
```

### データフロー図

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

ジャンプイベント ───▶ 除外条件チェック ───▶ 処理終了
                         │                    or
                         ▼
                    同一位置チェック ───▶ フラッシュ表示
                         │
                         ▼
                    nav-flash-show ───▶ オーバーレイ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/nav-flash/config.el` | ソース | フック登録と設定 |
| autoload.el | `modules/ui/nav-flash/autoload.el` | ソース | フラッシュ処理関数 |
| packages.el | `modules/ui/nav-flash/packages.el` | 設定 | 依存パッケージ定義 |
