#8547: address comments

doc/help/settings.asciidoc

@@ -293,12 +293,12 @@
 |<<prompt.radius,prompt.radius>>|Rounding radius (in pixels) for the edges of prompts.
 |<<qt.args,qt.args>>|Additional arguments to pass to Qt, without leading `--`.
 |<<qt.chromium.experimental_web_platform_features,qt.chromium.experimental_web_platform_features>>|Enables Web Platform features that are in development.
-|<<qt.chromium.lifecycle_state_discard_delay,qt.chromium.lifecycle_state_discard_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state.
-|<<qt.chromium.lifecycle_state_freeze_delay,qt.chromium.lifecycle_state_freeze_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state.
+|<<qt.chromium.lifecycle_state.discard_delay,qt.chromium.lifecycle_state.discard_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state. This state is an extreme resource-saving state, where the browsing context of the web view is discarded and the renderer process is shut down. Resource usage is therefore reduced to near-zero. The web page is automatically reloaded when needed.
+|<<qt.chromium.lifecycle_state.enabled,qt.chromium.lifecycle_state.enabled>>|Use recommended page lifecycle state.
+|<<qt.chromium.lifecycle_state.freeze_delay,qt.chromium.lifecycle_state.freeze_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state. This is a low-CPU state, where most DOM event processing, JavaScript execution, and other tasks are suspended.
 |<<qt.chromium.low_end_device_mode,qt.chromium.low_end_device_mode>>|When to use Chromium's low-end device mode.
 |<<qt.chromium.process_model,qt.chromium.process_model>>|Which Chromium process model to use.
 |<<qt.chromium.sandboxing,qt.chromium.sandboxing>>|What sandboxing mechanisms in Chromium to use.
-|<<qt.chromium.use_recommended_page_lifecycle_state,qt.chromium.use_recommended_page_lifecycle_state>>|Use recommended page lifecycle state.
 |<<qt.environ,qt.environ>>|Additional environment variables to set.
 |<<qt.force_platform,qt.force_platform>>|Force a Qt platform to use.
 |<<qt.force_platformtheme,qt.force_platformtheme>>|Force a Qt platformtheme to use.
@@ -3848,25 +3848,41 @@ Valid values:
 
 Default: +pass:[auto]+
 
-[[qt.chromium.lifecycle_state_discard_delay]]
-=== qt.chromium.lifecycle_state_discard_delay
-The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state.
+[[qt.chromium.lifecycle_state.discard_delay]]
+=== qt.chromium.lifecycle_state.discard_delay
+The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state. This state is an extreme resource-saving state, where the browsing context of the web view is discarded and the renderer process is shut down. Resource usage is therefore reduced to near-zero. The web page is automatically reloaded when needed.
+Set to -1 to disable this state.
 
 This setting is only available with the QtWebEngine backend.
 
 Type: <<types,Int>>
 
-Default: +pass:[0]+
+Default: +pass:[600000]+
 
-[[qt.chromium.lifecycle_state_freeze_delay]]
-=== qt.chromium.lifecycle_state_freeze_delay
-The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state.
+[[qt.chromium.lifecycle_state.enabled]]
+=== qt.chromium.lifecycle_state.enabled
+Use recommended page lifecycle state.
+This puts webpages into one of three lifecycle states: active, frozen, or discarded. Using the recommended lifecycle state lets the browser use less resources by freezing or discarding web views when it's safe to do so.
+This results in significant battery life savings.
+Ongoing page activity is taken into account when determining the recommended lifecycle state, as to not disrupt your browsing.
+This feature is only available on QtWebEngine 6.5+. On older versions this setting is ignored.
+See the Qt documentation for more details: https://doc.qt.io/qt-6/qtwebengine-features.html#page-lifecycle-api
+
+This setting is only available with the QtWebEngine backend.
+
+Type: <<types,Bool>>
+
+Default: +pass:[true]+
+
+[[qt.chromium.lifecycle_state.freeze_delay]]
+=== qt.chromium.lifecycle_state.freeze_delay
+The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state. This is a low-CPU state, where most DOM event processing, JavaScript execution, and other tasks are suspended.
 
 This setting is only available with the QtWebEngine backend.
 
 Type: <<types,Int>>
 
-Default: +pass:[0]+
+Default: +pass:[30000]+
 
 [[qt.chromium.low_end_device_mode]]
 === qt.chromium.low_end_device_mode
@@ -3935,19 +3951,6 @@ Valid values:
 
 Default: +pass:[enable-all]+
 
-[[qt.chromium.use_recommended_page_lifecycle_state]]
-=== qt.chromium.use_recommended_page_lifecycle_state
-Use recommended page lifecycle state.
-This puts webpages into one of three lifecycle states: active, frozen, or discarded. Using the recommended lifecycle state lets the browser use less resources by freezing or discarding web views when it's safe to do so.
-This results in significant battery life savings.
-Ongoing page activity is taken into account when determining the recommended lifecycle state, as to not disrupt your browsing.
-
-This setting is only available with the QtWebEngine backend.
-
-Type: <<types,Bool>>
-
-Default: +pass:[false]+
-
 [[qt.environ]]
 === qt.environ
 Additional environment variables to set.

qutebrowser/browser/webengine/webenginetab.py

@@ -1754,11 +1754,11 @@ class WebEngineTab(browsertab.AbstractTab):
         timers = {
             QWebEnginePage.LifecycleState.Frozen: (
                 self._lifecycle_timer_freeze,
-                config.val.qt.chromium.lifecycle_state_freeze_delay,
+                config.val.qt.chromium.lifecycle_state.freeze_delay,
             ),
             QWebEnginePage.LifecycleState.Discarded: (
                 self._lifecycle_timer_discard,
-                config.val.qt.chromium.lifecycle_state_discard_delay,
+                config.val.qt.chromium.lifecycle_state.discard_delay,
             ),
         }
 
@@ -1786,7 +1786,7 @@ class WebEngineTab(browsertab.AbstractTab):
             self._schedule_lifecycle_transition(None)
             return
 
-        disabled = not config.val.qt.chromium.use_recommended_page_lifecycle_state
+        disabled = not config.val.qt.chromium.lifecycle_state.enabled
 
         if recommended_state == QWebEnginePage.LifecycleState.Active:
             self._schedule_lifecycle_transition(None)

qutebrowser/config/configdata.yml

@@ -345,9 +345,9 @@ qt.chromium.experimental_web_platform_features:
     Chromium. By default, this is enabled with Qt 5 to maximize compatibility
     despite an aging Chromium base.
 
-qt.chromium.use_recommended_page_lifecycle_state:
+qt.chromium.lifecycle_state.enabled:
   type: Bool
-  default: false
+  default: true
   backend: QtWebEngine
   # yamllint disable rule:line-length
   desc: >-
@@ -368,27 +368,33 @@ qt.chromium.use_recommended_page_lifecycle_state:
     See the Qt documentation for more details: https://doc.qt.io/qt-6/qtwebengine-features.html#page-lifecycle-api
   # yamllint enable rule:line-length
 
-qt.chromium.lifecycle_state_freeze_delay:
+qt.chromium.lifecycle_state.freeze_delay:
   type:
     name: Int
     minval: 0
     maxval: maxint
-  default: 0
+  default: 30_000
   backend: QtWebEngine
   desc: >-
     The amount of time (in milliseconds) to wait before transitioning a page to
     the frozen lifecycle state.
+    This is a low-CPU state, where most DOM event processing, JavaScript
+    execution, and other tasks are suspended.
 
-qt.chromium.lifecycle_state_discard_delay:
+qt.chromium.lifecycle_state.discard_delay:
   type:
     name: Int
     minval: -1
     maxval: maxint
-  default: 0
+  default: 600_000
   backend: QtWebEngine
   desc: >-
     The amount of time (in milliseconds) to wait before transitioning a page to
     the discarded lifecycle state.
+    This state is an extreme resource-saving state, where the browsing context
+    of the web view is discarded and the renderer process is shut down.
+    Resource usage is therefore reduced to near-zero. The web page is
+    automatically reloaded when needed.
 
     Set to -1 to disable this state.
 

tests/end2end/features/tabs.feature

@@ -1992,7 +1992,9 @@ Feature: Tab management
 
     @qt>=6.5
     Scenario: Lifecycle change on tab switch
-        When I set qt.chromium.use_recommended_page_lifecycle_state to true
+        When I set qt.chromium.lifecycle_state.enabled to true
+        And I set qt.chromium.lifecycle_state.freeze_delay to 0
+        And I set qt.chromium.lifecycle_state.discard_delay to 0
         And I open about:blank?1
         And I open about:blank?2 in a new tab
         And I run :tab-prev

tests/unit/browser/webengine/test_webenginetab.py

@@ -288,9 +288,9 @@ class TestPageLifecycle:
         discard_delay=0,
         enabled=True,
     ):
-        config_stub.val.qt.chromium.lifecycle_state_freeze_delay = freeze_delay
-        config_stub.val.qt.chromium.lifecycle_state_discard_delay = discard_delay
-        config_stub.val.qt.chromium.use_recommended_page_lifecycle_state = enabled
+        config_stub.val.qt.chromium.lifecycle_state.freeze_delay = freeze_delay
+        config_stub.val.qt.chromium.lifecycle_state.discard_delay = discard_delay
+        config_stub.val.qt.chromium.lifecycle_state.enabled = enabled
 
     def timer_for(self, tab, state):  # pylint: disable=inconsistent-return-statements
         if state == QWebEnginePage.LifecycleState.Frozen: