# 帳票設計書 9-show-face

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `show-face` コマンドが出力するフォントフェイス情報の設計書です。

### 本帳票の処理概要

`show-face` コマンドは、指定されたコードポイントまたは文字列のレンダリングに使用されるフォントフェイス情報を標準出力に表示するCLIレポートです。

**業務上の目的・背景**：ユーザーが特定の文字がどのフォントでレンダリングされるかを確認し、フォント設定のデバッグやフォントフォールバックの動作確認を行えるようにします。絵文字や特殊文字が期待通りに表示されない場合の原因調査に役立ちます。

**帳票の利用シーン**：
- 特定の文字がどのフォントで表示されるか確認
- フォントフォールバックの動作確認
- 絵文字の表示問題のデバッグ
- フォント設定の検証

**主要な出力内容**：
1. コードポイント（16進数表記）
2. 文字のグリフ表示
3. フォントフェイス名
4. 特殊処理（Ghostty内部スプライト）の通知

**帳票の出力タイミング**：`ghostty +show-face` コマンド実行時

**帳票の利用者**：エンドユーザー、フォント設定をカスタマイズするユーザー、開発者

## 帳票種別

CLIレポート（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +show-face --cp=65` | 単一コードポイント |
| - | CLI | `ghostty +show-face --string="Hello"` | 文字列 |
| - | CLI | `ghostty +show-face --cp=0x1F600` | 絵文字（16進数） |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

各コードポイントにつき1行で、フォントフェイス情報を出力します。

```
┌─────────────────────────────────────┐
│  U+XXXX << char >> found in face "Font Name".  │
│  U+XXXX << char >> not found.                  │
│  U+XXXX << char >> is handled by Ghostty's internal sprites.  │
└─────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | コードポイント | Unicode コードポイント | --cp または --string | "U+{X:0>2}" |
| 2 | 文字グリフ | 対象文字の表示 | Unicode | "<< {u} >>" |
| 3 | フォント名 | 使用されるフォントフェイス名 | font_grid.resolver | "found in face "{s}"." |
| 4 | 未検出通知 | フォントが見つからない場合 | - | "not found." |
| 5 | 内部スプライト通知 | Ghostty内部処理の場合 | - | "is handled by Ghostty's internal sprites." |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --cp | 単一コードポイント（10進/16進/8進/2進対応） | --cpまたは--stringいずれか必須 |
| --string | UTF-8文字列 | --cpまたは--stringいずれか必須 |
| --style | フォントスタイル（regular/bold/italic/bold_italic） | No（デフォルト: regular） |
| --presentation | プレゼンテーションスタイル（text/emoji） | No（自動判定） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | 入力順 | 入力順 |

### 改ページ条件

改ページなし（連続出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| Config.load | フォント設定 | 設定ファイル読み込み |
| font.SharedGridSet | フォントグリッド | フォント解決 |
| font_grid.resolver | フォントフェイス検索 | コードポイント→フォント変換 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | 計算処理なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C{--cpまたは--string指定?}
    C -->|No| D[エラー: コードポイント必須]
    C -->|Yes| E[Config読み込み]
    D --> Z[終了コード1を返却]
    E --> F[font.SharedGridSet初期化]
    F --> G{font.Discover有効?}
    G -->|No| H[エラー: フォント発見機構なし]
    H --> Z
    G -->|Yes| I[font_grid取得]
    I --> J{--cp指定?}
    J -->|Yes| K[単一コードポイント検索]
    J -->|No| L[--string解析]
    K --> M[lookup処理]
    L --> N[各コードポイントをループ]
    N --> M
    M --> O{フォント見つかった?}
    O -->|Yes| P[フォント名出力]
    O -->|No| Q{内部スプライト?}
    Q -->|Yes| R[内部スプライト通知]
    Q -->|No| S[not found出力]
    P --> T{次のコードポイント?}
    R --> T
    S --> T
    T -->|Yes| N
    T -->|No| U[バッファフラッシュ]
    U --> V[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| コードポイント未指定 | --cpも--stringもなし | "You must specify a codepoint with --cp or a string with --string" | 終了コード1 |
| フォント発見機構なし | コンパイル時無効化 | "Ghostty was built without a font discovery mechanism..." | 終了コード1 |
| 設定読み込み失敗 | 設定ファイル不正 | "Unable to load config: {err}" | 終了コード1 |
| Unicode解析失敗 | --stringが不正なUTF-8 | "Unable to parse string as unicode: {err}" | 終了コード1 |
| フォントグリッド初期化失敗 | フォント設定不正 | "Unable to initialize font grid set: {err}" | 終了コード1 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1〜数十文字 |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

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

- フォント設定の読み取り権限が必要
- 出力にはフォント名のみ含まれる
- 機密情報なし

## 備考

- グラフェムクラスタリングは考慮されない（単純なコードポイント単位）
- 実際のターミナルレンダリングとは異なる場合がある
- font-size設定は96DPIで固定

---

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

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

### 推奨読解順序

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

オプションとフォント解決の構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | show_face.zig | `src/cli/show_face.zig` | Options構造体（11-41行目） |
| 1-2 | main.zig | `src/font/main.zig` | font.Style, font.Presentation定義 |

**読解のコツ**: Options構造体の_diagnosticsフィールドは通常の設定オプションとの共存を可能にしています。

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

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

**主要処理フロー**:
1. **94-103行目**: font.Discover有効チェック
2. **105-132行目**: オプション解析と診断処理
3. **138-141行目**: コードポイント/文字列必須チェック
4. **143-147行目**: Config読み込み
5. **162-186行目**: font_grid初期化とフォント検索
6. **188-200行目**: --cp / --string処理分岐

#### Step 3: フォント検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show_face.zig | `src/cli/show_face.zig` | lookup関数（205-239行目） |
| 3-2 | SharedGridSet.zig | `src/font/SharedGridSet.zig` | フォントグリッド管理 |

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ show_face.run (show_face.zig:64)
                  │
                  └─ runArgs (show_face.zig:87)
                         │
                         ├─ args.parse (オプション解析)
                         │
                         ├─ Config.load (設定読み込み)
                         │
                         ├─ font.SharedGridSet.init (グリッド初期化)
                         │
                         ├─ font_grid_set.ref (グリッド取得)
                         │
                         └─ lookup (フォント検索)
                                │
                                ├─ font_grid.resolver.getIndex
                                │
                                └─ font_grid.resolver.collection.getFace
```

### データフロー図

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

--cp/--string ───▶ runArgs()
                      │
                      ▼
              Config.load()
                      │
                      ▼
         font.SharedGridSet.init()
                      │
                      ▼
              font_grid_set.ref()
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
codepoint         style           presentation
(コードポイント)   (スタイル)      (プレゼンテーション)
    │                 │                 │
    └──────────▶ lookup() ◀─────────────┘
                      │
         ┌────────────┼────────────┐
         ▼            ▼            ▼
    フォント名    not found    内部スプライト
         │            │            │
         └────────────┼────────────┘
                      │
                      ▼
                  stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show_face.zig | `src/cli/show_face.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| diagnostics.zig | `src/cli/diagnostics.zig` | ソース | 診断リスト |
| main.zig | `src/font/main.zig` | ソース | フォントモジュールエントリ |
| SharedGridSet.zig | `src/font/SharedGridSet.zig` | ソース | フォントグリッド管理 |
| Config.zig | `src/config/Config.zig` | ソース | 設定管理 |
