feat: disable background throttling

.changes/disable-background-throttling.md

@@ -0,0 +1,11 @@
+---
+'tauri-cli': 'minor'
+'tauri-runtime': 'minor'
+'tauri-runtime-wry': 'minor'
+'tauri-schema-generator': 'minor'
+'tauri-utils': 'minor'
+'tauri': 'minor'
+'@tauri-apps/api': 'minor'
+---
+
+Add an option to disable background throttling (currently for WebKit only).

crates/tauri-cli/config.schema.json

@@ -516,6 +516,11 @@
               "type": "null"
             }
           ]
+        },
+        "disableBackgroundThrottling": {
+          "description": "Set whether background throttling should be disabled.\n\n By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when\n a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "default": false,
+          "type": "boolean"
         }
       },
       "additionalProperties": false

crates/tauri-cli/schema.json

@@ -465,6 +465,11 @@
           "description": "Whether page zooming by hotkeys is enabled\n\n ## Platform-specific:\n\n - **Windows**: Controls WebView2's [`IsZoomControlEnabled`](https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2settings?view=webview2-winrt-1.0.2420.47#iszoomcontrolenabled) setting.\n - **MacOS / Linux**: Injects a polyfill that zooms in and out with `ctrl/command` + `-/=`,\n 20% in each step, ranging from 20% to 1000%. Requires `webview:allow-set-webview-zoom` permission\n\n - **Android / iOS**: Unsupported.",
           "default": false,
           "type": "boolean"
+        },
+        "disableBackgroundThrottling": {
+          "description": "Set whether background throttling should be disabled\n\n Will prevent the browser from suspending the WebView's tab and all its tasks while running in background after ~5 Minutes.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "default": false,
+          "type": "boolean"
         }
       },
       "additionalProperties": false

crates/tauri-cli/tauri.config.schema.json

@@ -465,6 +465,11 @@
           "description": "Whether page zooming by hotkeys is enabled\n\n ## Platform-specific:\n\n - **Windows**: Controls WebView2's [`IsZoomControlEnabled`](https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2settings?view=webview2-winrt-1.0.2420.47#iszoomcontrolenabled) setting.\n - **MacOS / Linux**: Injects a polyfill that zooms in and out with `ctrl/command` + `-/=`,\n 20% in each step, ranging from 20% to 1000%. Requires `webview:allow-set-webview-zoom` permission\n\n - **Android / iOS**: Unsupported.",
           "default": false,
           "type": "boolean"
+        },
+        "disableBackgroundThrottling": {
+          "description": "Set whether background throttling should be disabled\n\n Will prevent the browser from suspending the WebView's tab and all its tasks while running in background after ~5 Minutes.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "default": false,
+          "type": "boolean"
         }
       },
       "additionalProperties": false

crates/tauri-runtime-wry/src/lib.rs

@@ -4180,6 +4180,7 @@ fn create_webview<T: UserEvent>(
     .with_accept_first_mouse(webview_attributes.accept_first_mouse)
     .with_incognito(webview_attributes.incognito)
     .with_clipboard(webview_attributes.clipboard)
+    .with_disable_background_throttling(webview_attributes.disable_background_throttling)
     .with_hotkeys_zoom(webview_attributes.zoom_hotkeys_enabled);
 
   #[cfg(any(target_os = "windows", target_os = "android"))]

crates/tauri-runtime/src/webview.rs

@@ -215,6 +215,7 @@ pub struct WebviewAttributes {
   pub use_https_scheme: bool,
   pub devtools: Option<bool>,
   pub background_color: Option<Color>,
+  pub disable_background_throttling: bool,
 }
 
 impl From<&WindowConfig> for WebviewAttributes {
@@ -225,7 +226,9 @@ impl From<&WindowConfig> for WebviewAttributes {
       .zoom_hotkeys_enabled(config.zoom_hotkeys_enabled)
       .use_https_scheme(config.use_https_scheme)
       .browser_extensions_enabled(config.browser_extensions_enabled)
+      .disable_background_throttling(config.disable_background_throttling)
       .devtools(config.devtools);
+
     #[cfg(any(not(target_os = "macos"), feature = "macos-private-api"))]
     {
       builder = builder.transparent(config.transparent);
@@ -279,6 +282,7 @@ impl WebviewAttributes {
       use_https_scheme: false,
       devtools: None,
       background_color: None,
+      disable_background_throttling: false,
     }
   }
 
@@ -444,6 +448,23 @@ impl WebviewAttributes {
     self.background_color = Some(color);
     self
   }
+
+  /// Set whether background throttling should be disabled.
+  ///
+  /// By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+  /// a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[must_use]
+  pub fn disable_background_throttling(mut self, disable: bool) -> Self {
+    self.disable_background_throttling = disable;
+    self
+  }
 }
 
 /// IPC handler.

crates/tauri-schema-generator/schemas/config.schema.json

@@ -516,6 +516,11 @@
               "type": "null"
             }
           ]
+        },
+        "disableBackgroundThrottling": {
+          "description": "Set whether background throttling should be disabled.\n\n By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when\n a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "default": false,
+          "type": "boolean"
         }
       },
       "additionalProperties": false

crates/tauri-utils/src/config.rs

@@ -1687,6 +1687,20 @@ pub struct WindowConfig {
   /// - **Windows**: On Windows 8 and newer, if alpha channel is not `0`, it will be ignored for the webview layer.
   #[serde(alias = "background-color")]
   pub background_color: Option<Color>,
+
+  /// Set whether background throttling should be disabled.
+  ///
+  /// By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+  /// a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[serde(default, alias = "disable-background-throttling")]
+  pub disable_background_throttling: bool,
 }
 
 impl Default for WindowConfig {
@@ -1739,6 +1753,7 @@ impl Default for WindowConfig {
       use_https_scheme: false,
       devtools: None,
       background_color: None,
+      disable_background_throttling: false,
     }
   }
 }
@@ -3004,6 +3019,7 @@ mod build {
       let use_https_scheme = self.use_https_scheme;
       let devtools = opt_lit(self.devtools.as_ref());
       let background_color = opt_lit(self.background_color.as_ref());
+      let disable_background_throttling = self.disable_background_throttling;
 
       literal_struct!(
         tokens,
@@ -3054,7 +3070,8 @@ mod build {
         browser_extensions_enabled,
         use_https_scheme,
         devtools,
-        background_color
+        background_color,
+        disable_background_throttling
       );
     }
   }

crates/tauri/src/webview/mod.rs

@@ -867,6 +867,23 @@ fn main() {
     self.webview_attributes.background_color = Some(color);
     self
   }
+
+  /// Set whether background throttling should be disabled.
+  ///
+  /// By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+  /// a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[must_use]
+  pub fn disable_background_throttling(mut self, disabled: bool) -> Self {
+    self.webview_attributes.disable_background_throttling = disabled;
+    self
+  }
 }
 
 /// Webview.

crates/tauri/src/webview/plugin.rs

@@ -48,6 +48,8 @@ mod desktop_commands {
     incognito: bool,
     #[serde(default)]
     zoom_hotkeys_enabled: bool,
+    #[serde(default)]
+    disable_background_throttling: bool,
   }
 
   #[cfg(feature = "unstable")]
@@ -63,6 +65,8 @@ mod desktop_commands {
       builder.webview_attributes.window_effects = config.window_effects;
       builder.webview_attributes.incognito = config.incognito;
       builder.webview_attributes.zoom_hotkeys_enabled = config.zoom_hotkeys_enabled;
+      builder.webview_attributes.disable_background_throttling =
+        config.disable_background_throttling;
       builder
     }
   }

crates/tauri/src/webview/webview_window.rs

@@ -977,6 +977,23 @@ impl<R: Runtime, M: Manager<R>> WebviewWindowBuilder<'_, R, M> {
     self.webview_builder = self.webview_builder.background_color(color);
     self
   }
+
+  /// Set whether background throttling should be disabled.
+  ///
+  /// By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+  /// a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[must_use]
+  pub fn disable_background_throttling(mut self, disabled: bool) -> Self {
+    self.webview_builder = self.webview_builder.disable_background_throttling(disabled);
+    self
+  }
 }
 
 /// A type that wraps a [`Window`] together with a [`Webview`].

crates/tests/acl/fixtures/snapshots/acl_tests__tests__scope.snap

@@ -1,6 +1,7 @@
 ---
 source: crates/tests/acl/src/lib.rs
 expression: resolved
+snapshot_kind: text
 ---
 Resolved {
     allowed_commands: {
@@ -109,9 +110,7 @@ Resolved {
                     },
                 ],
                 webviews: [],
-                scope_id: Some(
-                    3,
-                ),
+                scope_id: None,
             },
         ],
         "plugin:fs|read_file": [
@@ -202,33 +201,28 @@ Resolved {
             ],
             deny: [],
         },
-        3: ResolvedScope {
+    },
+    global_scope: {
+        "fs": ResolvedScope {
             allow: [
                 Map(
                     {
                         "path": String(
-                            "$DOWNLOAD",
+                            "$APP",
                         ),
                     },
                 ),
                 Map(
                     {
                         "path": String(
-                            "$DOWNLOAD/**",
+                            "$DOWNLOAD",
                         ),
                     },
                 ),
-            ],
-            deny: [],
-        },
-    },
-    global_scope: {
-        "fs": ResolvedScope {
-            allow: [
                 Map(
                     {
                         "path": String(
-                            "$APP",
+                            "$DOWNLOAD/**",
                         ),
                     },
                 ),

packages/api/src/webview.ts

@@ -767,6 +767,23 @@ interface WebviewOptions {
    * @since 2.1.0
    */
   backgroundColor?: Color
+
+  /** Set whether background throttling should be disabled.
+   *
+   * By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+   * a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+   * changes back from hidden to visible by bringing the view back to the foreground.
+   *
+   ## Platform-specific
+   *
+   * - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+   * 
+   * see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+   * 
+   * @since 2.2.0
+   * 
+   */
+  disableBackgroundThrottling?: boolean
 }
 
 export { Webview, getCurrentWebview, getAllWebviews }

packages/api/src/window.ts

@@ -1533,6 +1533,28 @@ class Window {
     return invoke('plugin:window|set_background_color', { color })
   }
 
+  /** Set whether background throttling should be disabled.
+   *
+   * By default, browsers throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when
+   * a view became minimized or hidden. This will permanently suspend all tasks until the documents visibility state
+   * changes back from hidden to visible by bringing the view back to the foreground.
+   *
+   ## Platform-specific
+   *
+   * - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+   * 
+   * see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+   * 
+   * @since 2.2.0
+   * 
+   */
+  async setDisableBackgroundThrottling(disable: boolean): Promise<void> {
+    return invoke('plugin:window|set_disable_background_throttling', {
+      label: this.label,
+      value: disable
+    })
+  }
+
   /**
    * Changes the position of the cursor in window coordinates.
    * @example
@@ -2338,6 +2360,17 @@ interface WindowOptions {
    * @since 2.1.0
    */
   backgroundColor?: Color
+  /**
+   * Set whether background throttling should be disabled
+   *
+   * #### Platform-specific
+   * - **Linux / Windows / Android**: Unsupported yet. But workarounds like a pending WebLock transaction might suffice.
+   *
+   * see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+   *
+   * @since 2.2.0
+   */
+  disableBackgroundThrottling?: boolean
 }
 
 function mapMonitor(m: Monitor | null): Monitor | null {