[webview_flutter_wkwebview] Add support for custom URL scheme handlers

[brlumen]

Adds support for loading resources with custom URL schemes on iOS and macOS by wrapping the native WKURLSchemeHandler API.

New public API:

• WebKitWebViewControllerCreationParams.urlSchemeHandlers — a map of URL scheme to handler. Handlers are registered at creation time because WKWebViewConfiguration.setURLSchemeHandler only takes effect before the WKWebView is created.
• WebKitUrlSchemeHandler — onStart/onStop callbacks receiving a WebKitUrlSchemeTask.
• WebKitUrlSchemeTask — exposes the request url/httpMethod and the reply methods didReceiveResponse, didReceiveData, didFinish, and didFail.

Internal changes:

• New Pigeon ProxyApis: WKURLSchemeHandler (Dart-implemented, modeled after WKScriptMessageHandler) and WKURLSchemeTask; WKWebViewConfiguration.setURLSchemeHandler; constructors for the existing HTTPURLResponse, URLResponse, and NSError ProxyApis (needed to build responses from Dart).
• Calling a WKURLSchemeTask method after the web view has stopped the task raises NSException. Since the stop notification inherently races in-flight platform channel calls, the native side tracks stopped tasks (via an associated object) and turns late calls into no-ops; the equivalent race on the Dart side (stop arriving while the start handler is still reading the request) is also handled.

Tests:

• Dart unit tests for the new wrapper API.
• Native XCTests for the new ProxyApi delegates, including the stopped-task no-op guard.
• Integration tests in the example app covering: serving an image to a real WKWebView, stopping an in-flight task when the page is replaced (with late replies being no-ops), delivering a large (3 MB) response body via main frame navigation to a custom scheme URL, and 24 concurrent requests on one page.

Example use case: an email client that rewrites cid: inline-image references to a custom scheme and serves the bytes from its local attachment cache. WKWebView cannot intercept http(s): requests, so a custom scheme handler is the platform-sanctioned counterpart of Android's shouldInterceptRequest for serving locally cached subresources.

Part of flutter/flutter#27896 (implements the iOS/macOS side).

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

Footnotes

1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

[gemini-code-assist]

Code Review

This pull request implements support for custom URL schemes in webview_flutter_wkwebview via the native WKURLSchemeHandler API, introducing WebKitUrlSchemeHandler and WebKitUrlSchemeTask along with their native Swift delegates and Pigeon bindings. The review feedback identifies a potential memory leak in _registerUrlSchemeHandler where tasks can remain in stoppedBeforeStart indefinitely, and recommends setting _stopped to true upon task completion to safeguard against post-completion calls.

[bparrishMines]

@brlumen Does Android's WebViewClient.shouldInterceptRequest also handle custom URL schemes? If so then I think this feature would also require an Android implementation as well as an update to the platform interface and app-facing interface.

[brlumen]

@bparrishMines Yes — shouldInterceptRequest does get invoked for custom URL schemes on Android, and a Dart-accessible counterpart there is something I'd very much like to have myself. In my app the chat screen has two implementations on Android: a native one (for unrelated historical reasons), where a shouldInterceptRequest interceptor serves locally cached email resources, and a webview_flutter-based one, which has no interception available and currently has to fall back to inlining resources as data URIs. An Android counterpart of this API would let the Flutter path use the same mechanism.

The catch is the threading contract. shouldInterceptRequest must return a WebResourceResponse synchronously on a Chromium worker thread, while platform channels are inherently asynchronous. As far as I can tell, there is still no way to synchronously invoke Dart from an arbitrary native thread (FFI callbacks are isolate-thread-only, and platform isolates never stabilized) — which I believe is the same conclusion reached in flutter/flutter#27896.

The only practical bridge is a bounded-wait latch: block the worker thread, post the request to Dart over the channel, and CountDownLatch.await with a timeout, degrading to an empty response on expiry. This is legal (the reply arrives on the unblocked main thread) and flutter_inappwebview has shipped this design for years, but it has real costs: every subresource pays a channel round-trip, and a busy Dart isolate stalls all in-flight resource loads for the page.

So before scoping this out, I'd like your take on the design question: is a latch-based shouldInterceptRequest bridge acceptable for webview_flutter_android in principle?

• If yes — I'm happy to work on the federated version (platform interface + app-facing API + Android implementation) as a follow-up series.
• If no (i.e. Android should wait for a proper synchronous-Dart mechanism) — then no Android implementation can exist yet regardless of how this feature is shaped, and I'd suggest landing the WebKit capability platform-specifically for now, following the precedent of other WebKit-only surface in WebKitWebViewControllerCreationParams (limitsNavigationsToAppBoundDomains, javaScriptCanOpenWindowsAutomatically, etc.). Notably WKURLSchemeHandler is also semantically narrower than shouldInterceptRequest (it cannot intercept http(s): at all), so a future shared interface would likely target only the custom-scheme subset anyway — and adding it later would be non-breaking.