Expose local-content serving in NativeWebView (custom scheme + response synthesis) — implement on WebKitGTK/WPE

[dcuccia]

Is your feature request related to a problem? Please describe.

NativeWebView can embed the engine, navigate, run JS, exchange messages, and it raises WebResourceRequested on every platform (including GTK/WPE) — but there's no way to fulfill an intercepted request with app-local bytes, and no custom URI-scheme registration. That makes it impossible to serve a local app bundle offline (an SPA, or a Blazor-/Hybrid-style app). On WKWebView/WebKitGTK/WPE this specifically requires a custom scheme, because those engines can't intercept http:// (as noted in Microsoft's own PhotinoWebViewManager).

Concretely, on GTK the current WebResourceRequested is wired to WebKit's resource-load-started signal, which is observational (can't supply a response body), so it can't serve local content.

Describe the solution you'd like

A small primitive on NativeWebView, mirroring approaches already present in this repo and in Microsoft's shipping stack:

1. Register an app origin scheme (default app://), via the existing *EnvironmentRequested seam (WebKitGTK/WKWebView must register scheme handlers at context/config creation time).
2. Respond to an intercepted request with a stream — e.g. SetResponse(Stream content, int statusCode, string reason, string mimeType, headers) (+ a deferral for async/large assets).

The machinery already exists on two backends — AndroidWebViewAdapter.ShouldInterceptRequest returns a WebResourceResponse, and ICoreWebView2Environment.CreateWebResourceResponse is bound for WebView2 — so this is essentially surfacing that through the unified API and implementing it on GTK (webkit_web_context_register_uri_scheme + webkit_uri_scheme_request_finish) and WPE. Structurally it's a near-1:1 of MAUI's WKWebView IWKUrlSchemeHandler.

Describe alternatives you've considered

• NavigateToString + a file:// base URI works for the top document but inherits file:// origin/security limits (fetch/XHR, ES-module CORS, service workers, and the virtual origin SPAs expect).
• Header-only mutation on the current WebResourceRequested event isn't enough — there's no response body.
• A localhost HTTP server defeats the offline/no-server goal.

Additional context

I put together a design write-up and drafted a potential approach (an illustrative spike — not yet build-wired) that mirrors your existing patterns and Microsoft's shipping code:

• Design + Microsoft prior-art (WebViewManager/StaticContentProvider reuse, per-platform interception table, downstream MAUI HybridWebViewHandler/BlazorWebViewHandler story): Design: Port Microsoft's BlazorWebView/HybridWebView content-serving model to NativeWebView (enable offline hybrid apps incl. Linux) dcuccia/Avalonia.Controls.WebView#1
• WebKitGTK/WPE spike (concrete P/Invoke, a GtkUriSchemeHandler callback in your GtkSignal.TryGetState style, and the one-line wiring into GtkWebViewAdapter's context-creation path): https://github.com/dcuccia/Avalonia.Controls.WebView/blob/spike/webkitgtk-uri-scheme-serving/docs/design/webkitgtk-uri-scheme-spike.md

Main questions before I take it further:

1. Is local-content serving intended / on the roadmap for NativeWebView?
2. Preferred shape — response synthesis on the interception surface, a scheme/virtual-host registration API, or both?
3. WebKitGTK vs. WPE as the primary Linux target?

Glad to shape a PR to your preferences.

[dcuccia]

Related existing issues (found these after filing — apologies for not linking sooner):

• Allow cancelling/overriding web resources in NativeWebView WebResourceRequested event #53 (override/cancel web resources in WebResourceRequested) — the response-synthesis half of this proposal. To serve local content on WKWebView/WebKitGTK/WPE you additionally need custom-scheme registration (those engines can't intercept http://), plus the GTK/WPE implementation. Happy to defer to Allow cancelling/overriding web resources in NativeWebView WebResourceRequested event #53's framing or consolidate.
• Implement CustomSchemeRegistrations in WindowsWebView2EnvironmentRequestedEvent #39 (CustomSchemeRegistrations for WebView2) — the Windows/WebView2 slice of the scheme-registration piece; Expose local-content serving in NativeWebView (custom scheme + response synthesis) — implement on WebKitGTK/WPE #57 is the cross-engine equivalent.
• [Feature-request] Consider adding Blazor Hybrid support. #21 (Blazor Hybrid support) — the downstream consumer. Notably @ScarletKuro already got a WebViewManager working over Avalonia.Controls.WebView, but was limited to Windows-only (the WebView2 interop interfaces are internal → copy-paste) and hit AOT/trimming issues. Expose local-content serving in NativeWebView (custom scheme + response synthesis) — implement on WebKitGTK/WPE #57 is the primitive that would let that same approach run on Linux. Two adjacent asks fall out of that report: (1) make the WebView2 interop surface public for WebViewManager reuse, and (2) validate the AOT/trimming path.

Net: #57 is meant as the unifying cross-engine primitive that #53 and #39 are facets of, and that #21 depends on — not a competing proposal. Glad to consolidate however the team prefers.