Add spec: Throttling Control - Script

specs/ThrottlingControlScript.md

@@ -0,0 +1,291 @@
+Throttling Control - Script Throttling
+===
+
+# Background
+Web content in WebView2 is generally subject to the same Web Platform
+restrictions as in the Microsoft Edge browser. However, some of the scenarios
+for WebView2 applications differ from the scenarios in the browser. For this
+reason, we're providing a set of APIs to fine-tune performance of scripts
+running in WebView2. These APIs allow WebView2 applications to achieve two
+things:
+
+* Customize script timers (`setTimeout` and `setInterval`) throttling under
+different page states (foreground, background, and background with intensive
+throttling)
+* Throttle script timers in select hosted iframes
+
+# Examples
+
+## Throttle timers in visible WebView
+
+Throttling Control APIs allow you to throttle JavaScript timers in scenarios
+where the WebView2 control in your application needs to remain visible, but
+consume less resources, for example, when the user is not interactive.
+
+```c#
+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 500);
+}
+
+void OnUserInteraction()
+{
+    // User is interactive again, unthrottle foreground timers.
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 0);
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::OnNoUserInteraction()
+{
+    auto webView21 = m_webview.try_query<ICoreWebView2_21>();
+    CHECK_FEATURE_RETURN_EMPTY(webView21);
+
+    // User is not interactive, keep webview visible but throttle timers to
+    // 500ms.
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 500));
+}
+
+void ScenarioThrottlingControl::OnUserInteraction()
+{
+    auto webView21 = m_webview.try_query<ICoreWebView2_21>();
+    CHECK_FEATURE_RETURN_EMPTY(webView21);
+
+    // User is interactive again, unthrottle foreground timers.
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 0));
+}
+```
+
+## Unthrottle timers in hidden WebView
+
+Throttling Control APIs allow you to set a custom throttling interval for timers
+on hidden WebViews. For example, if there's logic in your app that runs in
+JavaScript but doesn't need to render content, you can keep the WebView hidden
+and unthrottle its timers.
+
+```C#
+void SetupHiddenWebViewCore()
+{
+    // This WebView2 will remain hidden but needs to keep running timers.
+    // Unthrottle background timers.
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 0);
+    // Effectively disable intensive throttling by overriding its timer interval.
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 0);
+    webView.Visibility = System.Windows.Visibility.Hidden;
+}
+
+void DisableHiddenWebViewCore()
+{
+    webView.Visibility = System.Windows.Visibility.Visible;
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 1000);
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 60000);
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::SetupHiddenWebViewCore()
+{
+    auto webView21 = m_webview.try_query<ICoreWebView2_21>();
+    CHECK_FEATURE_RETURN_EMPTY(webView21);
+
+    // This WebView2 will remain hidden but needs to keep running timers.
+    // Unthrottle background timers.
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 0));
+    // Effectively disable intensive throttling by overriding its timer interval.
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 0));
+
+    CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE));
+}
+
+void ScenarioThrottlingControl::DisableHiddenWebViewCore()
+{
+    CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(TRUE));
+
+    auto webView21 = m_webview.try_query<ICoreWebView2_21>();
+    CHECK_FEATURE_RETURN_EMPTY(webView21);
+
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 1000));
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 60000));
+}
+```
+
+## Throttle timers in hosted iframes
+
+Throttling Control APIs allow you to throttle timers in specific frames within
+the WebView2 control. For example, if your application uses iframes to host 3rd
+party content, you can select and mark these frames to be throttled separately
+from the main frame and other regular, unmarked frames.
+
+```C#
+void SetupUntrustedFramesHandler()
+{
+    webView.CoreWebView2.FrameCreated += (sender, args) =>
+    {
+        // You can use the frame properties to determine whether it should be
+        // marked to be throttled separately from main frame.
+        if (args.Frame.Name == "untrusted")
+        {
+            args.Frame.IsUntrusted = true;
+        }
+    };
+
+    webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.UntrustedFrame, 500);
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::SetupUntrustedFramesHandler()
+{
+    auto webview4 = m_webview.try_query<ICoreWebView2_4>();
+    CHECK_FEATURE_RETURN_EMPTY(webview4);
+
+    // You can use the frame properties to determine whether it should be
+    // marked to be throttled separately from main frame.
+    CHECK_FAILURE(webview4->add_FrameCreated(
+        Callback<ICoreWebView2FrameCreatedEventHandler>(
+            [this](ICoreWebView2* sender, ICoreWebView2FrameCreatedEventArgs* args) -> HRESULT
+            {
+                wil::com_ptr<ICoreWebView2Frame> webviewFrame;
+                CHECK_FAILURE(args->get_Frame(&webviewFrame));
+
+                auto webviewFrame6 =
+                    webviewFrame.try_query<ICoreWebView2Frame6>();
+                CHECK_FEATURE_RETURN_HRESULT(webviewFrame6);
+
+                wil::unique_cotaskmem_string name;
+                CHECK_FAILURE(webviewFrame->get_Name(&name));
+                if (wcscmp(name.get(), L"untrusted") == 0)
+                {
+                    CHECK_FAILURE(webviewFrame6->put_IsUntrusted(TRUE));
+                }
+
+                return S_OK;
+            })
+            .Get(),
+        &m_frameCreatedToken));
+
+    auto webView21 = m_webview.try_query<ICoreWebView2_21>();
+    CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
+        COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME, 500));
+}
+```
+
+# API Details
+```cpp
+[v1_enum]
+typedef enum COREWEBVIEW2_THROTTLING_CATEGORY {
+  /// Applies to frames whose WebView is in foreground state. WebViews whose
+  /// `IsVisible` property is `TRUE` are in this state. The default value is a
+  /// constant determined by the running version of the WebView2 Runtime.
+  COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND,
+
+  /// Applies to frames whose WebView is in background state. WebViews whose
+  /// `IsVisible` property is `FALSE` are in this state. The default value is a
+  /// constant determined by the running version of the WebView2 Runtime.
+  /// All other background state policies (including intensive throttling) are
+  /// effective independently of this setting.
+  COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND,
+
+  /// Applies to frames whose WebView is being intensively throttled (a
+  /// sub-state of background state). For more details about intensive
+  /// throttling, see [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
+  /// The default value is a constant determined by the running version of the
+  /// WebView2 Runtime.
+  COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE,
+
+  /// Applies to frames that have been marked untrusted by the host app.
+  /// This is a category specific to WebView2 with no corresponding state in the
+  /// Chromium tab state model. The default value is a constant determined by
+  /// the running version of the WebView2 Runtime.
+  COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME
+} COREWEBVIEW2_THROTTLING_CATEGORY;
+
+/// A continuation of the `ICoreWebView2` interface to support ThrottlingPreference.
+[uuid(00f1b5fb-91ed-4722-9404-e0f8fd1e6b0a), object, pointer_default(unique)]
+interface ICoreWebView2_21 : ICoreWebView2_20 {
+  /// Get the preferred wake up interval (in milliseconds) for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), for the given
+  /// throttling category. A wake up interval is the amount of time that needs
+  /// to pass before the WebView2 Runtime checks for new timer tasks to run.
+  /// The default interval values are constants determined by the running
+  /// version of the WebView2 Runtime.
+  HRESULT GetThrottlingIntervalPreference(
+      [in] COREWEBVIEW2_THROTTLING_CATEGORY category,
+      [out, retval] UINT32* intervalInMilliseconds);
+
+  /// Sets the preferred wake up interval (in milliseconds) for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), for the given
+  /// throttling category. A wake up interval is the amount of time that needs
+  /// to pass before the WebView2 Runtime checks for new timer tasks to run. For
+  /// example, an application might use a foreground value of 30 ms for moderate
+  /// throttling scenarios, or match the default background value (usually 1000
+  /// ms). The WebView2 Runtime will try to respect the preferred interval set
+  /// by the application, but the effective value will be constrained by
+  /// resource and platform limitations. Setting a value of `0` means no
+  /// throttling will be applied.
+  HRESULT SetThrottlingIntervalPreference(
+      [in] COREWEBVIEW2_THROTTLING_CATEGORY category,
+      [in] UINT32 intervalInMilliseconds);
+}
+
+/// A continuation of the `ICoreWebView2Frame` interface to support IsUntrusted property.
+[uuid(5b7d1b96-699b-44a2-b9f1-b8e88f9ac2be), object, pointer_default(unique)]
+interface ICoreWebView2Frame6 : ICoreWebView2Frame5 {
+  /// The `IsUntrusted` property indicates whether the frame has been marked
+  /// untrusted by the host app. Untrusted frames will receive a different
+  /// script throttling category as compared to regular frames. Defaults to
+  /// `FALSE` unless set otherwise. When `FALSE`, and for main frame, throttling
+  /// category will be determined by page state. The corresponding preferred
+  /// interval will apply (set through `SetThrottlingIntervalPreference`).
+  [propget] HRESULT IsUntrusted([out, retval] BOOL* value);
+
+  /// Marks the frame as untrusted, for script throttling purposes.
+  [propput] HRESULT IsUntrusted([in] BOOL value);
+}
+
+```
+
+```C#
+namespace Microsoft.Web.WebView2.Core
+{
+    enum CoreWebView2ThrottlingCategory
+    {
+        Foreground = 0,
+        Background = 1,
+        Intensive = 2,
+        UntrustedFrame = 3,
+    };
+
+    runtimeclass CoreWebView2
+    {
+        // ...
+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_21")]
+        {
+            UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category);
+
+            void SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category, UInt32 intervalInMilliseconds);
+        }
+    }
+
+    runtimeclass CoreWebView2Frame
+    {
+        // ...
+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")]
+        {
+            Boolean IsUntrusted { get; set; };
+        }
+    }
+}
+
+```
+
+# Appendix