docs: update troubleshooting and contributing with Xcode 26 findings

The SPM issue was not a fundamental Swift limitation — it's that
Capacitor 8's xcframework requires Xcode 26 ($NonescapableTypes).
Update docs to reflect the correct diagnosis and CI matrix.

Author: j3k0

capacitor/CONTRIBUTING.md

@@ -24,34 +24,25 @@ The plugin targets iOS 15.0 but some APIs require newer versions:
 
 Always wrap these in availability checks with a fallback.
 
-## SPM (Swift Package Manager) compatibility
+## SPM and Xcode version requirements
 
-The plugin builds with CocoaPods. SPM support is provided via `Package.swift` but has known limitations with Capacitor's precompiled xcframework.
+Capacitor 8 defaults to SPM and distributes its iOS framework as a precompiled `.xcframework` via `capacitor-swift-pm`. The xcframework is compiled with **Xcode 26** (Swift 6.2+), which enables `$NonescapableTypes` by default. The `.swiftinterface` files gate extension methods (`reject()`, `getString()`, `getBool()`, etc.) behind this compiler feature flag.
 
-### The problem
+**This means Capacitor 8 + SPM requires Xcode 26.** With the correct Xcode version, all APIs work natively — no workarounds needed. Use idiomatic Capacitor APIs in the plugin code.
 
-Capacitor distributes its iOS framework as a precompiled `.xcframework` via `capacitor-swift-pm`. Swift extension methods on Objective-C types are not exported from binary frameworks. This means common Capacitor APIs are invisible when built via SPM:
+Capacitor 6 and 7 use CocoaPods by default, which compiles from source. Any Xcode version that supports the deployment target (15.0) works.
 
-| API | SPM status | Workaround |
-|-----|-----------|------------|
-| `call.resolve()` | Works | (zero-arg overload) |
-| `call.resolve(data)` | Works | |
-| `call.reject(msg)` | Not available | None reliable — method is invisible |
-| `call.getString("key")` | Not available | `call.options["key"] as? String` |
-| `call.getArray("key")` | Not available | `call.options["key"] as? [Type]` |
-| `call.getBool("key")` | Not available | `call.getBool("key", false)` |
-| `CAPPluginCallError(...)` | Not available | Init is inaccessible |
+## CI matrix
 
-### Impact
-
-This is a Capacitor-level issue affecting **all** third-party plugins, not specific to this one. It needs to be resolved upstream in `ionic-team/capacitor` by either shipping source via SPM instead of precompiled binaries, or moving APIs to ObjC headers. SPM became the default in Capacitor 8.
-
-### CI strategy
-
-The CI tests against Capacitor 6 and 7 using CocoaPods (the default for those versions). Once the upstream SPM issue is resolved, Capacitor 8 can be added to the test matrix.
+| Capacitor | Runner   | Xcode | Package Manager |
+|-----------|----------|-------|-----------------|
+| 6         | macOS-14 | 15.4  | CocoaPods       |
+| 7         | macOS-14 | 15.4  | CocoaPods       |
+| 8         | macOS-15 | 26.0  | SPM             |
 
 ## CI environment notes
 
-- **macOS-15 + Xcode 16.2** may report "no destinations" with `-sdk iphoneos`. Use `-destination 'generic/platform=iOS'` instead.
+- **macOS-15 + Xcode 16.2** fails with "iOS 18.2 Platform Not Installed" on storyboard compilation. Use Xcode 26 (for Cap 8) or macOS-14 + Xcode 15.4 (for Cap 6/7).
 - **`@capacitor/create-app`** always scaffolds the latest template (Cap 8 / SPM) regardless of CLI version. For testing older versions, scaffold manually with `npm init` + pinned deps.
+- **Podfile deployment target**: Cap 6/7 generate Podfiles defaulting to iOS 13.0/14.0. The plugin needs 15.0 — CI patches this with `sed`.
 - **Ruby version conflicts** on macOS: `pod` (Homebrew) and `gem` (system) may point to different Ruby versions. Install gems with the Homebrew Ruby if needed.

capacitor/TROUBLESHOOTING.md

@@ -31,14 +31,15 @@ To test on your Mac without a physical device:
 
 This works for testing the purchase flow with sandbox accounts.
 
-## Capacitor 8 / SPM support
+## Capacitor 8 / SPM requires Xcode 26
 
-Capacitor 8 defaults to Swift Package Manager (SPM). There is a known upstream issue where the Capacitor precompiled xcframework does not export certain Swift extension methods to plugins. This affects all third-party Capacitor plugins, not just this one.
+Capacitor 8 defaults to Swift Package Manager (SPM). The Capacitor xcframework is compiled with Xcode 26 (Swift 6.2+), so **you need Xcode 26 or later** to build.
 
-**If you hit build errors with Capacitor 8**, use CocoaPods instead:
+If you see errors like `value of type 'CAPPluginCall' has no member 'reject'`, your Xcode is too old. Update to Xcode 26+.
+
+As a fallback, you can use CocoaPods instead:
 
 ```bash
-# Remove the iOS project and recreate with CocoaPods
 rm -rf ios
 npx cap add ios --packagemanager CocoaPods
 npx cap sync ios