# 画面設計書 21-Nav Flash

## 概要

本ドキュメントは、Doom EmacsのNav Flash機能の画面設計について記述します。Nav Flashは、大きなカーソル移動後に現在行を一時的にフラッシュ（点滅ハイライト）させ、ユーザーにカーソル位置を視覚的にフィードバックする機能です。

### 本画面の処理概要

Nav Flashは、エディタ内でカーソルが大きく移動した際に、移動先の行を一時的にハイライト表示する視覚フィードバック機能を提供します。

**業務上の目的・背景**：大画面ディスプレイ（1600p以上や4K）での作業時、ジャンプ操作後にカーソル位置を見失いやすい問題を解決します。特にファイル間ジャンプ、検索結果へのジャンプ、ブックマークへの移動など、大きな画面移動を伴う操作において、ユーザーがカーソル位置を即座に把握できるようにします。

**画面へのアクセス方法**：Nav Flashは自動的に動作するため、明示的な画面アクセスは不要です。以下の操作時に自動的にトリガーされます：
- imenu-after-jump-hook（imenuジャンプ後）
- better-jumper-post-jump-hook（ジャンプリスト経由のジャンプ後）
- counsel-grep-post-action-hook（検索結果選択後）
- consult-after-jump-hook（consult検索後）
- dumb-jump-after-jump-hook（定義ジャンプ後）
- doom-switch-window-hook（ウィンドウ切り替え時）
- org-follow-link-hook（Orgリンク追跡時）
- persp-activated-functions（ワークスペース切り替え時）

**主要な操作・処理内容**：
1. フックまたはadviceによりジャンプイベントを検出
2. 除外条件（コマンド、モード）をチェック
3. 現在行にオーバーレイを作成しハイライト表示
4. 短時間後に自動的にハイライトを解除

**画面遷移**：Nav Flashは独立した画面ではなく、任意のバッファ上で動作する視覚エフェクトです。他の画面への遷移や、他画面からの遷移トリガーとして機能することはありません。

**権限による表示制御**：権限による制御はありません。以下のモードでは自動的に無効化されます：
- so-long-mode（長い行を含むファイル）
- special-mode
- comint-mode
- term-mode
- vterm-mode
- ミニバッファ

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 33 | ジャンプ時のハイライトフラッシュ | 主機能 | カーソル移動先行のハイライト表示 |

## 画面種別

視覚エフェクト（オーバーレイ表示）

## URL/ルーティング

N/A（Emacsバッファ上で動作するため、URLの概念なし）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| this-command | 入力 | symbol | 現在実行中のコマンド（除外判定に使用） |
| major-mode | 入力 | symbol | 現在のメジャーモード（除外判定に使用） |
| compilation-highlight-overlay | 出力 | overlay | ハイライト用オーバーレイオブジェクト |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| 行ハイライト | 現在行全体を一時的にハイライト | ジャンプイベント発生時 |

## イベント仕様

### 1-ジャンプイベント検出

各種フックおよびadviceにより、カーソルの大きな移動を検出します。

**処理フロー**：
1. フック/adviceから `+nav-flash-blink-cursor-maybe-h` が呼び出される
2. 除外条件をチェック（コマンド、モード、前回位置との比較）
3. 条件を満たす場合、`+nav-flash-blink-cursor` を実行
4. `nav-flash-show` を呼び出してオーバーレイを表示
5. オーバーレイを現在ウィンドウに限定

### 2-遅延フラッシュ

Orgリンク追跡など、即時にポイント位置が確定しない場合に使用します。

**処理フロー**：
1. `+nav-flash-delayed-blink-cursor-h` が呼び出される
2. 0.1秒後に `+nav-flash-blink-cursor-h` を実行
3. 通常のフラッシュ処理を実行

## データベース更新仕様

N/A（データベースを使用しない）

## メッセージ仕様

N/A（メッセージ表示なし）

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| ミニバッファ内 | フラッシュを実行しない |
| 除外コマンド実行時 | フラッシュを実行しない |
| 除外モード有効時 | フラッシュを実行しない |
| 前回と同一位置 | フラッシュを実行しない |

## 備考

- nav-flashパッケージは将来的にpulsar.elに置き換え予定（Emacs 28サポート終了後）
- evil-mode利用時は、`evil-window-top`、`evil-window-middle`、`evil-window-bottom`、`what-cursor-position`（gaキーバインド）でもフラッシュが発生

---

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

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

### 推奨読解順序

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

Nav Flashは比較的シンプルな構造で、主に変数と関数の組み合わせで実装されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/nav-flash/config.el` | 除外設定変数 `+nav-flash-exclude-commands` と `+nav-flash-exclude-modes` の定義を確認 |

**読解のコツ**: Emacs Lispの `defvar` は変数定義、`use-package!` はパッケージ設定のDoom Emacs独自マクロです。

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

フックとadviceによるイベント登録が処理の起点となります。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/nav-flash/config.el` | `add-hook!` と `advice-add` によるイベント登録を確認 |

**主要処理フロー**:
1. **行22-27**: 複数のジャンプ関連フックに `+nav-flash-blink-cursor-maybe-h` を登録
2. **行29**: ウィンドウ切り替えフックに登録
3. **行32**: Orgリンク追跡フックに遅延フラッシュを登録
4. **行35-36**: persp-mode有効化時の遅延フラッシュを登録
5. **行39-47**: Evilコマンドへのadvice登録

#### Step 3: コア機能を理解する

実際のフラッシュ処理はautoload.elに実装されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload.el | `modules/ui/nav-flash/autoload.el` | フラッシュ処理の実装詳細を確認 |

**主要処理フロー**:
- **行6-14**: `+nav-flash-blink-cursor` - 基本的なフラッシュ処理。ミニバッファチェック後、`nav-flash-show` を呼び出し
- **行17-28**: `+nav-flash-blink-cursor-maybe` - 条件チェック付きフラッシュ。除外コマンド/モードと前回位置をチェック
- **行31-35**: `+nav-flash-delayed-blink-cursor-h` - 0.1秒遅延でフラッシュを実行

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

```
ジャンプイベント発生
    │
    ├─ imenu-after-jump-hook ─────────────┐
    ├─ better-jumper-post-jump-hook ──────┤
    ├─ counsel-grep-post-action-hook ─────┤
    ├─ consult-after-jump-hook ───────────┼──▶ +nav-flash-blink-cursor-maybe-h
    ├─ dumb-jump-after-jump-hook ─────────┤           │
    ├─ doom-switch-window-hook ───────────┘           │
    │                                                  ▼
    │                                        除外条件チェック
    │                                                  │
    ├─ org-follow-link-hook ─────────────────────────┐│
    │                                                 ││
    │   +nav-flash-delayed-blink-cursor-h            ││
    │           │                                     ││
    │           ▼ (0.1秒後)                           ▼▼
    │                                        +nav-flash-blink-cursor
    │                                                  │
    │                                                  ▼
    └─ advice (evil-window-top等) ─────────▶ nav-flash-show
                                                       │
                                                       ▼
                                            compilation-highlight-overlay
                                            (行ハイライト表示)
```

### データフロー図

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

ジャンプイベント ───▶ +nav-flash-blink-cursor-maybe ───▶ オーバーレイ表示
                              │
                              ├─ this-command チェック
                              ├─ major-mode チェック
                              └─ 前回位置チェック

(selected-window)  ───▶ nav-flash-show ───▶ compilation-highlight-overlay
(current-buffer)                                   │
(point)                                            ▼
                                          行ハイライト(一時的)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/nav-flash/config.el` | ソース | 設定定義、フック/advice登録 |
| autoload.el | `modules/ui/nav-flash/autoload.el` | ソース | フラッシュ処理の実装 |
| packages.el | `modules/ui/nav-flash/packages.el` | 設定 | nav-flashパッケージの依存定義 |
| README.org | `modules/ui/nav-flash/README.org` | ドキュメント | モジュール説明書 |
| .doommodule | `modules/ui/nav-flash/.doommodule` | 設定 | Doomモジュールメタデータ |
