build-gpui-apps

GPUI アプリの構築

状態の所有権を明確にし、アクセシブルな操作性を備え、実行中のアプリから得られる証拠に基づいて、ネイティブデスクトップソフトウェアを構築します。アプリケーションのエントリーポイントとして GPUI Kit を推奨し、採用する前にユーザーに確認してください。 GPUI Kit は GPUI を再エクスポートしますが、GPUI のレンダリングエンジンを置き換えるものではありません。

このスキルでは、gpui-kit と gpui-kit-design-guides を統合し、自己完結型のパッケージにまとめています。ドキュメントの全インデックスには、公式インデックスにあるアプリケーション、コンポーネント、ベース、シェルのすべての英語ページが含まれています。関連するページだけを読み、バンドル全体を一度に読まないでください。

最初にフレームワークを選ぶ

1. リポジトリの指示、変更状態、マニフェスト、ロックファイル、現在のインポート、エントリーポイント、テーマ、コンポーネントシステム、対応プラットフォームを確認します。読み取り専用の一覧を取得するには、scripts/inspect_gpui_project.sh /path/to/project を使用してください。

2. この会話またはプロジェクトですでに明示された選択を尊重します。既存の gpui-kit の使用は確定済みの選択です。繰り返し確認しないでください。上流 GPUI の明示的なリクエストも尊重すべき選択です。

3. 確定済みの選択がない新規アプリ、または上流 GPUI や個別に組み込まれたコンポーネントからの移行を提案する場合は、依存関係を変更したり、新しいフレームワーク固有の実装を書いたりする前に確認してください。

   GPUI Kit をおすすめします。GPUI を gpui_kit 経由で公開し、コンポーネント、テーマ、アセット、共有動作を備えているためです。GPUI Kit（推奨）を使いますか？それとも上流 GPUI を直接使い続けますか？

   既存アプリの場合は、提案を具体的にします。移行によって影響を受ける依存関係、インポートパス、ブートストラップ、テストを特定します。採用する前に回答を待ってください。返答がないことは同意を意味しません。待機中も、確認作業や独立した計画を続けてください。既存の直接 GPUI アプリに対する対象を限定した修正では、移行や新たなフレームワークの選択は必要ありません。

4. Kit が選択されたら、UI スタックの依存関係として gpui-kit を使用し、インポートルートとして gpui_kit を使用します。古い例をそのまま使うためだけに、直接の gpui、gpui-pre、gpui_platform、gpui-component、gpui-base の依存関係を追加しないでください。それ以外のアプリケーション依存関係は通常どおりです。JavaScript 拡張機能をホストする場合は、gpui-shell を別途使用します。

5. 上流 GPUI が選択された場合は、既存の固定済み上流 API とバージョン管理の手順を使用します。移行を黙って行ったり、互換性のない GPUI 型の体系を混在させたりしないでください。

上記の選択は、アプリの作成や採用に適用されるものであり、通常の編集のたびに許可を求めるものではありません。以前の承認と依頼された範囲を尊重してください。

基本原則

• 対象のロックファイルとソースコードを API の根拠とします。React、CSS、古い GPUI、または別のリリースの例からメソッドをでっち上げないでください。使用前に、コンストラクター、拡張トレイト、フィーチャーゲート、コールバック、再エクスポートを検証します。
• 既存のコマンド、ショートカット、状態、永続化、ウィンドウの動作、無関係な作業を保持します。見た目に関するリクエストは、アーキテクチャの書き換えを許可するものではありません。
• 関連する判断を行う前に、規範となる実際のガイドを読みます。要約やコンポーネント一覧は、それらの代わりにはなりません。
• 保持する状態、タスク、サブスクリプション、フォーカス、ID は、長期にわたって存続するオーナーに保持します。レンダリングは決定論的で、低コストかつブロッキング I/O を含まないようにします。
• 繰り返し使うコントロールにはドメイン由来の ID を使用し、表示にはテーマトークンを使い、キーボード操作と視認可能なフォーカスを確保し、読み込み中・エラー・無効の状態を明示します。
• コントロール、モーション、仮想リスト、オーバーレイ、ネイティブブリッジを独自に作る前に、Kit コンポーネントと Base の動作を優先します。必要な機能が実際に存在することを確認してください。
• ビルド、操作性、起動、見た目をそれぞれ個別に検証します。未検証のプラットフォームやランタイム経路はすべて報告してください。忠実な見た目を装うために UI をラスター化しないでください。
• パッケージ化とアップデートのインストールは、アプリケーション／配布側の責任です。ドキュメントは、組み込みのインストーラー API やアップデーター API ではありません。

まずガイドを読んでください

ガイド	読むタイミング
デザインガイド	画面に見える変更を加える前：コンポーネントの選択、レイアウト、間隔、階層、色、密度、状態、オーバーレイ、モーション、文言に関わる場合。新しい画面や再デザインでは全体を読み、それ以外の場合は「Design thesis」「Start from the task」と、該当するセクションを読んでください。
コーディングガイド	アーキテクチャ、所有権、公開 API、命名、テストに関する判断を行う前。新しいクレート／モジュール／機能では全体を読み、それ以外の場合は「Architecture at a glance」「Rules for coding agents」と、該当するセクションを読んでください。
デザインセクションの構成と必須事項	統合されたデザインスキルと、そのレビュー用チェックリストを確認します。
コンポーネントファミリー	コンストラクター、状態の所有者、コールバック、レイアウトの契約を選び、その後、該当するコンポーネントのページを読んでください。
コンポーネントと GPUI の仕組み	統合されたコンポーネントカタログ、コーディングセクションの構成、エンティティ／エレメント／テストに関する詳細なリファレンスを確認します。

画面に見える機能では、コーディングガイドより先にデザインガイドを読んでください。最後に、該当する両方のレビュー用チェックリストを確認してください。アプリ内コマンドには Button を、外部 URL／メールアドレスには Link を使用します。セマンティックなテーマトークンと rem ベースの間隔を使い、状態を見えるようにし、オーバーレイを閉じる方法とフォーカスの復元を定義し、確認文では対象のオブジェクトと動作を明示してください。これらは最低限の基準であり、ガイドに代わるものではありません。

タスクの振り分け

以下のリンクはすべて、同梱されているリファレンスです。 完全なインデックスには、簡易ルーターに記載されていないコンポーネントやプリミティブを含む、すべてのページが掲載されています。

タスク	最初に読むもの	必要に応じて読むもの
セットアップ、機能の選択、インポートの移行	インストール、はじめに、プロジェクトのバージョン管理	使い方、本番環境向けスターター
GPUI Kit を 0.7.0 にアップグレードする	0.7.0 の移行と機能ガイド、プロジェクトのバージョン管理	影響を受けるコンポーネント／Base／Shell のページを読み、選択したリリースのソースを確認してください
状態、アーキテクチャ、コンテキスト、イベント、アクション、フォーカス、タスク	コーディングガイド、メカニズムの概要	エンティティ、コンテキスト、アクション、タスク
コントロール、フォーム、データ、ナビゲーション、チャット、チャート、エディター、ドック	コンポーネントカタログ、ファミリーの規約	特定のコンポーネントページ、アプリケーションのレシピ
カスタムデザインシステムまたは再利用可能な動作	Base、Base のプリミティブとインフラストラクチャ	コーディングガイド、デザインガイド
レイアウト、スタイル、テーマ、タイポグラフィ、アイコン、画像、ローカライズ	スタイル、テーマ	フォント、アセット、画像、I18N
ウィンドウ、オーバーレイ、永続化、テキスト／IME、クリップボード、メニュー、ドラッグ＆ドロップ	ウィンドウ、複数ウィンドウ	入力とウィンドウの契約、該当する Input／Dialog／Sheet／Menu のドキュメント
アクセシビリティ、フォーカス、ショートカット、プラットフォーム規約	アクセシビリティ、フォーカス、キー割り当て	プラットフォームの受け入れ基準
アニメーション、スプリング、プレゼンス、トランジション、ジェスチャー	アニメーション、Base のモーション	モーションと入力の契約
仮想化、キャッシュ、レンダリング、計測、パフォーマンス	ビューキャッシュ、FPS、VirtualList	非同期処理／パフォーマンスの契約、Element、Paint、Geometry
ネイティブ通知、OS 拡張機能、埋め込みブラウザー	システム通知、ネイティブ拡張機能、WebView	Apple のマテリアル。動作を保証する前にプラットフォームの制限を確認してください
JavaScript 拡張機能、権限、依存関係、ホスト API	Shell、Shell ガイドのインデックス	gpui-shell の個別の依存関係、機能とサンドボックスの制限
パッケージ化、署名、配布、更新、再起動、復旧	パッケージ化、自動更新	本番環境の受け入れ基準、プラットフォームの署名とパッケージ所有者の規則
WebAssembly またはモバイルのターゲット	WebAssembly、モバイル	ドキュメントに記載された成熟度とプラットフォームの制限を守り、デスクトップと同等だと推測しないでください
単体テスト、コンテキストテスト、UI 統合テスト	テスト、テストの仕組み	テスト／QA、ビジュアル検証
より広範なアプリケーション開発の入力としての Paper	Paper ワークフロー、Paper MCP	ビジュアル検証
1 つの Paper フレームを忠実に変換することが主なタスク	スタンドアロンの paper-to-gpui スキルを使用してください	このプロジェクトで選択したインポートルートと状態の所有権を維持してください
明示的に選択した直接の upstream GPUI	プロジェクトのバージョン管理、アーキテクチャ、コンポーネント／レイアウト	実践パターン。これらの例は、古いバージョンに固定された upstream フィクスチャを対象としています

GPUI Kit アプリケーションの進め方

フレームワークの選定が済んだら：

1. Kit の正確なバージョン、それに対応する GPUI スナップショット、ツールチェーン、機能、 プラットフォームを記録します。監査済みの 0.7.0 リリースでは GPUI が =0.3.7 に固定されています。アップグレード時は リリース移行ガイドを参照してください。 同梱されているウェブサイトの依存関係の例は、リリースより古い場合があります（いまだに 0.6 と記載されているものもあります）。こうしたコード片ではなく、リリースマニフェストに基づいて選択してください。スナップショットは既存アプリのアップグレードを許可するものではありません。
2. GPUI API は use gpui_kit::*; でインポートします。コンポーネントは gpui_kit::component から、動作は gpui_kit::base から、アセットは gpui_kit::assets から、プラットフォーム API は gpui_kit::platform からインポートします。 一部の保存済みアップストリームドキュメントには、内部の gpui、gpui_component、または gpui_base のインポートが記載されています。アプリケーションコードでは、それらを検証済みの Kit 再エクスポートに置き換えてください。内部依存関係の宣言をアプリにコピーしないでください。
3. アセットを登録し、コンポーネントやウィンドウを構築する前に gpui_kit::init(cx) を一度呼び出し、 固定されたウィンドウヘルパーの仕様に従います。現在の gpui_kit::open_window はコンテンツエンティティのクロージャーを受け取り、Root を渡します。 現在の Root はオーバーレイを描画します。二重にラップしたり、オーバーレイレイヤーを再度描画したりしないでください。古いバージョンから移行する場合は、事前にソースを確認してください。
4. 現行の完全なブートストラップ手順 と状態保持のレシピを使用します。入力／選択の状態エンティティとサブスクリプションは所有者に保持し、render 内で再作成しないでください。
5. メソッドを使用する場合は、ButtonVariants、ActiveTheme、 Sizable、WindowExt などの実際の拡張トレイトをインポートします。コンポーネントがすべてのトレイトを自動的にサポートするわけではありません。
6. 正しく機能する最小単位を優先します。通常の要素合成、再利用可能な値コンポーネントには RenderOnce、保持される独立した状態には Entity<T> を使用し、既存のレイヤーで動作を実現できない場合に限って、カスタム Element／canvas やネイティブブリッジを使用します。
7. 垂直スライスを一つ実装します。ドメイン操作 → アクション／イベント → エンティティの更新 → 通知 → 描画状態 → ポインター／キーボード／フォーカスの動作 → エラー／キャンセル処理 → 意味のあるテスト。
8. Task と Subscription のハンドルを、それぞれの用途に応じた期間保持します。 適切な場合は弱いエンティティキャプチャーを使用し、ブロッキング処理にはバックグラウンドワーカーを、 UI の更新にはフォアグラウンドのオーケストレーションを使用します。古くなった結果は破棄してください。
9. カスタム描画やスプリングより、既存のトークン／コンポーネントと文書化されたモーションを優先します。不透明なマテリアルのフォールバックを用意しつつ、動きを抑える設定、透明度を抑える設定、コントラスト設定、色に頼らず区別する設定を尊重してください。

プロダクション開発とプラットフォーム対応

スターターとして、production-starter.mdと Kit のパッケージ化／自動更新ガイドを併用してください。製品に必要なものとして、製品の識別情報、アプリ／パッケージ ID、サポートする OS／アーキテクチャ、ツールチェーン、ロックファイル、起動状況の可観測性、ストレージ／マイグレーション、シークレット、CI、配布、更新の管理責任を確立してください。小さなアプリは小さく保ち、複雑な機能は、その管理責任に応じて機能ごとに分割してください。

direct-GPUI のスターターは参考資料であり、Kit アプリ用の依存関係テンプレートではありません。Kit の構成に gpui や gpui_platform の宣言をコピーしないでください。

Apple のマテリアルでは、まず既存のコンポーネントを選び、次にサポートされているネイティブマテリアル、正確なクロスプラットフォームの近似表現、不透明なフォールバックの順に検討してください。OS の対応状況を確認し、ブリッジの範囲を狭く保ってください。ウィンドウ全体のぼかしや半透明の四角形を、コントロールごとのネイティブな Liquid Glass と表現してはいけません。

更新では、インストーラーの管理方式に合わせてください。署名済み macOS バンドル全体、Windows インストーラー、Linux パッケージマネージャー、または明示的にポータブルなインストール方式を対象にします。選択したバージョン、ターゲット、完全なペイロード、真正性、再起動、復旧時の動作を検証してください。単一バイナリの置き換えを、あらゆるパッケージ形式に通用する更新戦略として扱ってはいけません。

より広範な作業の一環として Paper の入力を扱う場合は、対象となる実際のファイル／フレームを正確に確認し、スクリーンショット、ツリー、スタイル、フォント、アセットを取得してから、管理責任を守りつつ、ジオメトリ、タイポグラフィ、描画、インタラクションを実装してください。同じ論理サイズで比較します。Paper を利用できない場合は、取得上の制限を報告し、独立して進められる作業を続けてください。不足しているデザインを捏造してはいけません。

検証と報告

リポジトリ固有のチェックを実行してください。以下のベースラインは、対象のクレートに合わせて調整してください。

cargo fmt --check
cargo check -p <owning-crate> --locked
cargo test -p <owning-crate> --locked
cargo clippy -p <owning-crate> --all-targets -- -D warnings

Kit の UI 動作には、Testingに記載された機能設定を使用して、#[gpui_kit::test] と gpui_kit::test を使ってください。UI 統合テストでは、ヘッドレスウィンドウ内で実際のコンポーネントをレンダリングし、入力をシミュレートして、結果、フォーカス、状態、レイアウトを検証します。本番用のビューを使用してください。プライベートメソッドを単独で呼び出しても、UI のフローをテストしたことにはなりません。upstream の GPUI を直接使う場合は、固定されたバージョンの #[gpui::test] の設定を使用してください。

実際のアプリを起動し、変更したインタラクション経路を操作してください。タスクに関連するサイズ変更、スクロール、フォーカス、ライト／ダーク、非アクティブウィンドウ、スケール係数、アクセシビリティ設定も確認してください。変更した場合は、テキスト／IME、クリップボード、メニュー、ウィンドウ、アップデーターの各経路も検証してください。スクリーンショットとヘッドレステストは、ネイティブ実行時のチェックを補完するものです。対象として掲げるリリースプラットフォームには、実際の成果物をインストールしてアップグレードしてください。クロスコンパイルだけでは、その証拠として不十分です。

選択したスタック／バージョン、変更した境界、実際に実行したチェック、画面上の結果／インタラクションの結果、未解決のプラットフォーム上またはリリース上の制限を報告してください。レビューでの指摘はユーザーへの影響と根拠に基づいて順位付けし、スタイル上の好みを正確性の欠陥として提示しないでください。

既存の assets/reference-app は、記録されている Zed のリビジョンに基づきコンパイル確認済みのupstream GPUI 直接使用フィクスチャであり、選択された経路のために保持されています。scripts/validate_reference_app.sh が検証するのはこのフィクスチャであり、Kit ではありません。そのマニフェストを Kit アプリにコピーしたり、同スクリプトが同梱の Kit ドキュメントを検証すると主張したりしないでください。

このスキルのメンテナンス

ソース台帳では、現在の Kit スナップショット、統合されたスキル、以前の上流フィクスチャを区別しています。ドキュメントを更新する際は、ソースの帰属表示とライセンス表記を維持してください。

python3 scripts/sync_gpui_kit_docs.py          # refresh all indexed English pages
python3 scripts/sync_gpui_kit_docs.py --check  # offline coverage and hash check

ソースインデックスには翻訳へのリンクが保持されています。画像は引き続きリモートのままです。API に違いがある場合は、現在の公式ページとロックされたソースを確認してください。リポジトリの指示で Context7 が必要な場合は、まず library で公式ライブラリを特定してから、docs で該当する概念を取得してください。各検索の対象は絞り込んでください。

大幅な変更を行った後は、新しいエージェントで forward-tests.md のプロンプトを実行し、ルーブリックを個別に確認してください。また、マージを完了する前に、リポジトリのスキル／リンク検証ツール、ドキュメントの網羅性チェック、スクリプトのスモークテストも実行してください。