# 機能設計書 53-フォント確認

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータのフォント確認機能(`+show-face`コマンド)の設計仕様を記載する。

### 本機能の処理概要

フォント確認機能は、特定のコードポイントがどのフォントフェイスから読み込まれるかを表示するCLIコマンドである。Unicodeの特定の文字がどのフォントでレンダリングされるかをデバッグする際に使用される。

**業務上の目的・背景**：ターミナルエミュレータでは多様なUnicode文字を表示する必要があり、複数のフォントがフォールバックチェーンを形成する。特定の文字が意図したフォントで表示されているかを確認することは、フォント設定のデバッグや最適化において重要である。Nerd FontsやCJK文字など、特殊なグリフの表示確認に特に有用。

**機能の利用シーン**：
- 特定の文字がどのフォントで表示されているか確認したい場合
- フォントフォールバックの動作を確認したい場合
- Nerd Fontsのアイコンが正しく表示されるか検証したい場合
- 絵文字やCJK文字のフォント割り当てを確認したい場合

**主要な処理内容**：
1. コマンドライン引数の解析（`--cp`、`--string`、`--style`、`--presentation`オプション）
2. 設定のロードとフォントグリッドの初期化
3. 各コードポイントについてフォントルックアップを実行
4. 結果の出力（フォント名または特殊ハンドリング情報）

**関連システム・外部連携**：システムフォント、設定ファイル

**権限による制御**：特になし。全ユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主機能 | コマンドライン実行によるフォント情報表示 |

## 機能種別

CLI操作 / 情報表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --cp | u21 | No* | 検索対象のコードポイント。10進数、16進数(0x)、8進数(0o)、2進数(0b)で指定可能 | 有効なUnicodeコードポイント |
| --string | 文字列 | No* | 検索対象の文字列。各コードポイントについて検索 | 有効なUTF-8シーケンス |
| --style | enum | No | フォントスタイル（regular, bold, italic, bold_italic）。デフォルト: regular | 列挙値のいずれか |
| --presentation | enum | No | プレゼンテーション強制（text, emoji）。未指定時はUnicode標準に従う | 列挙値のいずれか |

*注: --cpまたは--stringのいずれかは必須

### 入力データソース

- コマンドライン引数
- 設定ファイル（フォント設定の読み込み）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コードポイント情報 | テキスト | U+XXXX形式のコードポイントと文字、およびフォント名 |

### 出力先

- 標準出力（stdout）: 検索結果
- 標準エラー出力（stderr）: エラーメッセージ

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ Options構造体に各オプション値を設定
2. 入力検証
   └─ --cpまたは--stringのいずれかが指定されているか確認
3. 設定のロード
   └─ Config.load()でフォント設定を含む設定をロード
4. フォントグリッドの初期化
   └─ SharedGridSet、DerivedConfigを初期化
5. コードポイントごとにルックアップ
   └─ resolver.getIndex()でフォントインデックスを取得
   └─ collection.getFace()でフォントフェイスを取得
6. 結果の出力
   └─ フォント名、または特殊スプライト/未発見の情報を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数解析]
    B --> C{--cp or --string指定?}
    C -->|No| D[エラー: 必須引数なし]
    D --> E[終了コード1]
    C -->|Yes| F[Config.load]
    F --> G[フォントグリッド初期化]
    G --> H{--cp指定?}
    H -->|Yes| I[単一コードポイント検索]
    H -->|No| J{--string指定?}
    J -->|Yes| K[文字列の各コードポイント検索]
    I --> L[lookup関数実行]
    K --> L
    L --> M{フォント発見?}
    M -->|Yes| N[フォント名出力]
    M -->|No| O{内部スプライト?}
    O -->|Yes| P[スプライト情報出力]
    O -->|No| Q[未発見メッセージ出力]
    N --> R[終了コード0]
    P --> R
    Q --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-1 | 必須入力 | --cpまたは--stringのいずれかが必須 | 常時 |
| BR-53-2 | プレゼンテーション推論 | --presentation未指定時はUnicode標準に基づいてtext/emojiを決定 | --presentation未指定時 |
| BR-53-3 | グラフェムクラスタリング非考慮 | 結果はグラフェムクラスタリングを考慮しないため、実際の表示と異なる場合がある | 常時 |

### 計算ロジック

特になし

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

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

データベース操作なし（読み取り専用のCLIコマンド）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 必須引数なし | --cpも--stringも指定されていない | いずれかのオプションを指定 |
| 1 | 設定ロードエラー | 設定ファイルの読み込みに失敗 | 設定ファイルを確認 |
| 1 | フォントグリッド初期化エラー | フォントシステムの初期化に失敗 | フォント設定を確認 |
| - | フォント未発見 | 指定コードポイントのフォントがない | フォント設定を追加 |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

即座にレスポンスが返ること（通常1秒未満）

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

特になし

## 備考

- グラフェムクラスタリングやその他のUnicode機能は考慮されないため、実際のターミナル表示とは異なる場合がある
- Ghosttyの内部スプライトでハンドリングされるコードポイントは特別なメッセージで表示される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | show_face.zig | `src/cli/show_face.zig` | Options構造体（11-41行目）でCLIオプションを定義 |

**読解のコツ**: font.StyleやPresentation型はfontモジュールで定義されており、フォントシステムの型を理解するのに役立つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | show_face.zig | `src/cli/show_face.zig` | run関数（64-85行目）がエントリーポイント |

**主要処理フロー**:
1. **65-66行目**: argsIteratorの取得
2. **68-74行目**: stdout/stderrのwriter準備
3. **76-84行目**: runArgs関数の呼び出しと結果のフラッシュ

#### Step 3: 検索ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show_face.zig | `src/cli/show_face.zig` | runArgs関数（87-203行目）でメイン処理 |
| 3-2 | show_face.zig | `src/cli/show_face.zig` | lookup関数（205-239行目）で単一コードポイントの検索 |

**主要処理フロー**:
- **94-103行目**: フォントディスカバリ未サポート時のエラー処理
- **138-141行目**: --cpも--stringも未指定時のエラー
- **143-147行目**: Config.load()で設定をロード
- **162-186行目**: フォントグリッドの初期化
- **188-200行目**: コードポイントごとのlookup実行
- **214-217行目**: resolver.getIndex()でフォントインデックス取得
- **219-228行目**: collection.getFace()でフォントフェイス取得

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

```
ghostty +show-face
    │
    └─ show_face.run()
           │
           └─ runArgs()
                  │
                  ├─ args.parse() ─ オプション解析
                  │
                  ├─ Config.load() ─ 設定ロード
                  │
                  ├─ SharedGridSet.init() ─ フォントグリッド初期化
                  │
                  ├─ SharedGridSet.ref() ─ フォントグリッド参照取得
                  │
                  └─ lookup()
                         │
                         ├─ resolver.getIndex() ─ フォントインデックス取得
                         │
                         └─ collection.getFace() ─ フォントフェイス取得
                                │
                                └─ face.name() ─ フォント名取得
```

### データフロー図

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

コマンドライン ───▶ args.parse() ───────▶ Options
引数                                     (cp, string, style, presentation)

設定ファイル ───▶ Config.load() ─────▶ フォント設定
                         │
                         ▼
                  SharedGridSet.init()
                         │
                         ▼
コードポイント ───▶ lookup()
                         │
                         ├─▶ 「found in face "..."」
                         ├─▶ 「handled by internal sprites」
                         └─▶ 「not found」
                                          ▼
                                     標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show_face.zig | `src/cli/show_face.zig` | ソース | メインエントリーポイント |
| font/main.zig | `src/font/main.zig` | ソース | フォントモジュールエントリー |
| font/SharedGridSet.zig | `src/font/SharedGridSet.zig` | ソース | フォントグリッド管理 |
| Config.zig | `src/config/Config.zig` | ソース | 設定データ構造 |
| args.zig | `src/cli/args.zig` | ソース | コマンドライン引数解析 |
