# 機能設計書 8-SGR属性

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける太字、斜体、下線、取消線、点滅、反転などの文字属性に対応する「SGR属性」機能の設計を記述する。

### 本機能の処理概要

SGR（Select Graphic Rendition）属性機能は、CSI mシーケンスで指定された文字属性を解析し、セルに適用する。太字、斜体、下線（複数スタイル）、オーバーライン、点滅、反転、不可視、取消線などの属性をサポートし、前景色/背景色の設定も含む。

**業務上の目的・背景**：テキストの視覚的な強調は情報の読みやすさと理解を助ける。エラーメッセージの強調、重要なテキストのハイライト、コードのシンタックスハイライトなど、文字属性は端末の表現力を大きく向上させる。

**機能の利用シーン**：
- シェルがエラーメッセージを太字赤で表示する場面
- manページが見出しを太字、オプションを下線で表示する場面
- シンタックスハイライトでキーワードを色分け+太字で表示する場面
- gitがdiffを色と属性で強調表示する場面

**主要な処理内容**：
1. CSI mシーケンスのパラメータ解析
2. 各SGR属性の適用/リセット
3. 前景色/背景色の設定（8色、256色、True Color）
4. 下線スタイル（single、double、curly、dotted、dashed）の管理
5. 下線色の独立設定

**関連システム・外部連携**：
- VTパーサーとの連携
- カラー処理との連携
- スタイル管理との連携

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 太字、斜体、下線、取消線、点滅、反転などの文字属性表示 |

## 機能種別

データ処理 / 表示制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params | []const u16 | Yes | CSI mのパラメータ列 | 有効なSGRコード |
| params_sep | SepList | No | セパレータ情報（コロン対応） | - |

### 入力データソース

- CSI mエスケープシーケンス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| attribute | Attribute | 解析されたSGR属性 |

### 出力先

- セルのスタイル情報

## 処理フロー

### 処理シーケンス

```
1. CSI m受信
   └─ パラメータ列を取得

2. SGRパーサー初期化
   └─ Parser構造体にparams設定

3. 属性イテレーション
   └─ Parser.next()で次の属性を取得
   └─ 属性タイプに応じた処理

4. 属性適用
   └─ bold/italic/underline等を設定
   └─ 色指定を処理（8色/256色/True Color）

5. リセット処理
   └─ SGR 0で全属性リセット
   └─ 個別リセットコードで部分リセット
```

### フローチャート

```mermaid
flowchart TD
    A[CSI m受信] --> B[Parserにparams設定]
    B --> C[Parser.next]
    C --> D{属性あり?}
    D -->|Yes| E{属性タイプ}
    D -->|No| F[終了]

    E -->|unset| G[全属性リセット]
    E -->|bold| H[太字設定]
    E -->|italic| I[斜体設定]
    E -->|underline| J[下線設定]
    E -->|direct_color| K[True Color設定]
    E -->|256_color| L[256色設定]
    E -->|8_color| M[8色設定]

    G --> C
    H --> C
    I --> C
    J --> C
    K --> C
    L --> C
    M --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SGR 0 | 全属性をリセット | params空またはSGR 0 |
| BR-002 | 複数パラメータ | セミコロン区切りで複数属性を一度に設定 | CSI m実行時 |
| BR-003 | コロン区切り | 下線スタイル等でコロン区切りをサポート（38:2:r:g:b等） | mコマンドのみ |
| BR-004 | 下線色独立 | 下線色は前景色とは独立して設定可能 | SGR 58/59 |

### 計算ロジック

- SGR 38;5;n: 256色前景
- SGR 48;5;n: 256色背景
- SGR 38;2;r;g;b: True Color前景
- SGR 48;2;r;g;b: True Color背景

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-001 | 不明なSGRコード | 未定義のSGR番号 | unknownとして処理 |

### リトライ仕様

リトライ機構は使用しない。

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

トランザクション処理は使用しない。

## パフォーマンス要件

- 属性解析: O(n) - nはパラメータ数

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

特になし。

## 備考

- 下線スタイルはKitty拡張でサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sgr.zig | `src/terminal/sgr.zig` | Attribute union、Tag enum |
| 1-2 | sgr.zig | `src/terminal/sgr.zig` | Underline enum（下線スタイル） |

**読解のコツ**: `Attribute`はタグ付きunionで、各SGR属性タイプを表現。`Tag`は属性タイプのenum。

#### Step 2: パーサーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sgr.zig | `src/terminal/sgr.zig` | Parser構造体 |
| 2-2 | sgr.zig | `src/terminal/sgr.zig` | Parser.next()メソッド |

**主要処理フロー**:
- **14-173行目**: Attribute union - 各属性タイプの定義
- **120-143行目**: Unknown構造体 - 未知のSGRパラメータ処理
- **144-157行目**: Underline enum - 5種類の下線スタイル
- **176-200行目**: Parser.next() - 次の属性を返す

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

```
SGR処理
    |
    +-- Parser初期化
    |      +-- params設定
    |      +-- params_sep設定
    |
    +-- Parser.next() [ループ]
    |      +-- idx >= len? → return null
    |      +-- params[idx]を解析
    |      +-- Attribute生成
    |
    +-- Attribute処理
           +-- unset → スタイルリセット
           +-- bold/italic等 → フラグ設定
           +-- direct_color → RGB設定
           +-- 256_color → パレット参照
```

### データフロー図

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

CSI m params ────────> Parser.init()
                           |
                           v
                    Parser.next() [イテレート]
                           |
                           v
                    Attribute ─────────> セルスタイル
                           |
                           v
                    レンダラーで表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sgr.zig | `src/terminal/sgr.zig` | ソース | SGR属性解析のメインロジック |
| style.zig | `src/terminal/style.zig` | ソース | スタイル構造体 |
| color.zig | `src/terminal/color.zig` | ソース | カラー処理 |
| Parser.zig | `src/terminal/Parser.zig` | ソース | CSI mをSGRに渡す |
