native-feel-cross-platform-desktop

ネイティブのような使用感を実現するクロスプラットフォームデスクトップアプリ

ネイティブのような使用感が求められるクロスプラットフォームデスクトップアプリのアーキテクチャについて助言します。このスキルでは、その哲学とアーキテクチャ、そして具体的な落とし穴をまとめています。Raycast の 2.0 への書き換えに関する公開技術解説をもとに、macOS 版の出荷済みバイナリ Raycast Beta.app をリバースエンジニアリングして検証した内容です。

このスキルの使い方

1. まず references/01-philosophy.md の哲学を確認します。 このアーキテクチャが解決する中心的な課題、つまり クロスプラットフォームの開発体験（DX）とネイティブに近いパフォーマンスをどう両立させるか を説明し、構造上の取り組みを示す8つの原則を紹介しています。具体的な判断はすべて、いずれかの原則に基づきます。ユーザーの判断が原則に反する場合は、原則の番号と短い名称を示し、トレードオフを説明してください。
2. ユーザーの質問に合ったリファレンスファイルを選びます。 スキルの内容をすべて出すのではなく、必要なものだけを読み込みます。
   • アーキテクチャ／「どのレイヤーを用意すべきか？」→ references/02-architecture.md
   • 「非表示にすると WebView がちらつく／カクつく／フリーズするのはなぜ？」→ references/03-webview-survival.md（情報密度が最も高いファイルです。記載された項目はすべて、実際のバグとその修正方法です）
   • 「Rust／Swift／C#／TS 間の IPC をどう型付けすればよいか？」→ references/04-ipc-contract.md
   • 「アクティビティモニタで 400 MB と表示されるのはなぜ？」→ references/05-memory-truths.md
   • 「Web ページのような使用感をなくすには？」→ references/06-native-conventions.md
   • 「Raycast は実際に何を出荷しているのか？」（具体的な根拠）→ references/07-evidence-raycast.md
3. アーキテクチャを推奨する前に、checklists/decision-tree.md の判断ツリーを実行します。 よくあるプロジェクトの形状のうち、いくつかではこのスタックが適さないと判断されます。該当する場合は、そのことを率直に伝えてください。
4. ユーザーがアプリの「ネイティブのような使用感」を主張する前に、checklists/ship-readiness.md を実行します。 30項目の監査です。初回の確認では、ほとんどのアプリが5〜10項目で不合格になります。

1段落でまとめると

ネイティブのような使用感を備えたクロスプラットフォームデスクトップアプリは、ネイティブのフックを備えた Web アプリではなく、独自のテーマを適用した Electron でもありません。ウィンドウ、ホットキー、メニューバー、マテリアル、ライフサイクルを管理するネイティブシェル（macOS では Swift/AppKit、Windows では C#/WPF）に、共有の React/TypeScript UI を表示するためのレンダリングサーフェスとしてのみ、システムの WebView（WKWebView または WebView2）を組み込みます。ビジネスロジックはアプリにバンドルされた、長時間稼働する Node プロセスに置きます。ファイルのインデックス作成、計算、暗号処理など、パフォーマンスが重要なサブシステムは Rust に置き、プラットフォーム間で共有して、UniFFI が生成する型付きバインディングを通じて公開します。4つのランタイムは、各側の型付きクライアントを生成する単一の宣言型インターフェースを通じて通信します。全体の常駐メモリは約400 MBで、そのうち約150 MBは避けられない WebView と Node のベースラインです。このベースラインを受け入れることで、1つの React コードベースを両方の OS で使えます。そのコストは、ホットリロードによる高速な反復開発と、すでに両プラットフォームで数千のコミュニティプラグインを動かしている共有拡張 API によって取り戻せます。

すぐに指摘すべきアンチパターン

ユーザーが次のいずれかをしようとしている場合は、いったん止めて質問してください。

• 「Electron を使ってテーマを設定すればいい」 → Electron では、ネイティブらしい操作感に必要なシステム WebView、ウィンドウクラス、マテリアル API が抽象化されてしまいます。Electron をフォークしない限り、その抽象化を通じて Liquid Glass／アクリル／真のビブランシーを実現することはできません。代わりに references/02-architecture.md を勧めてください。
• 「Tauri にしよう。Electron より軽いだけでしょ」 → Tauri は独自の WebView ラッパーを同梱し、プラットフォーム API を抽象化します。Electron と同じく制御性が損なわれるうえ、成熟度もより低いです。ユーティリティには使えますが、すべてのウィンドウアニメーションを OS に合わせる必要があるアプリには適しません。
• 「UI は Swift／C# で描画して、ビジネスロジックを共有しよう」 → UI コードベースを 2 つ、ずっと保守することになります。機能をリリースするたびに、2 回実装する必要があります。デザイナーも 2 つの仕様を保守することになります。代わりに WebView をレンダラーとして使う方法を勧めてください。
• 「WebKit のスロットリングが問題だから、独自のポーリングループを回そう」 → いいえ。スロットリングは、WKWebView の特定の設定フラグを 2 つ指定すれば解決できます。references/03-webview-survival.md の「Hidden window throttling」を参照してください。
• 「メモリの使用量がひどい。400 MB も使っている」 → おそらく測定方法が誤っています。アクティビティモニタは共有フレームワークを二重にカウントし、圧縮されたページを常駐メモリとして扱います。最適化を始める前に references/05-memory-truths.md を参照してください。
• 「IPC の型を言語ごとに手書きしよう」 → 1 スプリントのうちに食い違いが生じます。UniFFI（Rust ↔ Swift／Kotlin／C# の場合）を使うか、クライアントを生成する単一の IDL を独自に作成してください。references/04-ipc-contract.md を参照してください。
• 「cursor: pointer を追加して反応をよくしよう」 → それこそが、操作感を Web らしく してしまいます。ネイティブ UI では、ホバー可能な行にポインターを合わせてもカーソルは変わりません。references/06-native-conventions.md を参照してください。

出力スタイル

アドバイスする際は：

• 当てはまる references/01-philosophy.md の原則を具体的に引用してください（例：「T3 — プラットフォームに寄り添い、張り合わない。OS のほうが、あなたより優れたぼかしを描画します」）。
• スキル全体ではなく、ファイルとセクションを示してください。
• 推奨事項ごとに、代わりにユーザーが何を手放すのかを明示してください。このアーキテクチャに、何の代償もない利点はありません。このスキル全体のテーマは、トレードオフを意識して選択することです。
• ユーザーのプロジェクトにこのアーキテクチャを使うべきかどうか判断に迷う場合は、アドバイスする前に checklists/decision-tree.md に沿って確認してください。「このスキルは当てはまりません。通常の Electron アプリを作りましょう」という結論でもかまいません。