# 機能設計書 82-カーソルスタイル

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるカーソルスタイル機能の設計仕様を記載する。

### 本機能の処理概要

カーソルスタイル機能は、ターミナル画面上のテキストカーソルの視覚的な形状（ブロック、アンダーライン、バー）およびブリンク（点滅）動作を制御する機能である。

**業務上の目的・背景**：
ターミナルユーザーにとって、カーソルは現在の入力位置を示す重要なUI要素である。ユーザーの好みや視認性の要件に応じてカーソルの形状や点滅を変更できることで、作業効率と視覚的快適性を向上させる。また、vimやemacsなどのエディタとの連携で、モード（挿入/通常モード）に応じたカーソル変更をサポートする。

**機能の利用シーン**：
- ユーザーが好みのカーソル形状を設定ファイルで指定する場合
- アプリケーション（vim等）がDECSCUSR（カーソル形状変更シーケンス）を送信してカーソル形状を動的に変更する場合
- パスワード入力時にロック型カーソルに自動切替する場合
- ウィンドウフォーカスが外れた際に中空ブロックカーソルに切り替える場合

**主要な処理内容**：
1. 設定ファイルからカーソルスタイルとブリンク設定を読み取る
2. ターミナルからのDECSCUSRエスケープシーケンスを処理する
3. レンダラーでカーソルを描画する
4. フォーカス状態やIME状態に応じてカーソル表示を調整する

**関連システム・外部連携**：
- DECSCUSRエスケープシーケンス（CSI ? q）
- ターミナルモード12（カーソルブリンク）
- IME（入力メソッドエディタ）プリエディット状態

**権限による制御**：
特に権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | カーソル形状（ブロック、アンダーライン、バー）の表示 |

## 機能種別

表示処理 / 視覚効果 / ユーザー設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cursor-style | CursorStyle | No | カーソルの形状 | block, bar, underline, block_hollow |
| cursor-style-blink | bool | No | カーソルの点滅有無 | true/false |
| cursor-color | Color | No | カーソルの色 | RGB値またはカラー名 |
| cursor-text | Color | No | カーソル上のテキスト色 | RGB値またはカラー名 |

### 入力データソース

- 設定ファイル（`~/.config/ghostty/config`等）
- DECSCUSRエスケープシーケンス（アプリケーションからの動的変更）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| カーソル描画 | 視覚表示 | 指定された形状でカーソルを描画 |

### 出力先

ターミナルレンダリング画面

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ 設定ファイルからカーソルスタイルを読み込み
2. レンダリング判定
   └─ RenderState から現在のカーソル状態を取得
3. スタイル決定
   ├─ プリエディット中: block
   ├─ パスワード入力中: lock
   ├─ 非フォーカス時: block_hollow
   ├─ ブリンク非表示時: null (描画しない)
   └─ 通常時: ターミナル指定のスタイル
4. カーソル描画
   └─ 決定されたスタイルでカーソルをレンダリング
```

### フローチャート

```mermaid
flowchart TD
    A[レンダリング開始] --> B{カーソルがビューポート内?}
    B -->|No| C[カーソル描画なし]
    B -->|Yes| D{プリエディット中?}
    D -->|Yes| E[block カーソル]
    D -->|No| F{パスワード入力中?}
    F -->|Yes| G[lock カーソル]
    F -->|No| H{カーソル表示設定?}
    H -->|非表示| C
    H -->|表示| I{フォーカスあり?}
    I -->|No| J[block_hollow カーソル]
    I -->|Yes| K{ブリンク && 非表示期間?}
    K -->|Yes| C
    K -->|No| L[設定スタイルでカーソル描画]
    E --> M[終了]
    G --> M
    J --> M
    L --> M
    C --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | プリエディット優先 | IMEプリエディット中は常にblockカーソル | IME使用時 |
| BR-82-02 | パスワードロック | シェル統合でパスワード入力検出時はlockカーソル | パスワード入力時 |
| BR-82-03 | フォーカス判定 | 非フォーカス時は常にblock_hollowカーソル | ウィンドウ非フォーカス時 |
| BR-82-04 | ブリンク制御 | ブリンク有効かつ非表示期間中はカーソル非表示 | ブリンク有効時 |

### 計算ロジック

カーソルスタイルはDECSCUSRの値に対応：
- 1, 2: block（1: ブリンクあり、2: ブリンクなし）
- 3, 4: underline
- 5, 6: bar

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | 不正なDECSCUSR値 | デフォルトスタイルを使用 |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- カーソルブリンクはレンダラーのフレームレートに同期
- ブリンク間隔は設定可能

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

- パスワード入力検出時は自動的にlock型カーソルに切り替わり、視覚的フィードバックを提供

## 備考

- block_hollow（中空ブロック）はDECSCUSRでは直接指定できないGhostty独自のスタイル
- DECSCUSR問い合わせ時はblock_hollowはblock（1または2）として報告される

---

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

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

### 推奨読解順序

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

まず、カーソルスタイルの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cursor.zig (terminal) | `src/terminal/cursor.zig` | ターミナル側のカーソルStyle enum定義 |
| 1-2 | cursor.zig (renderer) | `src/renderer/cursor.zig` | レンダラー側のカーソルStyle enum定義 |

**読解のコツ**: ターミナル側（terminal/cursor.zig）とレンダラー側（renderer/cursor.zig）で別々のStyle enumがあり、レンダラー側にはlockやblock_hollowなど追加のスタイルがある。

**主要処理フロー**:
- **terminal/cursor.zig 4-15行目**: Style enum（bar, block, underline, block_hollow）
- **renderer/cursor.zig 7-15行目**: Style enum（block, block_hollow, bar, underline, lock）

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

レンダリング時のカーソルスタイル決定ロジック。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cursor.zig (renderer) | `src/renderer/cursor.zig` | style関数（36-68行目）がカーソルスタイルを決定 |

**主要処理フロー**:
- **44-45行目**: ビューポート外判定
- **48-50行目**: プリエディット中はblockカーソル
- **52-53行目**: パスワード入力中はlockカーソル
- **55-56行目**: カーソル非表示設定時はnull
- **58-60行目**: 非フォーカス時はblock_hollow
- **62-64行目**: ブリンク非表示期間中はnull
- **66-67行目**: 通常時はターミナル指定のスタイル

#### Step 3: 設定の読み込みを理解する

設定ファイルからのカーソル設定読み込み。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Config.zig | `src/config/Config.zig` | cursor-style, cursor-style-blink設定 |

**主要処理フロー**:
- **49行目**: CursorStyle型のインポート（terminal/cursor.zigから）

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

```
Config.zig (設定読み込み)
    │
    ├─ cursor-style → terminal.CursorStyle
    │
    └─ cursor-style-blink → bool
           │
           ▼
    Terminal.zig (ターミナル状態管理)
           │
           ├─ screens.active.cursor.cursor_style
           │
           └─ modes.cursor_blinking
                  │
                  ▼
           RenderState (レンダリング状態)
                  │
                  ▼
           renderer/cursor.zig#style()
                  │
                  ├─ プリエディット判定
                  ├─ パスワード入力判定
                  ├─ フォーカス判定
                  ├─ ブリンク判定
                  │
                  ▼
           レンダラー (Metal/OpenGL/WebGL)
                  │
                  ▼
           カーソル描画
```

### データフロー図

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

設定ファイル ───▶ Config.zig ───▶ cursor-style値
                      │
                      ▼
DECSCUSR ────────▶ Terminal.zig ───▶ cursor_style状態
シーケンス                │
                         ▼
              RenderState更新
                         │
                         ▼
              renderer/cursor.zig#style()
                         │
                         ▼
              スタイル決定ロジック
                         │
                         ▼
              レンダラー ───▶ カーソル描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cursor.zig | `src/terminal/cursor.zig` | ソース | ターミナル側カーソルスタイル定義 |
| cursor.zig | `src/renderer/cursor.zig` | ソース | レンダラー側カーソルスタイル決定ロジック |
| Config.zig | `src/config/Config.zig` | ソース | カーソル関連設定の定義 |
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | ターミナル状態管理（カーソル状態含む） |
| Screen.zig | `src/terminal/Screen.zig` | ソース | スクリーンのカーソル位置管理 |
| generic.zig | `src/renderer/generic.zig` | ソース | 汎用レンダラーでのカーソル描画 |
| render.zig | `src/terminal/render.zig` | ソース | ターミナルレンダリング状態 |
