# 非機能要件定義書

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの非機能要件を定義します。Ghosttyは高速性、機能性、ネイティブ体験の3つを同時に実現することを目標とした、クロスプラットフォームのターミナルエミュレータです。本書では、コードベースの分析に基づき、性能、可用性、セキュリティ、拡張性、保守性、運用・監視に関する要件を記載します。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 描画間隔 | 8ms（120FPS） | `DRAW_INTERVAL = 8`として定義。アニメーションやカーソル描画に使用 |
| カーソル点滅間隔 | 600ms | `CURSOR_BLINK_INTERVAL = 600`として定義 |
| リサイズオーバーレイ表示時間 | 750ms（デフォルト） | `resize-overlay-duration`設定で調整可能 |
| Quick Terminal アニメーション | 200ms（デフォルト） | `quick-terminal-animation-duration`設定で調整可能（macOSのみ） |
| 異常終了判定時間 | 250ms | `abnormal-command-exit-runtime`設定。この時間以内にプロセスが終了した場合は異常と判断 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 同時接続数 | 制限なし（OSリソース依存） | 各ウィンドウ・タブ・分割ペインは独立して動作 |
| IO処理 | 専用IOスレッド | 高負荷IO時のジッター最小化のため専用スレッドで処理 |
| 描画フレームレート | 約60FPS（通常時）、120FPS（アニメーション時） | 画面変更が少ない場合はより低いレートで動作 |
| レンダラーメールボックス容量 | 64メッセージ | `BlockingQueue(rendererpkg.Message, 64)`として定義 |

### メモリ使用量

| 項目 | 制限値 | 備考 |
| --- | --- | --- |
| スクロールバックバッファ | 10MB（デフォルト） | `scrollback-limit`設定で調整可能。ターミナルサーフェスごと |
| 画像ストレージ制限 | 320MB（デフォルト） | `image-storage-limit`設定。Kitty画像プロトコル等に使用 |
| 最大画像ストレージ | 4GB | 設定可能な最大値（4,294,967,295バイト） |
| 入力ファイルサイズ | 10MB | `input`設定でファイルから読み込む際の上限 |
| CSSファイルサイズ | 5MB | GTKカスタムCSSファイルの上限 |
| Linux cgroupメモリ制限 | 設定可能 | `linux-cgroup-memory-limit`でサーフェスごとの制限設定可能 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | デスクトップアプリケーションとして常時利用可能 | シングルインスタンスモードまたはマルチインスタンスモードで動作 |
| 計画停止時間 | なし | アップデート時のみ再起動が必要 |
| 障害復旧時間（RTO） | 即時（クラッシュレポートベース） | クラッシュレポートが自動生成され、次回起動時に保存 |
| 目標復旧時点（RPO） | ウィンドウ状態の保存による復旧 | `window-save-state`設定で状態保存を有効化可能（macOS） |
| ウィンドウ状態保存 | 有効化可能 | タブ、分割、ウィンドウ位置などを保存・復元（macOS） |
| Undo操作タイムアウト | 5秒（デフォルト） | `undo-timeout`設定で調整可能（macOS） |
| アプリケーション終了遅延 | 設定可能 | `quit-after-last-window-closed-delay`（最小1秒、Linux） |

## セキュリティ要件

### クリップボードセキュリティ

| 要件 | 実装 | 設定 |
| --- | --- | --- |
| クリップボード読み取り制御 | 読み取り前にユーザー確認（デフォルト） | `clipboard-read`: `ask`/`allow`/`deny` |
| クリップボード書き込み制御 | 無条件許可（デフォルト） | `clipboard-write`: `ask`/`allow`/`deny` |
| ペースト保護 | 危険なテキストのペースト前に確認 | `clipboard-paste-protection`: `true`（デフォルト） |
| ブラケットペースト安全性 | ブラケットペーストモード時は安全とみなす | `clipboard-paste-bracketed-safe`: `true`（デフォルト） |

### ターミナルセキュリティ

| 要件 | 実装 | 設定 |
| --- | --- | --- |
| タイトルレポート | デフォルト無効（セキュリティリスク） | `title-report`: `false`（デフォルト） |
| セキュア入力（macOS） | パスワードプロンプト検出時に自動有効化 | `macos-auto-secure-input`: `true`（デフォルト） |
| セキュア入力表示 | セキュア入力有効時のグラフィカル表示 | `macos-secure-input-indication`: `true`（デフォルト） |
| Shortcutsアクセス制御（macOS） | ユーザー確認またはアクセス制御 | `macos-shortcuts`: `ask`/`allow`/`deny` |

### プロセス分離（Linux）

| 要件 | 実装 | 設定 |
| --- | --- | --- |
| cgroupベースのリソース分離 | systemdスコープによるサーフェス分離 | `linux-cgroup`: `never`/`always`/`single-instance` |
| プロセス数制限 | サーフェスごとのプロセス数制限 | `linux-cgroup-processes-limit` |
| メモリ制限 | サーフェスごとのメモリ制限 | `linux-cgroup-memory-limit` |

## 拡張性要件

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

| 項目 | 対応状況 | 備考 |
| --- | --- | --- |
| macOS | フル対応 | SwiftUI/Metal/CoreText使用 |
| Linux | フル対応 | GTK/OpenGL使用 |
| Windows | 計画中 | PowerShell、Cmd、WSL対応予定 |
| WebAssembly | 対応 | libghostty-vtとして利用可能 |

### レンダラーアーキテクチャ

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| Metal | macOS | Apple Metal API使用、リガチャ対応 |
| OpenGL | Linux/その他 | クロスプラットフォーム対応 |
| WebGL | WebAssembly | ブラウザ対応 |

### IOバックエンド

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| epoll | Linux | デフォルトのフォールバック |
| io_uring | Linux | 利用可能な場合に使用 |
| auto | 全プラットフォーム | プラットフォームに最適なバックエンドを自動選択 |

### 拡張機能

| 機能 | 対応 | 備考 |
| --- | --- | --- |
| カスタムシェーダー | 対応 | `custom-shader`設定でカスタマイズ可能 |
| カスタムCSS（GTK） | 対応 | `gtk-custom-css`設定 |
| フォントカスタマイズ | 対応 | フォントファミリー、サイズ、バリエーション等 |
| キーバインド | 完全カスタマイズ可能 | `keybind`設定でアクション定義 |
| テーマ | 対応 | ビルトインテーマおよびカスタムテーマ |

## 保守性要件

### コード品質

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| プログラミング言語 | Zig（コア）、Swift（macOS）、GTK（Linux） | 高性能かつメモリ安全 |
| テスト | ユニットテスト、統合テスト | `zig build test`で実行 |
| リント | Prettier、SwiftLint、ShellCheck、Alejandra | CI/CDで自動チェック |
| メモリリークチェック | Valgrindサポート | `zig build run-valgrind`で実行 |

### 設定管理

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| 設定ファイル | Ghostty設定形式 | `$XDG_CONFIG_HOME/ghostty/config` |
| 設定リロード | ランタイムリロード対応 | 一部設定は再起動が必要 |
| 設定継承 | 複数設定ファイルの読み込み | `config-file`設定で追加ファイル指定 |
| テーマファイル | 別ファイルでのテーマ定義 | `theme`設定で指定 |

### ビルドシステム

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| ビルドツール | Zig Build System | クロスプラットフォームビルド |
| 依存関係管理 | build.zig.zon | Zigパッケージマネージャー |
| Nix対応 | フルサポート | flake.nix提供 |

## 運用・監視要件

### ログ機能

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| 標準エラー出力 | 全プラットフォーム | `GHOSTTY_LOG`環境変数で制御 |
| macOS統合ログ | macOS | `com.mitchellh.ghostty`サブシステム |
| journald統合 | Linux（systemd） | ユーザーサービスとしてログ記録 |
| ログレベル | Debug/Releaseで異なる | Debugビルドでは詳細ログ出力 |

### クラッシュレポート

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| クラッシュレポート生成 | 自動 | `$XDG_STATE_HOME/ghostty/crash`に保存 |
| レポート形式 | Sentry Envelope形式 | Sentryへの送信も可能 |
| CLIアクセス | `ghostty +crash-report` | クラッシュレポート一覧表示 |
| 自動送信 | なし | プライバシー配慮により手動送信が必要 |

### デバッグ機能

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| インスペクター | 組み込み | ターミナル状態の確認 |
| GTK Inspector | GTK_DEBUG=interactive | CSSのリアルタイム調整 |
| OpenGLデバッグ | `gtk-opengl-debug` | Debugビルドでデフォルト有効 |

### デスクトップ通知

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| デスクトップ通知 | OSC 9/OSC 777対応 | `desktop-notifications`設定で有効化 |
| コマンド終了通知 | 対応 | `notify-on-command-finish`設定 |
| 通知アクション | ベル/システム通知 | `notify-on-command-finish-action`設定 |
| 通知遅延 | 5秒以上（デフォルト） | `notify-on-command-finish-after`設定 |

## 備考

### パフォーマンスに関する注意事項

- IO処理は専用スレッドで行われ、高負荷IO時（例：`cat <大きなファイル>.txt`）でもジッターを最小化
- iTerm比で4倍、Kitty比で4倍、Terminal.app比で2倍の読み取り速度（README記載のベンチマーク）
- Alacrittyと同等の速度でより豊富な機能を提供
- `window-vsync`設定でVSyncを無効化し、入力レイテンシを最小化可能（ただしティアリングのリスクあり）

### プラットフォーム固有の制限事項

- macOS: 非ネイティブフルスクリーンモードではタブが使用不可
- Linux: ウィンドウ位置の設定はX11のみ対応、Waylandでは非対応
- 一部の設定はランタイムでの変更が反映されず、再起動が必要

### セキュリティに関する注意事項

- クラッシュレポートには機密情報が含まれる可能性があるため、手動送信時は注意が必要
- テーマファイルは任意の設定を含むことができるため、信頼できないソースからのテーマ使用は非推奨
