# 機能設計書 56-Vtermターミナル（高速）

## 概要

本ドキュメントは、Doom Emacsの`term/vterm`モジュールが提供するVtermターミナル機能の設計仕様を記述する。libvtermを使用したネイティブターミナルエミュレーションにより、フルスクリーンのTUIアプリケーション（vim、htop、tmux等）を高速かつ正確に動作させることができる。

### 本機能の処理概要

**業務上の目的・背景**：Eshellは純粋なEmacs Lispで実装されているため、フルスクリーンのTUIアプリケーションには対応できない。VtermはCで実装されたlibvtermライブラリを使用することで、完全なVT100/xterm互換ターミナルエミュレーションを提供し、tmuxやvim、htopなどのTUIアプリケーションを正常に動作させる。パフォーマンスもネイティブターミナルに近いレベルを実現する。

**機能の利用シーン**：
- フルスクリーンTUIアプリケーションの実行（htop、vim、tmux等）
- 高速なターミナル出力が必要な場面
- ネイティブターミナルに近い体験が必要な場面
- プロジェクトルートでのシェル操作

**主要な処理内容**：
1. libvtermによるネイティブターミナルエミュレーション
2. プロジェクトルートでの自動起動
3. ワークスペース（persp-mode）連携
4. ポップアップウィンドウとしての表示
5. バッファ終了時の自動クリーンアップ

**関連システム・外部連携**：
- vterm（libvtermラッパー）
- libvterm（Cライブラリ）
- cmake、make（ビルドツール）
- persp-mode（ワークスペース管理）

**権限による制御**：特になし。すべてのユーザーが利用可能。ただし、動的モジュールサポート付きのEmacsビルドが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Vtermバッファ | 主画面 | ターミナル入出力 |

## 機能種別

ターミナルエミュレーション / 外部プログラム連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| arg | prefix | No | プロジェクトルートまたはカレントディレクトリの選択 | C-u プレフィックス |

### 入力データソース

- ユーザーのキーボード入力
- シェルからの出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ターミナル出力 | string | シェルコマンドの実行結果 |
| TUI画面 | buffer | フルスクリーンTUIアプリの表示 |

### 出力先

- `*vterm*`バッファまたはポップアップバッファ

## 処理フロー

### 処理シーケンス

```
1. Vterm起動要求
   └─ +vterm/toggle または +vterm/here
2. 動的モジュールチェック
   └─ module-load関数の存在確認
3. vterm-module.soの読み込み
   └─ 未コンパイルの場合は自動ビルド
4. vterm-modeの有効化
   └─ フック実行、ポップアップ設定
5. シェル起動
   └─ default-directoryまたはプロジェクトルートで起動
```

### フローチャート

```mermaid
flowchart TD
    A[+vterm/toggle] --> B{dynamic modules?}
    B -->|No| C[user-error]
    B -->|Yes| D{バッファ存在?}
    D -->|Yes| E[バッファ表示/削除]
    D -->|No| F[新規バッファ作成]
    F --> G{vterm-module?}
    G -->|No| H[自動ビルド]
    G -->|Yes| I[vterm-mode有効化]
    H --> I
    I --> J[シェル起動]
    J --> K[ターミナル操作]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-01 | バッファ終了時削除 | vtermプロセス終了時にバッファも削除 | vterm-kill-buffer-on-exit t |
| BR-56-02 | スクロールバック | 5000行のスクロールバック履歴を保持 | vterm-max-scrollback 5000 |
| BR-56-03 | ポップアップサイズ | 画面の25%の高さでポップアップ表示 | set-popup-rule! |
| BR-56-04 | プロセス確認無効 | vterm終了時にプロセス確認を表示しない | confirm-kill-processes nil |

### 計算ロジック

- プロジェクトルート取得: `doom-project-root`
- 環境変数PROOT: プロジェクトルートを設定

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 動的モジュール非対応 | Emacsが動的モジュールなしでビルド | user-errorで通知 |
| - | ビルドツール不足 | makeまたはcmakeが未インストール | doctor.elで警告 |
| - | コンパイルエラー | vterm-moduleのビルド失敗 | ビルドログを確認 |

### リトライ仕様

ビルド失敗時は手動でのリトライが必要。

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

トランザクション処理は不要。

## パフォーマンス要件

- ターミナル出力: ネイティブターミナルに近いパフォーマンス
- TUIアプリケーション: 60fps相当のリフレッシュレート

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

- vterm-module.soはローカルでコンパイルされるため、信頼性が担保される

## 備考

- Emacsの動的モジュールサポートが必要（`--with-modules`オプションでビルド）
- cmakeとmakeが必要
- Eshellと比較して完全なターミナルエミュレーションを提供

---

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

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

### 推奨読解順序

#### Step 1: 基本設定を理解する

まず、vtermの基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/term/vterm/config.el` | use-package設定（3-33行目） |

**読解のコツ**: `bound-and-true-p module-file-suffix`で動的モジュールサポートをチェック。

**主要処理フロー**:
1. **4行目**: 動的モジュールサポートの条件チェック
2. **6-7行目**: vtermモードフック設定
3. **18行目**: ポップアップルール設定
4. **24行目**: バッファ終了時の自動削除
5. **27行目**: スクロールバック行数設定

#### Step 2: コマンド定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | autoload.el | `modules/term/vterm/autoload.el` | コマンド定義（6-76行目） |

**主要処理フロー**:
- **6-42行目**: `+vterm/toggle`でポップアップ表示
- **45-60行目**: `+vterm/here`で現在ウィンドウに表示
- **62-76行目**: `+vterm--configure-project-root-and-display`でプロジェクトルート設定

#### Step 3: 診断ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doctor.el | `modules/term/vterm/doctor.el` | 診断チェック（1-11行目） |

**主要処理フロー**:
- **3-4行目**: makeコマンドの存在確認
- **6-7行目**: cmakeコマンドの存在確認
- **9-10行目**: 動的モジュールサポートの確認

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

```
+vterm/toggle
    │
    ├─ +vterm--configure-project-root-and-display
    │      │
    │      ├─ doom-project-root
    │      │
    │      └─ setenv "PROOT"
    │
    ├─ get-buffer-create
    │
    ├─ vterm-mode
    │      │
    │      ├─ doom-mark-buffer-as-real-h
    │      │
    │      └─ hide-mode-line-mode
    │
    └─ pop-to-buffer

+vterm/here
    │
    ├─ +vterm--configure-project-root-and-display
    │
    └─ vterm (built-in command)
```

### データフロー図

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

キー入力 ───▶ vterm-mode ───▶ libvterm ───▶ ターミナル出力
                  │
                  ▼
              vterm-module.so
                  │
                  ▼
              シェルプロセス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/term/vterm/config.el` | ソース | メイン設定 |
| packages.el | `modules/term/vterm/packages.el` | 設定 | 依存パッケージ定義 |
| autoload.el | `modules/term/vterm/autoload.el` | ソース | コマンド定義 |
| doctor.el | `modules/term/vterm/doctor.el` | 診断 | ビルドツール確認 |
