macOS: unhandled JavaScriptException in async void OnDelegateOnDidFinishNavigation crashes the whole process on non-scriptable navigation (e.g. file download)

[szemeredipeter-prog]

Describe the bug

On macOS (Apple Silicon), when the WKWebView backend used by Avalonia.Controls.WebView navigates to a URL whose response is not a scriptable HTML document, the whole process can crash with an unhandled Avalonia.Controls.JavaScriptException.

Observed with ChatGPT-generated file download links. The same application code using the Windows WebView2 backend does not crash on the equivalent download.

The crash occurs inside the macOS adapter. MaciosWebViewAdapter.OnDelegateOnDidFinishNavigation unconditionally calls InvokeScript(...) after navigation finishes. If JavaScript cannot be executed in the resulting document, InvokeScript rethrows the native WebKit failure as JavaScriptException. Because the navigation completion handler is async void and does not catch that exception, the exception escapes and terminates the process.

Reproduced 3 times across two test sessions with an identical stack trace. Application-level attempts to cancel navigation, intercept only NewWindowRequested, and run with no custom navigation handlers did not prevent the crash.

To Reproduce

1. Run an Avalonia application on macOS Apple Silicon with a NativeWebView.
2. Navigate to a page containing a downloadable file link.
3. Click a link whose response is a file/download response rather than a normal scriptable HTML page.
4. Observe that the process exits with an unhandled Avalonia.Controls.JavaScriptException.

Observed in practice with ChatGPT-generated downloads.

A standalone example target would be an <a href="/download"> where /download responds with:

• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename=test.txt

Expected behavior

Navigating to or initiating a file download must not crash the entire application process.

At minimum, failure to inject the C#↔JavaScript bridge into a non-scriptable document should be handled gracefully.

Actual native file-download support can be treated as a separate feature/fix.

Avalonia WebView version

12.1.0

Avalonia version

12.1.1

OS

macOS

Additional context

Environment:

• macOS, Apple Silicon (osx-arm64)
• Target framework: net8.0
• dotnet publish -r osx-arm64 -c Debug --self-contained
• Also reproduces in Release
• .NET SDK used to build: 10.0.400
• Windows/WebView2 backend, same app code: does not crash on the equivalent download

Stack trace:

Unhandled exception. Avalonia.Controls.JavaScriptException: Cannot execute JavaScript in this document
 ---> Avalonia.Controls.Macios.Interop.NSErrorException: A JavaScript exception occurred
   at Avalonia.Controls.Macios.Interop.WebKit.WKWebView.EvaluateJavaScriptAsync(String script)
   at Avalonia.Controls.Macios.MaciosWebViewAdapter.InvokeScript(String script)
   at Avalonia.Controls.Macios.MaciosWebViewAdapter.OnDelegateOnDidFinishNavigation(Object sender, EventArgs args)
   ...

Source-level confirmation:

private async void OnDelegateOnDidFinishNavigation(object? sender, EventArgs args)
{
    _ = await InvokeScript(WebViewHelper.BuildWebKitInvokeCSharpActionScript(_scriptHandlerMessageName, stringify: true));

    using var url = _webView.Url;
    NavigationCompleted?.Invoke(this, new WebViewNavigationCompletedEventArgs { Request = Uri.TryCreate(url!.AbsoluteString, UriKind.Absolute, out var uri) ? uri : null, IsSuccess = true });
}

InvokeScript converts the native WebKit JavaScript failure into JavaScriptException, and the async void completion handler does not catch it.

Suggested crash-safety fix:

private async void OnDelegateOnDidFinishNavigation(object? sender, EventArgs args)
{
    try
    {
        _ = await InvokeScript(WebViewHelper.BuildWebKitInvokeCSharpActionScript(_scriptHandlerMessageName, stringify: true));
    }
    catch (JavaScriptException)
    {
        // Bridge injection failure must not terminate the process.
    }

    using var url = _webView.Url;
    NavigationCompleted?.Invoke(this, new WebViewNavigationCompletedEventArgs { Request = Uri.TryCreate(url!.AbsoluteString, UriKind.Absolute, out var uri) ? uri : null, IsSuccess = true });
}

This proposed change is intentionally scoped only to preventing the process crash. Full download support is separate.

[szemeredipeter-prog]

Update: built and tested the proposed fix — confirmed working

We didn't just propose the try/catch blind — we built it and tested it end to end on macOS (Apple Silicon).

What we did:

1. Cloned this repo locally.
2. Applied exactly this diff to MaciosWebViewAdapter.OnDelegateOnDidFinishNavigation:

private async void OnDelegateOnDidFinishNavigation(object? sender, EventArgs args)
{
    try
    {
        _ = await InvokeScript(WebViewHelper.BuildWebKitInvokeCSharpActionScript(_scriptHandlerMessageName, stringify: true));
    }
    catch (JavaScriptException)
    {
        // The just-loaded document isn't scriptable (e.g. a file/binary/PDF response instead
        // of HTML) - the C#<->JS bridge simply isn't available for this navigation, which is
        // not itself an application-fatal condition.
    }

    using var url = _webView.Url;
    NavigationCompleted?.Invoke(this, new WebViewNavigationCompletedEventArgs { Request = Uri.TryCreate(url!.AbsoluteString, UriKind.Absolute, out var uri) ? uri : null, IsSuccess = true });
}

[szemeredipeter-prog]

Switched our app from the Avalonia.Controls.WebView NuGet package to a ProjectReference against the patched local clone (net8.0, osx-arm64, self-contained publish — same config as the original repro).
Re-ran the exact same ChatGPT file-download action that reliably crashed the process every time before (4/4 reproductions).

Result: confirmed fix for the reproduced crash path. The process no longer crashes. It stays alive; the WKWebView navigates into the file's raw content in-place (replacing the current page — this patch only stops the crash, it doesn't add real download/save handling, which would be a separate, bigger change involving decidePolicyForNavigationResponse + WKDownloadDelegate).

One unrelated cosmetic side note on that fallback in-place render: text/background both resolved to white, so the raw content was invisible until selected/highlighted — not a crash, not caused by this patch, just worth flagging in case it's a known quirk of the plain-text/no-stylesheet render path.

To be precise about scope: we validated this against the real ChatGPT download flow that originally reproduced the crash. We have not yet independently tested every possible non-scriptable MIME type, so this confirms crash containment for the reproduced path rather than claiming exhaustive MIME coverage.

Friction notes for anyone else trying to reproduce this build locally, in case it saves someone time:

build-common is a git submodule — a plain git clone leaves it empty and breaks Directory.Build.props resolution; needs git submodule update --init --recursive.
The multi-targeting (net8.0;net10.0;net10.0-android;net10.0-browser) makes a plain ProjectReference restore demand the Android workload even when only targeting net8.0. We worked around it by temporarily trimming down to net8.0;net10.0 in the local clone (not something to do for a real fix, just for local validation).
Avalonia.Controls.WebView.Core types weren't visible to our app through the outer project alone — the official build presumably ILMerges Core into the published package, which a plain ProjectReference doesn't replicate. We added a second ProjectReference straight to Avalonia.Controls.WebView.Core.csproj alongside the one to the outer project.

Happy to open this as a PR against this repo instead of just a comment, if that's preferred — let me know