feat(desktop): expose Config::with_background_throttling to opt out of WKWebView WebContent suspension

[goosewobbler]

Summary

dioxus-desktop builds on wry, which has supported WebView::with_background_throttling(BackgroundThrottlingPolicy) for a while now, but the policy is not surfaced through dioxus_desktop::Config. There is currently no way for a Dioxus desktop app to opt out of macOS WKWebView's default WebContent-process throttling — and on a headless host (CI, hidden window, no focus) that throttling indefinitely suspends every JS timer, fetch, and event handler running in the page.

Motivation

We hit this building @wdio/dioxus-service, a WebdriverIO service for automated testing of Dioxus desktop apps. Our embedded-WebDriver mode runs an Axum HTTP server inside the app process and dispatches executeScript requests to the webview through a JS polling loop. On macOS-ARM GitHub-Actions runners — no display, no user input, app window not visible — WKWebView's WebContent process gets suspended within seconds of launch, freezing the polling loop. The same test suite passes on Linux/Windows CI and on macOS interactively.

caffeinate, NSAppSleepDisabled=YES, JS-side workarounds (silent AudioContext, muted HTMLAudioElement) all failed because the throttling is WebKit-internal (not OS-level App Nap). The only fix that worked was calling WebViewBuilder::with_background_throttling(BackgroundThrottlingPolicy::Disabled) at WebView construction, which is exactly what wry exposes already.

Beyond automation, this also matters for any Dioxus desktop app that needs to do background work in the webview: long-running renderers, background music/streaming UIs, background data sync, system-tray apps with a hidden main window, etc.

Proposed API

use dioxus::desktop::wry::BackgroundThrottlingPolicy;

let config = dioxus::desktop::Config::new()
    .with_background_throttling(BackgroundThrottlingPolicy::Disabled);

Three variants from wry:

• Disabled — never throttle.
• Suspend — fully suspend tasks when the view isn't in a window (current implicit default).
• Throttle — limit rather than suspend.

The setting applies at WebView creation. On non-Apple platforms wry currently ignores the attribute, so this is effectively a macOS-only opt-out.

Implementation

PR is up at #5587 with the change against main. Cross-referencing here so the discussion thread stays in one place.

Related

• wry: https://docs.rs/wry/latest/wry/struct.WebViewBuilder.html#method.with_background_throttling
• WebKit docs on background tab throttling: https://developer.apple.com/documentation/webkit/wkwebpagepreferences/4111121-inactiveschedulingpolicy