# API設計書

## 概要

本ドキュメントは、Ghosttyプロジェクトが提供するC言語APIの設計書です。Ghosttyは高速でネイティブな機能豊富なターミナルエミュレータであり、以下の2つのライブラリAPIを提供しています:

1. **libghostty** - ターミナルエミュレータを3rdパーティアプリケーションに組み込むためのAPI
2. **libghostty-vt** - 仮想端末のパース・エンコーディング機能を提供する軽量API

## 共通仕様

### 対象プラットフォーム

- macOS（Metal レンダラー、SwiftUI アプリケーション）
- Linux（GTK アプリケーション）
- iOS（実験的サポート）
- WebAssembly（libghostty-vt のみ）

### 言語バインディング

| 言語 | 対応状況 |
| --- | --- |
| C | ネイティブサポート |
| Zig | ネイティブ実装 |
| Swift | macOSアプリで使用 |

### 共通型定義

#### 結果コード

| コード | 値 | 説明 |
| --- | --- | --- |
| GHOSTTY_SUCCESS | 0 | 操作成功 |
| GHOSTTY_OUT_OF_MEMORY | -1 | メモリ割り当て失敗 |
| GHOSTTY_INVALID_VALUE | -2 | 無効な値 |

#### 不透明ハンドル型

| 型名 | 説明 |
| --- | --- |
| ghostty_app_t | アプリケーションインスタンス |
| ghostty_config_t | 設定オブジェクト |
| ghostty_surface_t | ターミナルサーフェス |
| ghostty_inspector_t | インスペクタインスタンス |

### メモリ管理

libghostty-vtはカスタムアロケータインターフェース（`GhosttyAllocator`）をサポートしています。NULL を渡すことでデフォルトアロケータ（libc malloc/free）を使用できます。

```c
typedef struct GhosttyAllocator {
    void *ctx;                           // アロケータコンテキスト
    const GhosttyAllocatorVtable *vtable; // 関数テーブル
} GhosttyAllocator;
```

---

## API一覧

### libghostty API

| カテゴリ | 関数名 | 説明 |
| --- | --- | --- |
| 初期化 | ghostty_init | ライブラリ初期化 |
| 初期化 | ghostty_info | ビルド情報取得 |
| 設定 | ghostty_config_new | 設定オブジェクト作成 |
| 設定 | ghostty_config_free | 設定オブジェクト解放 |
| 設定 | ghostty_config_clone | 設定オブジェクト複製 |
| 設定 | ghostty_config_load_cli_args | CLI引数から設定読み込み |
| 設定 | ghostty_config_load_file | ファイルから設定読み込み |
| 設定 | ghostty_config_load_default_files | デフォルト設定ファイル読み込み |
| 設定 | ghostty_config_load_recursive_files | 再帰的に設定ファイル読み込み |
| 設定 | ghostty_config_finalize | 設定確定 |
| 設定 | ghostty_config_get | 設定値取得 |
| アプリ | ghostty_app_new | アプリケーション作成 |
| アプリ | ghostty_app_free | アプリケーション解放 |
| アプリ | ghostty_app_tick | イベントループ処理 |
| アプリ | ghostty_app_set_focus | フォーカス設定 |
| アプリ | ghostty_app_key | キーイベント処理 |
| アプリ | ghostty_app_update_config | 設定更新 |
| サーフェス | ghostty_surface_new | サーフェス作成 |
| サーフェス | ghostty_surface_free | サーフェス解放 |
| サーフェス | ghostty_surface_draw | 描画実行 |
| サーフェス | ghostty_surface_set_size | サイズ設定 |
| サーフェス | ghostty_surface_key | キー入力処理 |
| サーフェス | ghostty_surface_mouse_button | マウスボタン処理 |
| サーフェス | ghostty_surface_mouse_pos | マウス位置更新 |
| サーフェス | ghostty_surface_mouse_scroll | スクロール処理 |
| インスペクタ | ghostty_surface_inspector | インスペクタ取得 |
| インスペクタ | ghostty_inspector_free | インスペクタ解放 |

### libghostty-vt API

| カテゴリ | 関数名 | 説明 |
| --- | --- | --- |
| OSC | ghostty_osc_new | OSCパーサ作成 |
| OSC | ghostty_osc_free | OSCパーサ解放 |
| OSC | ghostty_osc_reset | OSCパーサリセット |
| OSC | ghostty_osc_next | 次バイト処理 |
| OSC | ghostty_osc_end | パース完了 |
| OSC | ghostty_osc_command_type | コマンドタイプ取得 |
| OSC | ghostty_osc_command_data | コマンドデータ取得 |
| SGR | ghostty_sgr_new | SGRパーサ作成 |
| SGR | ghostty_sgr_free | SGRパーサ解放 |
| SGR | ghostty_sgr_reset | SGRパーサリセット |
| SGR | ghostty_sgr_set_params | パラメータ設定 |
| SGR | ghostty_sgr_next | 次属性取得 |
| Key | ghostty_key_event_new | キーイベント作成 |
| Key | ghostty_key_event_free | キーイベント解放 |
| Key | ghostty_key_encoder_new | エンコーダ作成 |
| Key | ghostty_key_encoder_free | エンコーダ解放 |
| Key | ghostty_key_encoder_setopt | オプション設定 |
| Key | ghostty_key_encoder_encode | エンコード実行 |
| Paste | ghostty_paste_is_safe | ペースト安全性確認 |

---

## 各APIエンドポイント定義

### 初期化・情報

#### 1. ghostty_init

ライブラリを初期化します。アプリケーション起動時に一度だけ呼び出します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `int ghostty_init(uintptr_t, char**)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | GHOSTTY_SUCCESS (0) で成功 |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| argc | uintptr_t | コマンドライン引数の数 |
| argv | char** | コマンドライン引数配列 |

---

#### 2. ghostty_info

ライブラリのビルド情報を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `ghostty_info_s ghostty_info(void)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | ghostty_info_s 構造体 |

**戻り値構造体**

```c
typedef struct {
  ghostty_build_mode_e build_mode;  // ビルドモード
  const char* version;              // バージョン文字列
  uintptr_t version_len;            // バージョン文字列長
} ghostty_info_s;
```

---

### 設定管理

#### 3. ghostty_config_new

新しい設定オブジェクトを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `ghostty_config_t ghostty_config_new()` |
| ヘッダ | `ghostty.h` |
| 戻り値 | 設定オブジェクトハンドル |

---

#### 4. ghostty_config_free

設定オブジェクトを解放します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_config_free(ghostty_config_t)` |
| ヘッダ | `ghostty.h` |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| config | ghostty_config_t | 解放する設定オブジェクト |

---

#### 5. ghostty_config_clone

設定オブジェクトを複製します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `ghostty_config_t ghostty_config_clone(ghostty_config_t)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | 複製された設定オブジェクト |

---

#### 6. ghostty_config_load_file

指定ファイルから設定を読み込みます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_config_load_file(ghostty_config_t, const char*)` |
| ヘッダ | `ghostty.h` |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| config | ghostty_config_t | 設定オブジェクト |
| path | const char* | 設定ファイルパス |

---

#### 7. ghostty_config_finalize

設定を確定します。設定の読み込み後、使用前に呼び出す必要があります。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_config_finalize(ghostty_config_t)` |
| ヘッダ | `ghostty.h` |

---

#### 8. ghostty_config_get

設定値を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_config_get(ghostty_config_t, void*, const char*, uintptr_t)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | 取得成功時 true |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| config | ghostty_config_t | 設定オブジェクト |
| out | void* | 値の出力先 |
| key | const char* | 設定キー名 |
| key_len | uintptr_t | キー名の長さ |

---

### アプリケーション管理

#### 9. ghostty_app_new

新しいアプリケーションインスタンスを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `ghostty_app_t ghostty_app_new(const ghostty_runtime_config_s*, ghostty_config_t)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | アプリケーションハンドル |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| runtime_config | ghostty_runtime_config_s* | ランタイムコールバック設定 |
| config | ghostty_config_t | 設定オブジェクト |

**ランタイム設定構造体**

```c
typedef struct {
  void* userdata;
  bool supports_selection_clipboard;
  ghostty_runtime_wakeup_cb wakeup_cb;
  ghostty_runtime_action_cb action_cb;
  ghostty_runtime_read_clipboard_cb read_clipboard_cb;
  ghostty_runtime_confirm_read_clipboard_cb confirm_read_clipboard_cb;
  ghostty_runtime_write_clipboard_cb write_clipboard_cb;
  ghostty_runtime_close_surface_cb close_surface_cb;
} ghostty_runtime_config_s;
```

---

#### 10. ghostty_app_free

アプリケーションを解放します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_app_free(ghostty_app_t)` |
| ヘッダ | `ghostty.h` |

---

#### 11. ghostty_app_tick

アプリケーションのイベントループを1回処理します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_app_tick(ghostty_app_t)` |
| ヘッダ | `ghostty.h` |

---

#### 12. ghostty_app_key

アプリケーションレベルでキーイベントを処理します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_app_key(ghostty_app_t, ghostty_input_key_s)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | イベントが処理された場合 true |

**入力構造体**

```c
typedef struct {
  ghostty_input_action_e action;    // press/release/repeat
  ghostty_input_mods_e mods;        // 修飾キー
  ghostty_input_mods_e consumed_mods;
  uint32_t keycode;                 // キーコード
  const char* text;                 // 生成されたテキスト
  uint32_t unshifted_codepoint;
  bool composing;
} ghostty_input_key_s;
```

---

### サーフェス管理

#### 13. ghostty_surface_new

新しいターミナルサーフェスを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `ghostty_surface_t ghostty_surface_new(ghostty_app_t, const ghostty_surface_config_s*)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | サーフェスハンドル |

**サーフェス設定構造体**

```c
typedef struct {
  ghostty_platform_e platform_tag;
  ghostty_platform_u platform;
  void* userdata;
  double scale_factor;
  float font_size;
  const char* working_directory;
  const char* command;
  ghostty_env_var_s* env_vars;
  size_t env_var_count;
  const char* initial_input;
  bool wait_after_command;
  ghostty_surface_context_e context;
} ghostty_surface_config_s;
```

---

#### 14. ghostty_surface_free

サーフェスを解放します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_surface_free(ghostty_surface_t)` |
| ヘッダ | `ghostty.h` |

---

#### 15. ghostty_surface_draw

サーフェスを描画します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_surface_draw(ghostty_surface_t)` |
| ヘッダ | `ghostty.h` |

---

#### 16. ghostty_surface_set_size

サーフェスのサイズを設定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_surface_set_size(ghostty_surface_t, uint32_t, uint32_t)` |
| ヘッダ | `ghostty.h` |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| surface | ghostty_surface_t | サーフェス |
| width | uint32_t | 幅（ピクセル） |
| height | uint32_t | 高さ（ピクセル） |

---

#### 17. ghostty_surface_key

サーフェスにキー入力を送信します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_surface_key(ghostty_surface_t, ghostty_input_key_s)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | イベントが処理された場合 true |

---

#### 18. ghostty_surface_mouse_button

マウスボタンイベントを処理します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_surface_mouse_button(ghostty_surface_t, ghostty_input_mouse_state_e, ghostty_input_mouse_button_e, ghostty_input_mods_e)` |
| ヘッダ | `ghostty.h` |
| 戻り値 | イベントが処理された場合 true |

---

#### 19. ghostty_surface_mouse_pos

マウス位置を更新します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_surface_mouse_pos(ghostty_surface_t, double, double, ghostty_input_mods_e)` |
| ヘッダ | `ghostty.h` |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| surface | ghostty_surface_t | サーフェス |
| x | double | X座標 |
| y | double | Y座標 |
| mods | ghostty_input_mods_e | 修飾キー |

---

#### 20. ghostty_surface_mouse_scroll

スクロールイベントを処理します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_surface_mouse_scroll(ghostty_surface_t, double, double, ghostty_input_scroll_mods_t)` |
| ヘッダ | `ghostty.h` |

---

### アクションシステム

Ghosttyはアクションシステムを使用して、アプリケーションとサーフェス間の通信を行います。

#### アクション列挙型

```c
typedef enum {
  GHOSTTY_ACTION_QUIT,
  GHOSTTY_ACTION_NEW_WINDOW,
  GHOSTTY_ACTION_NEW_TAB,
  GHOSTTY_ACTION_CLOSE_TAB,
  GHOSTTY_ACTION_NEW_SPLIT,
  GHOSTTY_ACTION_CLOSE_ALL_WINDOWS,
  GHOSTTY_ACTION_TOGGLE_MAXIMIZE,
  GHOSTTY_ACTION_TOGGLE_FULLSCREEN,
  GHOSTTY_ACTION_TOGGLE_TAB_OVERVIEW,
  GHOSTTY_ACTION_TOGGLE_WINDOW_DECORATIONS,
  GHOSTTY_ACTION_TOGGLE_QUICK_TERMINAL,
  GHOSTTY_ACTION_TOGGLE_COMMAND_PALETTE,
  GHOSTTY_ACTION_TOGGLE_VISIBILITY,
  GHOSTTY_ACTION_TOGGLE_BACKGROUND_OPACITY,
  GHOSTTY_ACTION_MOVE_TAB,
  GHOSTTY_ACTION_GOTO_TAB,
  GHOSTTY_ACTION_GOTO_SPLIT,
  GHOSTTY_ACTION_GOTO_WINDOW,
  GHOSTTY_ACTION_RESIZE_SPLIT,
  GHOSTTY_ACTION_EQUALIZE_SPLITS,
  GHOSTTY_ACTION_TOGGLE_SPLIT_ZOOM,
  GHOSTTY_ACTION_PRESENT_TERMINAL,
  GHOSTTY_ACTION_SIZE_LIMIT,
  GHOSTTY_ACTION_RESET_WINDOW_SIZE,
  GHOSTTY_ACTION_INITIAL_SIZE,
  GHOSTTY_ACTION_CELL_SIZE,
  GHOSTTY_ACTION_SCROLLBAR,
  GHOSTTY_ACTION_RENDER,
  GHOSTTY_ACTION_INSPECTOR,
  GHOSTTY_ACTION_SHOW_GTK_INSPECTOR,
  GHOSTTY_ACTION_RENDER_INSPECTOR,
  GHOSTTY_ACTION_DESKTOP_NOTIFICATION,
  GHOSTTY_ACTION_SET_TITLE,
  GHOSTTY_ACTION_PROMPT_TITLE,
  GHOSTTY_ACTION_PWD,
  GHOSTTY_ACTION_MOUSE_SHAPE,
  GHOSTTY_ACTION_MOUSE_VISIBILITY,
  GHOSTTY_ACTION_MOUSE_OVER_LINK,
  GHOSTTY_ACTION_RENDERER_HEALTH,
  GHOSTTY_ACTION_OPEN_CONFIG,
  GHOSTTY_ACTION_QUIT_TIMER,
  GHOSTTY_ACTION_FLOAT_WINDOW,
  GHOSTTY_ACTION_SECURE_INPUT,
  GHOSTTY_ACTION_KEY_SEQUENCE,
  GHOSTTY_ACTION_KEY_TABLE,
  GHOSTTY_ACTION_COLOR_CHANGE,
  GHOSTTY_ACTION_RELOAD_CONFIG,
  GHOSTTY_ACTION_CONFIG_CHANGE,
  GHOSTTY_ACTION_CLOSE_WINDOW,
  GHOSTTY_ACTION_RING_BELL,
  GHOSTTY_ACTION_UNDO,
  GHOSTTY_ACTION_REDO,
  GHOSTTY_ACTION_CHECK_FOR_UPDATES,
  GHOSTTY_ACTION_OPEN_URL,
  GHOSTTY_ACTION_SHOW_CHILD_EXITED,
  GHOSTTY_ACTION_PROGRESS_REPORT,
  GHOSTTY_ACTION_SHOW_ON_SCREEN_KEYBOARD,
  GHOSTTY_ACTION_COMMAND_FINISHED,
  GHOSTTY_ACTION_START_SEARCH,
  GHOSTTY_ACTION_END_SEARCH,
  GHOSTTY_ACTION_SEARCH_TOTAL,
  GHOSTTY_ACTION_SEARCH_SELECTED,
  GHOSTTY_ACTION_READONLY,
  GHOSTTY_ACTION_COPY_TITLE_TO_CLIPBOARD,
} ghostty_action_tag_e;
```

---

### IPCインターフェース

プロセス間通信で使用されるAPI。

#### IPC ターゲット

```c
typedef enum {
  GHOSTTY_IPC_TARGET_CLASS,   // 特定のGhosttyインスタンス
  GHOSTTY_IPC_TARGET_DETECT,  // 自動検出
} ghostty_ipc_target_tag_e;
```

#### IPC アクション

```c
typedef enum {
  GHOSTTY_IPC_ACTION_NEW_WINDOW,  // 新しいウィンドウを開く
} ghostty_ipc_action_tag_e;
```

---

## libghostty-vt API詳細

### OSCパーサ

#### 21. ghostty_osc_new

OSCパーサを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_osc_new(const GhosttyAllocator *allocator, GhosttyOscParser *parser)` |
| ヘッダ | `ghostty/vt/osc.h` |
| 戻り値 | GHOSTTY_SUCCESS で成功 |

---

#### 22. ghostty_osc_free

OSCパーサを解放します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_osc_free(GhosttyOscParser parser)` |
| ヘッダ | `ghostty/vt/osc.h` |

---

#### 23. ghostty_osc_next

次のバイトをパースします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_osc_next(GhosttyOscParser parser, uint8_t byte)` |
| ヘッダ | `ghostty/vt/osc.h` |

---

#### 24. ghostty_osc_end

パースを完了し、コマンドを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyOscCommand ghostty_osc_end(GhosttyOscParser parser, uint8_t terminator)` |
| ヘッダ | `ghostty/vt/osc.h` |
| 戻り値 | パースされたOSCコマンド |

---

#### 25. ghostty_osc_command_type

OSCコマンドのタイプを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyOscCommandType ghostty_osc_command_type(GhosttyOscCommand command)` |
| ヘッダ | `ghostty/vt/osc.h` |

**コマンドタイプ**

| タイプ | 値 | 説明 |
| --- | --- | --- |
| GHOSTTY_OSC_COMMAND_INVALID | 0 | 無効なコマンド |
| GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE | 1 | ウィンドウタイトル変更 |
| GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_ICON | 2 | ウィンドウアイコン変更 |
| GHOSTTY_OSC_COMMAND_SEMANTIC_PROMPT | 3 | セマンティックプロンプト |
| GHOSTTY_OSC_COMMAND_CLIPBOARD_CONTENTS | 4 | クリップボード内容 |
| GHOSTTY_OSC_COMMAND_REPORT_PWD | 5 | PWD報告 |
| GHOSTTY_OSC_COMMAND_MOUSE_SHAPE | 6 | マウス形状 |
| GHOSTTY_OSC_COMMAND_COLOR_OPERATION | 7 | カラー操作 |
| GHOSTTY_OSC_COMMAND_KITTY_COLOR_PROTOCOL | 8 | Kittyカラープロトコル |
| GHOSTTY_OSC_COMMAND_SHOW_DESKTOP_NOTIFICATION | 9 | デスクトップ通知 |
| GHOSTTY_OSC_COMMAND_HYPERLINK_START | 10 | ハイパーリンク開始 |
| GHOSTTY_OSC_COMMAND_HYPERLINK_END | 11 | ハイパーリンク終了 |

---

### SGRパーサ

#### 26. ghostty_sgr_new

SGRパーサを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_sgr_new(const GhosttyAllocator* allocator, GhosttySgrParser* parser)` |
| ヘッダ | `ghostty/vt/sgr.h` |
| 戻り値 | GHOSTTY_SUCCESS で成功 |

---

#### 27. ghostty_sgr_set_params

SGRパラメータを設定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_sgr_set_params(GhosttySgrParser parser, const uint16_t* params, const char* separators, size_t len)` |
| ヘッダ | `ghostty/vt/sgr.h` |

**パラメータ**

| パラメータ名 | 型 | 説明 |
| --- | --- | --- |
| parser | GhosttySgrParser | パーサハンドル |
| params | uint16_t* | SGRパラメータ配列 |
| separators | char* | セパレータ配列（NULLで全てセミコロン） |
| len | size_t | パラメータ数 |

---

#### 28. ghostty_sgr_next

次のSGR属性を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_sgr_next(GhosttySgrParser parser, GhosttySgrAttribute* attr)` |
| ヘッダ | `ghostty/vt/sgr.h` |
| 戻り値 | 属性がある場合 true |

**SGR属性タグ**

| タグ | 説明 |
| --- | --- |
| GHOSTTY_SGR_ATTR_BOLD | 太字 |
| GHOSTTY_SGR_ATTR_ITALIC | イタリック |
| GHOSTTY_SGR_ATTR_UNDERLINE | 下線 |
| GHOSTTY_SGR_ATTR_FG_8 | 8色前景色 |
| GHOSTTY_SGR_ATTR_BG_8 | 8色背景色 |
| GHOSTTY_SGR_ATTR_FG_256 | 256色前景色 |
| GHOSTTY_SGR_ATTR_BG_256 | 256色背景色 |
| GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG | RGB前景色 |
| GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG | RGB背景色 |

---

### キーエンコーダ

#### 29. ghostty_key_event_new

キーイベントを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_key_event_new(const GhosttyAllocator *allocator, GhosttyKeyEvent *event)` |
| ヘッダ | `ghostty/vt/key/event.h` |
| 戻り値 | GHOSTTY_SUCCESS で成功 |

---

#### 30. ghostty_key_event_set_action

キーアクションを設定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_key_event_set_action(GhosttyKeyEvent event, GhosttyKeyAction action)` |
| ヘッダ | `ghostty/vt/key/event.h` |

**アクション**

| アクション | 値 | 説明 |
| --- | --- | --- |
| GHOSTTY_KEY_ACTION_RELEASE | 0 | キーリリース |
| GHOSTTY_KEY_ACTION_PRESS | 1 | キープレス |
| GHOSTTY_KEY_ACTION_REPEAT | 2 | キーリピート |

---

#### 31. ghostty_key_encoder_new

キーエンコーダを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_key_encoder_new(const GhosttyAllocator *allocator, GhosttyKeyEncoder *encoder)` |
| ヘッダ | `ghostty/vt/key/encoder.h` |
| 戻り値 | GHOSTTY_SUCCESS で成功 |

---

#### 32. ghostty_key_encoder_setopt

エンコーダオプションを設定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `void ghostty_key_encoder_setopt(GhosttyKeyEncoder encoder, GhosttyKeyEncoderOption option, const void *value)` |
| ヘッダ | `ghostty/vt/key/encoder.h` |

**オプション**

| オプション | 型 | 説明 |
| --- | --- | --- |
| GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION | bool | カーソルキーアプリケーションモード |
| GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION | bool | キーパッドアプリケーションモード |
| GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX | bool | Alt でエスケーププレフィックス |
| GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS | GhosttyKittyKeyFlags | Kittyキーボードプロトコルフラグ |
| GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT | GhosttyOptionAsAlt | macOS Optionキーの振る舞い |

---

#### 33. ghostty_key_encoder_encode

キーイベントをエスケープシーケンスにエンコードします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len)` |
| ヘッダ | `ghostty/vt/key/encoder.h` |
| 戻り値 | GHOSTTY_SUCCESS で成功、GHOSTTY_OUT_OF_MEMORY でバッファ不足 |

**使用例**

```c
GhosttyKeyEncoder encoder;
GhosttyKeyEvent event;
char buf[128];
size_t written = 0;

ghostty_key_encoder_new(NULL, &encoder);
ghostty_key_event_new(NULL, &event);

// Ctrl+C の設定
ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
ghostty_key_event_set_key(event, GHOSTTY_KEY_C);
ghostty_key_event_set_mods(event, GHOSTTY_MODS_CTRL);

// エンコード
GhosttyResult result = ghostty_key_encoder_encode(
    encoder, event, buf, sizeof(buf), &written);

if (result == GHOSTTY_SUCCESS) {
    // buf に書き込まれたシーケンスを使用
    write(pty_fd, buf, written);
}

ghostty_key_event_free(event);
ghostty_key_encoder_free(encoder);
```

---

### ペーストユーティリティ

#### 34. ghostty_paste_is_safe

ペーストデータの安全性を確認します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `bool ghostty_paste_is_safe(const char* data, size_t len)` |
| ヘッダ | `ghostty/vt/paste.h` |
| 戻り値 | 安全な場合 true |

**危険とみなされるデータ**

- 改行文字 (`\n`) を含む
- Bracketed Paste終了シーケンス (`\x1b[201~`) を含む

---

## 備考

### ABIの安定性

現時点では、Ghostty APIはABIの安定性を保証していません。バージョン間で破壊的変更が行われる可能性があります。

### ドキュメント

詳細なAPIドキュメントは、Zigソースコード内のドキュメントコメントを参照してください。

### 関連リソース

- 公式ドキュメント: https://ghostty.org/docs
- GitHub: https://github.com/ghostty-org/ghostty
- libghostty-vt ブログ記事: https://mitchellh.com/writing/libghostty-is-coming
