# 機能設計書 25-IME対応

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「IME対応」機能の設計を記述する。IME（Input Method Editor）対応は、日本語、中国語、韓国語などの多バイト文字入力をサポートするための機能であり、プラットフォームネイティブのIMEと連携して、変換候補表示や未確定文字列（プリエディット）の処理を行う。

### 本機能の処理概要

**業務上の目的・背景**：
グローバルなユーザーベースを持つターミナルエミュレータにとって、非ASCII文字の入力サポートは必須機能である。特に東アジア言語圏のユーザーは、IMEを使用した文字入力を日常的に行う。IME対応機能により、Ghosttyは日本語、中国語、韓国語などの複雑な入力システムをシームレスにサポートし、これらの言語を使用するユーザーの生産性を確保する。

**機能の利用シーン**：
- 日本語入力（ローマ字変換、かな入力）
- 中国語入力（ピンイン入力、注音入力）
- 韓国語入力（ハングル入力）
- 絵文字入力（OS絵文字パレット経由）

**主要な処理内容**：
1. プラットフォームIMEイベントの受信
2. プリエディット文字列（未確定文字列）の管理
3. プリエディット文字列のレンダリング（カーソル位置にオーバーレイ）
4. 確定文字列のPTY送信
5. IME候補ウィンドウの位置調整

**関連システム・外部連携**：
- macOS: NSTextInputClient / TextInputContext
- GTK: GtkIMContext
- レンダラー（プリエディット描画）

**権限による制御**：
本機能に特別な権限制御はない。OSのIME設定に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | IME入力、プリエディット表示 |
| 2 | クイックターミナル | 主画面 | 同上 |

## 機能種別

入力処理 / レンダリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| preedit | []const u8 | No | プリエディット文字列（UTF-8） | 有効なUTF-8 |
| committed | []const u8 | No | 確定文字列（UTF-8） | 有効なUTF-8 |
| cursor_pos | usize | No | プリエディット内カーソル位置 | preedit長以下 |

### 入力データソース

- プラットフォームIMEからのコールバック

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| preedit_display | []const u8 | 表示用プリエディット文字列 |
| cursor_rect | Rect | IME候補ウィンドウ配置用矩形 |

### 出力先

- レンダラー（プリエディットオーバーレイ）
- PTY（確定文字列）
- OS（候補ウィンドウ位置）

## 処理フロー

### 処理シーケンス

```
1. IMEアクティベーション
   └─ ユーザーがIME入力を開始

2. プリエディット更新
   └─ 未確定文字列の受信
   └─ レンダラーへの通知（dirty.preedit = true）

3. プリエディット描画
   └─ カーソル位置にオーバーレイ表示

4. 確定処理
   └─ 確定文字列の受信
   └─ PTYへのUTF-8送信
   └─ プリエディットクリア
```

### フローチャート

```mermaid
flowchart TD
    A[IME入力開始] --> B[プリエディット更新]
    B --> C[dirty.preedit = true]
    C --> D[レンダラーへ通知]
    D --> E[プリエディット描画]

    F[確定キー押下] --> G[確定文字列受信]
    G --> H[UTF-8エンコード]
    H --> I[PTY送信]
    I --> J[プリエディットクリア]

    K[ESC/取消] --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-1 | プリエディット表示位置 | 現在のカーソル位置にオーバーレイ表示 | プリエディット存在時 |
| BR-25-2 | 確定文字列エンコード | UTF-8でPTYに送信 | 確定時 |
| BR-25-3 | Dirty flag | preedit変更時にdirty.preeditをtrueに | プリエディット更新時 |

### 計算ロジック

該当なし

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効なUTF-8 | IMEから無効なUTF-8を受信 | ログ出力、入力を無視 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- プリエディット更新: 60fps以上のレンダリング
- 確定文字列送信: 即時

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

- IME入力はパスワード入力時にも使用される可能性があるが、セキュア入力モード（機能No.77）との連携で保護可能

## 備考

- IME対応はプラットフォームネイティブの機能に依存
- macOSとGTKで異なる実装が必要

---

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

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

### 推奨読解順序

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

プリエディット関連のデータ構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Terminal.zig | `src/terminal/Terminal.zig` | Dirty structのpreeditフィールド（163-164行目） |
| 1-2 | State.zig | `src/renderer/State.zig` | レンダラー状態でのpreedit管理 |

**読解のコツ**: dirty.preeditフラグがどのタイミングでtrueに設定されるかを追跡する。

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

IMEイベントの受信処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | embedded.zig | `src/apprt/embedded.zig` | 組み込みランタイムでのIME処理 |

**主要処理フロー**:
1. プラットフォームからのIMEコールバック受信
2. preedit文字列の更新
3. レンダラーへのdirty通知

#### Step 3: レンダリングを理解する

プリエディットの描画処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | generic.zig | `src/renderer/generic.zig` | レンダラーでのpreedit描画 |
| 3-2 | cursor.zig | `src/renderer/cursor.zig` | カーソル位置でのオーバーレイ |

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

```
OS IME
    │
    ├─ [macOS] NSTextInputClient
    │      │
    │      └─ insertText() / setMarkedText()
    │
    └─ [GTK] GtkIMContext
           │
           └─ commit / preedit-changed シグナル
                  │
                  ▼
           Surface.imeCallback()
                  │
                  ├─ preedit更新
                  │      └─ dirty.preedit = true
                  │
                  └─ commit処理
                         └─ PTY送信
```

### データフロー図

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

IMEプリエディット ────▶ Surface.preedit更新 ────▶ dirty.preedit = true
                              │
                              ▼
                      レンダラー通知 ────▶ プリエディット描画
                                                  │
                                                  ▼
                                          カーソル位置オーバーレイ

IME確定 ────────────▶ UTF-8エンコード ────▶ PTY送信
                              │
                              ▼
                      preeditクリア ────▶ dirty.preedit = true
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Terminal.zig | `src/terminal/Terminal.zig` | ソース | Dirty.preeditフラグ定義 |
| embedded.zig | `src/apprt/embedded.zig` | ソース | 組み込みランタイムIME処理 |
| State.zig | `src/renderer/State.zig` | ソース | レンダラー状態管理 |
| generic.zig | `src/renderer/generic.zig` | ソース | 汎用レンダラー実装 |
| Surface.zig | `src/Surface.zig` | ソース | Surface状態管理 |
