Page Life Cycle Support

[modeveci]

This ticket is for following activities regarding Page Life-Cycle support.

https://jira.rdkcentral.com/jira/browse/WPEBROWSER-54

business need/user story behind :

As an operator I need to be start and switch between WebApps quickly.
To remain competitive Operation System, RDK needs to support industry accepted Lifecycle model that allows multiple WebApps to run concurrently (and resume quickly from background) while at same time not use all scarce resources when running in background and safeguard stable operation.
As WebApp developer I would like to use industry standard solution for Lifecycle api instead of having to develop custom solution.
Technical solution agreed between Architects of Comcast-Sky-LibertyGlobal is :
As lifecycle API between Browser and the WebApp, W3C page Lifecycle need to be supported on WebEngine.
see specs & documentation:
https://developer.chrome.com/docs/web-platform/page-lifecycle-api
W3C Lifecycle model & events in diagram
https://developer.chrome.com/docs/web-platform/page-lifecycle-api/image/page-lifecycle-api-state.svg
Need to support
ACTIVE, PASSIVE, HIDDEN but very important also FROZEN state (support focus, blur, visibilitychange, freeze and resume events)
specs :
https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API
https://html.spec.whatwg.org/multipage/interaction.html#page-visibility
https://wicg.github.io/page-lifecycle/spec.html
Support for same page-lifecycle spec is also required by HBBTV consortium and by BBC iPlayer application.
Between the WebEngine and the platform (Middleware) the Webengine needs to support Firebolt Lifecycle 2.0 model as defined in
https://wiki.rdkcentral.com/pages/viewpage.action?spaceKey=ASP&title=Simplified+Lifecycle+2.0
Concretely this is means WebEngine needs to support Firebolt Lifecycle states initializing, Paused, Active, Suspended and Hibernated and associated transition events (onStart, onActivate, onPause, onSuspend, onResume, onHibernate, onRestore and onDestroy. OnStartSuspend is not required. WebEngine needs to support mapping of the Firebolt Lifecycle 2.0 states and events to appropriate W3C PageLifecycle states/events towards the application and release appropriate resources in associated state.
WebEngine needs to support Firebolt Lifecycle states initializing, Paused, Active, Suspended and Hibernated and associated transition events (onStart, onActivate, onPause, onSuspend, onResume, onHibernate, onRestore and onDestroy. OnStartSuspend is not required.
Process part of Webengine (eg launcher) needs to communicate (IPC) with FireboltServer (ripple) for these Firebolt Lifecycle states.
A none-thunder Webengine launcher that works with AppInfra2.0 will need to be developed as well.
Needs to be supported on existing WPE2.38 browser and on the newer upcoming versions
Above can happen in phases but must clear definition of all phases must be defined then as part of assessment of this ticket.
example Webapp Listening to W3C Pagelifecycle events
https://page-lifecycle.glitch.me/
Tool to force lifecycle (especially freeze) in chrome
chrome://discards/
There no W3C solution for communicating deeplinks from platform to WebApp but that is important business requirement (used today)
So until there is one defined at W3C we provide solution where WebApp can fetch NavigationIntent at appropriate events (load/pageshow, resume)
by calling firebolt api. discovery.getNavigationIntent This is signleton per application and platform will set the appropriate NavigationIntent before associated Lifecycle event change. that method will be added to Firebolt Discovery api and works in concert with 'Discovery.onNavigateTo' https://rdkcentral.github.io/firebolt/apis/latest/core/Discovery/#navigateto event that is already defined in firebolt api version of today

[modeveci]

Development branch: https://github.com/WebPlatformForEmbedded/WPEWebKit/tree/wpe-2.38_page_lifecycle_api_new
The reference COG launcher has been updated: https://github.com/pgorszkowski-igalia/cog/tree/0.16.0_page_lifecycle_new
This is the test page: https://people.igalia.com/pgorszkowski/page_lifecycle.html

[modeveci]

@pgorszkowski-igalia , Some feedback for draft implementation:

with webkit built from https://github.com/WebPlatformForEmbedded/WPEWebKit/tree/wpe-2.38_page_lifecycle_api_new , last change: 3035cf746fbbc8ce60d19158806a8d1006bed95e resume event is not generated when calling webkit_web_view_resume_frozen .

there is a proposed solution, but first I want you to check whole impl. and implications on other components.
Thanks

[pgorszkowski-igalia]

@modeveci : There was a missing change for dispatching the 'resume' event after restoring page from the frozen state. I added commit with that change to https://github.com/WebPlatformForEmbedded/WPEWebKit/tree/wpe-2.38_page_lifecycle_api_new branch

[pgorszkowski-igalia]

One note about minimizing the memory usage in case of suspend/frozen state: there is a change in 2.38 which minimize the GPU memory usage in case of suspending of the page (which happens in frozen state) but it is currently implemented only with Wayland and if nonCompositedWebGL feature is off. This is the link to that change: #1491. To turn it on ENABLE_RESIZE_WAYLAND_SURFACES_ON_SUSPEND_PAINTING cmake option has to be true (by default it is false).

I am working on to make similar behaviour not only in case of Wayland and with enabled nonCompositedWebGL feature.

[wouterlucas]

One note about minimizing the memory usage in case of suspend/frozen state: there is a change in 2.38 which minimize the GPU memory usage in case of suspending of the page (which happens in frozen state) but it is currently implemented only with Wayland and if nonCompositedWebGL feature is off. This is the link to that change: #1491. To turn it on ENABLE_RESIZE_WAYLAND_SURFACES_ON_SUSPEND_PAINTING cmake option has to be true (by default it is false).

I am working on to make similar behaviour not only in case of Wayland and with enabled nonCompositedWebGL feature.

yes please! 😄 - a fair amount of Lightning apps are running on WPEWebKit with background capabilities. Having this to work with nonCompositedWebGL is key to making it work well for Lightning too!

[modeveci]

@pgorszkowski-igalia We had talked about to release nativeWindow during freeze event/frozen state but being flexible to have option (environment variable) to resize the surface window in case we want to keep the nativeWindow during the frozen state. Could we consider the implementation accordantly?

[pgorszkowski-igalia]

@modeveci : currently I am working on the option with resizing the surface window in case of nonCompositedWebGL. I have not checked the option with releasing the nativeWindow during frozen state yet (it might be too problematic).

[modeveci]

Hi @pgorszkowski-igalia , can you also use this test page? As it has been enhanced on top of your test-page. https://bunsoft.dev/lifecycle.html

[BunioFH]

with the lifecycle.html you can see:

• that resume & freeze events do replace pageshow and pagehide - something to address
• when page activity state is change using webkit_web_view_hide & webkit_web_view_show visibilitychange is generated. however if you do the same with activity state change adding/removing the wpe_view_activity_state_focused it is replaced by focus & blur events
• page activity is properly stopped during the cycle and freeze allows closing of all network activity although in case of WebSocket closure is rethrown and WebSocket::suspend is called before it's applied which produces an error in log:
  2025-09-12T12:10:46.457Z WPEFramework[3120]: [HtmlApp]:0 WebSocket connection to 'wss://echo.websocket.org/' failed: WebSocket is closed due to suspension.
• during freeze main browser texture is not freed and remains visible

[pgorszkowski-igalia]

with the lifecycle.html you can see:

* that `resume` & `freeze` events do replace `pageshow` and `pagehide` - something to address

* when page activity state is change using `webkit_web_view_hide` & `webkit_web_view_show` `visibilitychange` is generated. however if you do the same with activity state change adding/removing the `wpe_view_activity_state_focused` it is replaced by `focus` & `blur` events

* page activity is properly stopped during the cycle and `freeze` allows closing of all network activity although in case of `WebSocket` closure is rethrown and `WebSocket::suspend` is called before it's applied which produces an error in log:
  `2025-09-12T12:10:46.457Z WPEFramework[3120]:  [HtmlApp]:0 WebSocket connection to 'wss://echo.websocket.org/' failed: WebSocket is closed due to suspension.`

* during `freeze` main browser texture is not freed and remains visible

Thanks @BunioFH for the feedback. I am going to check that this week.

[pgorszkowski-igalia]

with the lifecycle.html you can see:

* that `resume` & `freeze` events do replace `pageshow` and `pagehide` - something to address

Yes, I replaced that events with resume and freeze but they can be sent together(pageshow with resume and pagehide with freeze).

* when page activity state is change using `webkit_web_view_hide` & `webkit_web_view_show` `visibilitychange` is generated. however if you do the same with activity state change adding/removing the `wpe_view_activity_state_focused` it is replaced by `focus` & `blur` events

Can you elaborate this more? do the same with activity state change adding/removing the "wpe_view_activity_state_focused" how did you do that?

* page activity is properly stopped during the cycle and `freeze` allows closing of all network activity although in case of `WebSocket` closure is rethrown and `WebSocket::suspend` is called before it's applied which produces an error in log:
  `2025-09-12T12:10:46.457Z WPEFramework[3120]:  [HtmlApp]:0 WebSocket connection to 'wss://echo.websocket.org/' failed: WebSocket is closed due to suspension.`

Working on it.

* during `freeze` main browser texture is not freed and remains visible

Yes, I am working on it. The main idea is to make it transparent when webkit_web_view_hide is called (it works now) and when ``webkit_web_view_freeze` is called the main surface should be released or minimize as much as possible to minimize GPU memory usage.

[pgorszkowski-igalia]

@BunioFH : I think there is a mistake in your test page, please find my proposal for fix:

diff --git a/lifecycle.html b/lifecycle.html
index 7668d1c..bae9848 100644
--- a/lifecycle.html
+++ b/lifecycle.html
@@ -129,11 +129,12 @@
     const api = window.indexedDB;
     let request;
     let timeout;
+    let database;
 
     const _cleanup = () => {
-      if( request ) {
-        request.close();
-        request = null;
+      if( database ) {
+        database.close();
+        database = null;
         timedLog('db closed');
       }
       if( timeout ) {
@@ -187,6 +188,7 @@
         let index = store.createIndex('index', ['name.last', 'name.first']);
       };
       request.onsuccess = () => {
+        database = request.result;
         timedLog('db opened');
         idb.textContent = 'ON';
         _run(request.result);