capacitor-uiscene-migrator

Capacitor UIScene Migrator

Capacitor 8.4 → 8.5 の iOS 移行を、UIScene ライフサイクルに対応させるためのガイドです。CLI マイグレーター（npx cap migrate）は、Capacitor のテンプレートにまだ準拠しているプロジェクトを処理します。このスキルは、それ以外のすべてを対象とします。編集前に監査を行い、判断が必要な箇所では開発者に確認し、既存のファイルを置き換えるのではなく内容をマージします。また、プロジェクトの構成が許す場合は、機械的な作業を CLI に委ねます。

移行の正式なリファレンスは、 8.4 → 8.5 migration guide です。開発者が手動で行う手順がある場合は、リンクしてください。

このスキルを使用するタイミング

• Capacitor 8.x の iOS アプリを UIScene ライフサイクルに移行する場合
• npx cap migrate が部分的な状態を報告して処理をスキップしたプロジェクト
• 独自に作成した SceneDelegate.swift や、カスタマイズした AppDelegate.swift（ディープリンクのルーティング、サードパーティ SDK への転送など）を含むアプリ
• UIScene との互換性について Capacitor プラグインのリポジトリを監査する場合
• Capacitor アプリで Xcode の「CLIENT OF UIKIT REQUIRES UPDATE: This process does not adopt UIScene lifecycle」警告を診断する場合

このスキルを使用しないタイミング

• Cordova から Capacitor へのプラグイン移行 → cordova-plugin-migrator
• 新しい Capacitor プラグインの生成 → capacitor-plugin-generator
• Capacitor 9 以降への移行（このスキルの対象は 8.4 → 8.5 のみです）
• Android のライフサイクルに関する作業（UIScene は iOS 専用です）
• シーンのライフサイクルに関係しない一般的な Capacitor のデバッグ

前提条件

• ios/ プラットフォームまたは iOS ソースを含む Capacitor 8.x プロジェクト（アプリまたはプラグイン）
• npx cap migrate に引き継ぐための @capacitor/cli 8.5+ が利用可能であること
• 開発者がビルドを検証する場合は、Xcode がインストールされていること

8.5 での変更点（監査で参照する事実）

これらの変更によって何が動かなくなり、何が動き続けるのかが決まります。内容を和らげないでください。

• シーンの採用はオプトインです。UIApplicationSceneManifest がないアプリでは AppDelegate の経路が維持され、8.5 のコアでも引き続き動作します。iOS はレガシーアプリ（互換性シーン）でも UIScene.* 通知を送信するため、ブリッジの JS resume／pause イベントはどちらのモードでも発火します。
• シーンマニフェストが存在すると、iOS は application(_:open:options:)、application(_:continue:)、および 4 つのフォアグラウンド／バックグラウンド AppDelegate メソッド （applicationDidBecomeActive、applicationWillResignActive、 applicationDidEnterBackground、applicationWillEnterForeground）を呼び出さなくなります。これらのいずれかにあるカスタムコードは、警告なしに実行されなくなります。UIApplication 通知は引き続き発火します。また、didFinishLaunching、applicationWillTerminate、プッシュトークンの登録、リモート通知のコールバックは引き続き AppDelegate で処理されます。
• SceneDelegateProxy は従来の .capacitorOpenURL、 .capacitorOpenUniversalLink、および CDVPluginHandleOpenURL 通知を同じペイロード形式で再送するため、既存のオブザーバーは引き続き動作します。コールドスタート時の URL はブリッジのビューが表示された後に渡されるため、コールド起動時も appUrlOpen と getLaunchUrl() の両方が動作します。
• 新しい .capacitorSceneWillConnect、.capacitorSceneOpenURL、および .capacitorSceneOpenUniversalLink 通知は、オブジェクトとして UIScene を渡します。これらが送信されるのは 8.5 以降のみです。8.4 にも対応するプラグインでは、従来の名前を引き続き使用する必要があります。
• TmpViewController と CapacitorBridge.tmpWindow は削除されました。これらを参照すると、8.5 ではビルドエラーになります。
• 8.5 のテンプレートでは、scene(_:willConnectTo:) 内のコードでウィンドウを作成します。Main.storyboard はルートビューコントローラーを提供しなくなりました。カスタムの CAPBridgeViewController サブクラスは、ストーリーボードではなく SceneDelegate でインスタンス化されます。

エージェントの動作

• まず監査し、次に報告し、最後に編集します。開発者が調査結果を確認して承認するまでは、ファイルを変更しないでください。
• 既存の SceneDelegate.swift、AppDelegate.swift、または Info.plist の構造を上書きしないでください。references/surgical-merges.md に従って、必要な箇所のみを慎重にマージしてください。
• CLI を優先してください。プロジェクトが対象条件を満たす（Phase 3）場合は、ファイルを手動で編集する代わりに npx cap migrate を実行してください。
• Phase 6 の判断が必要な場面では、決めつけずに質問してください。利用できる場合は AskUserQuestion を使用し、それ以外の場合は通常のテキストで質問して回答を待ってください。
• コミット、ステージング、プッシュはしないでください。バージョン管理は開発者に任せてください。
• プラグインリポジトリでは、Info.plist、AppDelegate.swift、プロジェクトファイルには一切触れないでください。プラグインの分岐では、監査とアドバイスのみを行います。

手順

Phase 1: リポジトリの種類を判定する

何よりも先に、アプリかプラグインかを判定してください。

• アプリ：ios/App/App.xcodeproj（または ios/ プラットフォームディレクトリを含む capacitor.config.*）がある。
• プラグイン：Capacitor に依存する Package.swift または .podspec があり、ios/Sources または ios/Plugin に CAPPlugin／CapacitorPlugin のサブクラスがあり、App/App.xcodeproj はない。

プラグインリポジトリの場合 → Phase 10 に進んでください （references/plugin-repo-audit.md）。

Phase 2: パッケージマネージャーとバージョンを判定する

• CocoaPods と SPM：ios/App/Podfile があれば CocoaPods、Package.swift または Xcode プロジェクト内に SPM の参照があれば SPM です。これは npx cap sync ios の動作に影響しますが、SceneDelegate の内容には影響しません。8.5 のテンプレートには、どちらにも対応する SceneDelegate が用意されています。
• package.json で @capacitor/ios のバージョンを確認してください。8.5 未満の場合、依存関係の更新はマイグレーションに含まれます。CLI のマイグレーターが処理するか、ガイドに従って手動で更新してください。

Phase 3: プロジェクトの状態を分類する

CLI マイグレーターが使用するのと同じ、次の 3 つのシグナルを確認してください。

1. Info.plist に UIApplicationSceneManifest が含まれている
2. アプリのターゲットディレクトリ内に SceneDelegate.swift が存在する（pbxproj への登録は別の問題であり、Phase 7 で処理します）
3. AppDelegate.swift に UISceneConfiguration(name: が含まれている

シグナルの数	状態	手順
3 つ中 0	対象条件を満たす	Phase 4～6 の後、Phase 7a：npx cap migrate に引き継ぐ
3 つ中 3	マイグレーション済み	監査のみ（Phase 4）の後、検証（Phase 9）
3 つ中 1～2	一部のみ適用済み	Phase 4～6 の後、Phase 7b：必要な箇所のみを慎重にマージする

どの手順でも、何かを実行または変更する前に監査を行います。手順の違いは、誰が変更を適用するかだけです。

CLI は仕様上、一部のみ適用された状態を警告してスキップします。この状態こそ、このスキルが独自に編集を行う場面です。

Phase 4: コードベースを監査する

references/audit-patterns.md にあるスキャンを、アプリの iOS ソースとインストール済みプラグイン（node_modules/@capacitor* に加え、ローカルのプラグインパスがあればそのパス）に対して実行してください。次の項目について調査結果を収集します。

• UIApplication.shared.applicationState の使用箇所
• ApplicationDelegateProxy への転送処理を超える、カスタムの application(_:open:)／application(_:continue:) の本体
• AppDelegate のライフサイクルメソッド内のカスタムコード
• 既存の SceneDelegate.swift の実装とその内容
• tmpWindow／TmpViewController の参照箇所（8.5 ではビルドエラーになります）
• 既存または一部のみ適用された UIApplicationSceneManifest のエントリ
• .capacitorOpenURL／.capacitorOpenUniversalLink のオブザーバー（情報提供のみ：引き続き動作します）

Phase 5: 調査結果を提示し、確認を得る

何かに触れる前に、すべての調査結果をファイル名と行番号とともに報告してください。次のように分類します。ビルドを妨げるもの（tmpWindow／TmpViewController）、判断が必要なもの（カスタムのデリゲート本体、既存の SceneDelegate）、情報提供のみのもの（オブザーバー、開発者が所有していないプラグイン内の applicationState）。続行してよいか、開発者に確認してください。

フェーズ 6：判断が必要な項目

最低限、次の点を確認します。

1. レガシー URL ハンドラー：AppDelegate.swift の application(_:open:options:)／application(_:continue:) を残すか削除するか。 シーンを使う場合、これらは不要なコードになります。残しても問題はありませんが、 削除したほうがすっきりします。本文にカスタムロジックが含まれている場合は、 どちらにする場合でも SceneDelegate に移す必要があります。対象となるルートでは、 CLI の実行後に回答を適用します。
2. カスタムの application(_:open:) 本文：手動で移行する（開発者がロジックを移す） か、スキルでプロキシ転送処理とともに scene(_:openURLContexts:) に移すかを確認します。確認する前に本文を提示します。 監査テストで転送処理のみと判定された場合は、この質問を省略します。
3. 既存の SceneDelegate：提案する挿入箇所（不足している転送処理、ウィンドウの設定） をそれぞれ差分として提示し、適用前に確認します。

フェーズ 7a：対象プロジェクト → CLI による引き継ぎ

最初に、解決された CLI を確認します。node_modules がない場合は npm install を実行し、 続けて npx cap --version を実行します。UIScene 移行ツールには 8.5 以降が必要です。 次に npx cap migrate を実行し、その出力を解釈します。このコマンドは SceneDelegate.swift を書き込み、Info.plist と AppDelegate.swift にパッチを適用し、 project.pbxproj にファイルを登録します。また、フェーズ 4 のスキャンパターンに ついて警告し、移行ガイドへのリンクを表示します。各手順のログ行を確認します。 CLI が手順をスキップした場合（ファイルがすでに存在する、または部分的な状態が 同時に発生した場合など）は、その手順に限り、フェーズ 7b に進みます。

フェーズ 7b：部分移行または手動移行 → 必要箇所のみ統合

references/surgical-merges.md に従い、不足している部分だけを 適用します。

• マニフェストがない → 既存のキーを維持しながら、UIApplicationSceneManifest を Info.plist に統合します
• configurationForConnecting がない → AppDelegate.swift の既存クラスの閉じ波括弧の 前に挿入します。既存のコードは置き換えません
• SceneDelegate.swift がない、または不完全 → references/scene-delegate-template.md から作成するか、 既存のカスタムロジックを維持しながら、不足している SceneDelegateProxy.shared の 転送処理を追加します
• 新しいファイル → project.pbxproj に登録します（IDE からファイルを追加すると Xcode が 登録します。それ以外の場合はリファレンスに従います）

フェーズ 8：同期とビルド

npx cap sync ios を実行します。Xcode が利用できる場合は、アプリのターゲットをビルドし、 エラーがあれば提示します（最もよくあるのは、残っている tmpWindow の参照です）。

フェーズ 9：確認チェックリスト

詳細についてはガイドにリンクしながら、開発者と次の項目を確認します。

• アプリが Web ビューを表示して起動する
• アプリをバックグラウンドに移してからフォアグラウンドに戻すと、JavaScript の resume／pause が発生する（これらは現在、アプリのシーンにスコープされています）
• カスタム URL スキーム：コールド起動と起動中の両方で URL が渡される （appUrlOpen リスナーと App.getLaunchUrl()）
• アプリでユニバーサルリンクを使用している場合は、その動作を確認する （関連付けられたドメインが必要です）

フェーズ 10：プラグインリポジトリの分岐

アプリレベルのファイルにはパッチを適用しません。 references/plugin-repo-audit.md に従ってプラグインの Swift コードを監査し、 シーンの使用時に問題を起こすライフサイクルの前提、8.5 で削除された API、 1 つのプラグインバージョンで 8.4 と 8.5 の両方をサポートするための互換性ルールを報告します。 コードの変更は、開発者から依頼された場合に限り、プラグイン独自のソースコードにのみ適用します。

ベストプラクティス

実施すること

• 適用前に差分を提示する
• すべての指摘をファイルと行に結び付ける
• 編集後にフェーズ 3 の分類を再実行し、プロジェクトが完全に移行済みと判定されることを確認する
• 8.4 をサポートする間は、従来の通知名を維持するようプラグイン作成者に伝える

実施しないこと

• ユーザーのコードを上書きしない
• node_modules 内のサードパーティープラグインのコードを書き換えない（問題を報告し、修正は上流に委ねる）
• 対象プロジェクトで CLI が行う処理を、手動編集で重複して行わない
• テスト用の関連付けられたドメインがない状態で、ユニバーサルリンクの動作を保証しない

エラー処理

• npx cap migrate が「partial state」と警告します → 想定どおりです。このスキルにはそのための フェーズ 7b があります。確認せずにプロジェクトをリセットしないでください。
• project.pbxproj の編集に失敗する、またはプロジェクトを開けなくなります → pbxproj の変更を元に戻し、 代わりに Xcode からファイルを登録してください。
• tmpWindow / TmpViewController でビルドに失敗します → これらの参照を削除する必要があります。8.5 での置き換え先はありません（ブリッジの viewController がプレゼンテーションのアンカーです）。
• SceneDelegate が存在するのにアプリに黒い画面が表示されます → デリゲートがウィンドウを作成せず、ストーリーボードにも作成させていません。テンプレートのウィンドウ設定を追加してください。

関連スキル

• cordova-plugin-migrator：Cordova プラグインから Capacitor への移行
• capacitor-plugin-generator：新しい Capacitor プラグインのスキャフォールド

参考資料

ファイル	用途
references/scene-delegate-template.md	8.5 の SceneDelegate テンプレートとカスタムサブクラスのバリエーション
references/audit-patterns.md	コマンドを含む正確なスキャンパターン
references/surgical-merges.md	部分的なプロジェクトおよび手作業で構築されたプロジェクト向けのマージ手順
references/plugin-repo-audit.md	プラグイン作成者向けブランチ：監査と互換性のルール