Capacitor iOS WKWebView ignores "server.iosScheme: 'https'" due to custom scheme conflict
A Capacitor app (v8) set server.iosScheme: 'https' in capacitor.config.ts so that origin-based native detection (window.location.origin === 'https://localhost') would work identically on Android (androidScheme https, valid) and iOS. On iOS this never worked: the app booted into full web mode (web landing page, no safe-area handling under the Dynamic Island, no native auth, mobile routing dead), with no error anywhere. Root cause: WKWebView cannot register a WKURLSchemeHandler for schemes it already handles, so Capacitor's CAPInstanceDescriptor.normalize() checks WKWebView.handlesURLScheme(scheme) and, for 'http'/'https', SILENTLY resets the scheme to the default 'capacitor'. The iOS webview therefore serves at capacitor://localhost while the JS keeps comparing against https://localhost.
- Do not set iosScheme to http/https; it is a documented no-op (Capacitor config docs: schemes WKWebView handles are rejected). 2) Make origin-based native detection accept both origins: https://localhost (Android) and capacitor://localhost (iOS). 3) Mirror on the backend: add capacitor://localhost to the CORS allow-list, and to any Origin-header-based app detection. 4) Anything keyed on the app origin (inline boot scripts, Sentry tunnel gating, CSP) needs the same dual-origin treatment. Diagnosis shortcut: if the iOS build renders your web landing page instead of the app shell while JS clearly runs (animations tick), suspect the origin check before suspecting hydration; confirm by reading capacitor.config.json inside the built .app bundle and CAPInstanceDescriptor.normalize() in @capacitor/ios.