Implement basic application preload functionality. (#8928)

Implement background preloading support for instantaneous application
launching.

This feature allows Cobalt to initialize in a hidden state, deferring
heavy resource
creation until the application is revealed to the foreground. To further
minimize
footprint, the splash screen creation is skipped entirely during
preloading.

- Support starting Cobalt in a background/hidden state via the
kSbEventTypePreload signal.
- Defer creation of native windows and UI widgets until the application
is revealed,
  minimizing initial memory and CPU footprint.
- Skip creation of splash screen WebContents when preloaded to further
reduce
  background resource usage.
- Handle kSbEventTypeReveal events to transition the application from a
background
  to a visible state and initialize deferred UI components.
- Ensure standard Web APIs (document.visibilityState, document.hidden)
correctly
reflect the application's hidden state during preloading and its
revealed state.
- Standardize on visibility state propagation throughout the browser
initialization
chain (MainDelegate, BrowserClient, MainParts), keeping "preload" logic
encapsulated
  at the Starboard entry point.
- Consolidate window creation logic into a private internal helper to
ensure
  consistent initialization for both normal and preloaded startups.
- Refactor shell unit tests into a reusable ShellTestBase and extract
common mock
  infrastructure into shell_test_support.h.
- Add comprehensive unit tests:
- LifecycleTest: Verifies startup states, revelation, and signal
idempotency.
- SplashScreenTest: Verifies that splash screen is skipped during
preloading.
- Add a comprehensive automated integration test (test_preload.sh) to
verify
  preloading, revelation, and clean shutdown.
- Add detailed documentation for developers, device manufacturers, and
web
  designers in cobalt/doc/preload.md.
- Enhanced developer tools with usage examples and captured test output.

Bug: 447660888

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
(cherry picked from commit 97ca4ee)

Author: 2 people

cobalt/BUILD.gn

@@ -274,7 +274,11 @@ test("cobalt_unittests") {
   }
 
   if (!is_android) {
-    sources += [ "//cobalt/shell/browser/splash_screen_unittest.cc" ]
+    sources += [
+      "//cobalt/shell/browser/lifecycle_unittest.cc",
+      "//cobalt/shell/browser/shell_test_support.h",
+      "//cobalt/shell/browser/splash_screen_unittest.cc",
+    ]
   }
 
   public_deps = [ "//third_party/zlib/google:compression_utils" ]

cobalt/app/cobalt.cc

@@ -108,26 +108,16 @@ int InitCobalt(int argc, const char** argv, const char* initial_deep_link) {
 
 void SbEventHandle(const SbEvent* event) {
   switch (event->type) {
-    case kSbEventTypePreload: {
-#if BUILDFLAG(IS_COBALT_HERMETIC_BUILD)
-      init_musl();
-#endif
-      SbEventStartData* data = static_cast<SbEventStartData*>(event->data);
-      g_exit_manager = new base::AtExitManager();
-      g_content_main_delegate = new cobalt::CobaltMainDelegate();
-      g_platform_event_source = new PlatformEventSourceStarboard();
-      InitCobalt(data->argument_count,
-                 const_cast<const char**>(data->argument_values), data->link);
-
-      break;
-    }
+    case kSbEventTypePreload:
     case kSbEventTypeStart: {
 #if BUILDFLAG(IS_COBALT_HERMETIC_BUILD)
       init_musl();
 #endif
       SbEventStartData* data = static_cast<SbEventStartData*>(event->data);
       g_exit_manager = new base::AtExitManager();
-      g_content_main_delegate = new cobalt::CobaltMainDelegate();
+      g_content_main_delegate =
+          new cobalt::CobaltMainDelegate(false /* is_content_browsertests */,
+                                         event->type == kSbEventTypeStart);
       g_platform_event_source = new PlatformEventSourceStarboard();
       InitCobalt(data->argument_count,
                  const_cast<const char**>(data->argument_values), data->link);
@@ -174,7 +164,9 @@ void SbEventHandle(const SbEvent* event) {
       break;
     }
     case kSbEventTypeConceal:
+      break;
     case kSbEventTypeReveal:
+<<<<<<< HEAD
       break;
     case kSbEventTypeFreeze: {
       auto* client = cobalt::CobaltContentBrowserClient::Get();
@@ -183,6 +175,11 @@ void SbEventHandle(const SbEvent* event) {
       }
       break;
     }
+=======
+      content::Shell::OnReveal();
+      break;
+    case kSbEventTypeFreeze:
+>>>>>>> 97ca4ee459 (Implement basic application preload functionality. (#8928))
     case kSbEventTypeUnfreeze:
       break;
     case kSbEventTypeInput:

cobalt/app/cobalt_main_delegate.cc

@@ -30,6 +30,7 @@
 
 namespace cobalt {
 
+<<<<<<< HEAD
 CobaltMainDelegate::CobaltMainDelegate() : content::ShellMainDelegate() {
   CHECK_CALLED_ON_VALID_THREAD(thread_checker_);
 }
@@ -40,6 +41,15 @@ CobaltMainDelegate::~CobaltMainDelegate() {
 
 std::optional<int> CobaltMainDelegate::BasicStartupComplete() {
   CHECK_CALLED_ON_VALID_THREAD(thread_checker_);
+=======
+CobaltMainDelegate::CobaltMainDelegate(bool is_content_browsertests,
+                                       bool is_visible)
+    : content::ShellMainDelegate(is_content_browsertests),
+      is_visible_(is_visible) {}
+
+CobaltMainDelegate::~CobaltMainDelegate() {}
+absl::optional<int> CobaltMainDelegate::BasicStartupComplete() {
+>>>>>>> 97ca4ee459 (Implement basic application preload functionality. (#8928))
   base::CommandLine* cl = base::CommandLine::ForCurrentProcess();
   cl->AppendSwitch(switches::kEnableAggressiveDOMStorageFlushing);
   cl->AppendSwitch(switches::kDisableGpuShaderDiskCache);
@@ -48,8 +58,12 @@ std::optional<int> CobaltMainDelegate::BasicStartupComplete() {
 
 content::ContentBrowserClient*
 CobaltMainDelegate::CreateContentBrowserClient() {
+<<<<<<< HEAD
   CHECK_CALLED_ON_VALID_THREAD(thread_checker_);
   browser_client_ = std::make_unique<CobaltContentBrowserClient>();
+=======
+  browser_client_ = std::make_unique<CobaltContentBrowserClient>(is_visible_);
+>>>>>>> 97ca4ee459 (Implement basic application preload functionality. (#8928))
   return browser_client_.get();
 }
 

cobalt/app/cobalt_main_delegate.h

@@ -30,7 +30,12 @@ namespace cobalt {
 
 class CobaltMainDelegate : public content::ShellMainDelegate {
  public:
+<<<<<<< HEAD
   explicit CobaltMainDelegate();
+=======
+  explicit CobaltMainDelegate(bool is_content_browsertests = false,
+                              bool is_visible = true);
+>>>>>>> 97ca4ee459 (Implement basic application preload functionality. (#8928))
 
   CobaltMainDelegate(const CobaltMainDelegate&) = delete;
   CobaltMainDelegate& operator=(const CobaltMainDelegate&) = delete;
@@ -56,6 +61,7 @@ class CobaltMainDelegate : public content::ShellMainDelegate {
   ~CobaltMainDelegate() override;
 
  private:
+  bool is_visible_;
   std::unique_ptr<content::BrowserMainRunner> main_runner_;
   std::unique_ptr<CobaltContentBrowserClient> browser_client_;
   std::unique_ptr<CobaltContentGpuClient> gpu_client_;

cobalt/browser/cobalt_browser_main_parts.cc

@@ -38,6 +38,9 @@
 
 namespace cobalt {
 
+CobaltBrowserMainParts::CobaltBrowserMainParts(bool is_visible)
+    : ShellBrowserMainParts(is_visible) {}
+
 int CobaltBrowserMainParts::PreCreateThreads() {
   SetupMetrics();
 #if BUILDFLAG(IS_ANDROIDTV)

cobalt/browser/cobalt_browser_main_parts.h

@@ -39,7 +39,7 @@ class GlobalFeatures;
 // ShellContentBrowserClient, this should implement BrowserMainParts.
 class CobaltBrowserMainParts : public content::ShellBrowserMainParts {
  public:
-  CobaltBrowserMainParts() = default;
+  explicit CobaltBrowserMainParts(bool is_visible = true);
 
   CobaltBrowserMainParts(const CobaltBrowserMainParts&) = delete;
   CobaltBrowserMainParts& operator=(const CobaltBrowserMainParts&) = delete;

cobalt/browser/cobalt_content_browser_client.cc

@@ -170,8 +170,9 @@ blink::UserAgentMetadata GetCobaltUserAgentMetadata() {
   return metadata;
 }
 
-CobaltContentBrowserClient::CobaltContentBrowserClient()
-    : video_geometry_setter_service_(
+CobaltContentBrowserClient::CobaltContentBrowserClient(bool is_visible)
+    : is_visible_(is_visible),
+      video_geometry_setter_service_(
           std::unique_ptr<cobalt::media::VideoGeometrySetterService,
                           base::OnTaskRunnerDeleter>(
               nullptr,
@@ -200,8 +201,14 @@ CobaltContentBrowserClient* CobaltContentBrowserClient::Get() {
 std::unique_ptr<content::BrowserMainParts>
 CobaltContentBrowserClient::CreateBrowserMainParts(
     bool /* is_integration_test */) {
+<<<<<<< HEAD
   CHECK_CALLED_ON_VALID_THREAD(thread_checker_);
   auto browser_main_parts = std::make_unique<CobaltBrowserMainParts>();
+=======
+  DCHECK_CALLED_ON_VALID_THREAD(thread_checker_);
+  auto browser_main_parts =
+      std::make_unique<CobaltBrowserMainParts>(is_visible_);
+>>>>>>> 97ca4ee459 (Implement basic application preload functionality. (#8928))
   set_browser_main_parts(browser_main_parts.get());
   return browser_main_parts;
 }

cobalt/browser/cobalt_content_browser_client.h

@@ -62,7 +62,7 @@ class CobaltWebContentsObserver;
 // a demo around Content.
 class CobaltContentBrowserClient : public content::ShellContentBrowserClient {
  public:
-  CobaltContentBrowserClient();
+  explicit CobaltContentBrowserClient(bool is_visible = true);
 
   CobaltContentBrowserClient(const CobaltContentBrowserClient&) = delete;
   CobaltContentBrowserClient& operator=(const CobaltContentBrowserClient&) =
@@ -152,6 +152,7 @@ class CobaltContentBrowserClient : public content::ShellContentBrowserClient {
   void DispatchEvent(const std::string&, base::OnceClosure);
   void OnSbWindowCreated(SbWindow window);
 
+  bool is_visible_;
   std::unique_ptr<CobaltWebContentsObserver> web_contents_observer_;
   std::unique_ptr<media::VideoGeometrySetterService, base::OnTaskRunnerDeleter>
       video_geometry_setter_service_;

cobalt/doc/preload.md

@@ -0,0 +1,104 @@
+# Application Preload
+
+Preloading allows Cobalt to start and initialize in the background without
+displaying any user interface. This enables a "background-to-foreground"
+transition that appears instantaneous to the user when they eventually choose to
+launch the application.
+
+## For Web Designers
+
+When an application is preloaded, it starts in a **hidden** state. Standard Web
+APIs correctly reflect this state:
+
+-   `document.visibilityState` will be `"hidden"`.
+-   `document.hidden` will be `true`.
+
+### Best Practices
+
+-   Avoid starting audio playback or heavy graphical animations while in the
+    hidden state.
+-   Listen for the `visibilitychange` event on the `document` object to detect
+    when the application transitions from preloaded to visible.
+
+## For Device Manufacturers (Starboard Porters)
+
+Preloading is managed through the Starboard lifecycle.
+
+-   **Startup:** To start in preload mode, the Starboard implementation should
+    send the `kSbEventTypePreload` event instead of `kSbEventTypeStart`.
+    -   In the shared Starboard application framework (`starboard/shared/starboard/application.cc`),
+        the `--preload` command-line flag is recognized via the `kPreloadSwitch` constant.
+    -   If a platform implementation's `Application::IsPreloadImmediate()` returns true
+        (typically by checking `HasPreloadSwitch()`), the application will
+        automatically call `DispatchPreload()`.
+    -   `DispatchPreload()` then creates and dispatches the `kSbEventTypePreload`
+        initial event, which is the signal to the application that it should
+        initialize in a hidden state.
+-   **Revelation:** To bring a preloaded application to the foreground, the
+    platform should send a `kSbEventTypeReveal` signal.
+    -   On Linux-based platforms, this is often triggered by sending a `SIGCONT`
+        signal to the process.
+    -   An example of this mapping can be found in `starboard/shared/signal/suspend_signals.cc`,
+        where `SIGCONT` is handled by requesting a focus change.
+    -   The shared Starboard application logic in `starboard/shared/starboard/application.cc`
+        automatically injects a `kSbEventTypeReveal` event if a focus request is
+        received while the application is in the preloaded (concealed) state.
+-   **Resource Management:** Cobalt defers the creation of the native window and
+    associated graphics resources until the first `Reveal` signal is received.
+    This minimizes the memory and CPU footprint of the application while it
+    resides in the background.
+-   **Splash Screen:** The creation of the splash screen's `WebContents` is also
+    skipped when the application is preloaded, further reducing the background
+    footprint.
+
+## For Cobalt Developers
+
+The "preload" signal is converted into a generic "visibility" state as soon as
+it enters the application layer.
+
+### Implementation Flow
+
+1.  **Entry Point:** `SbEventHandle` (in `cobalt/app/cobalt.cc`) receives
+    `kSbEventTypePreload`.
+2.  **State Propagation:** An `is_visible` boolean (set to `false`) is passed
+    through the constructor chain: `CobaltMainDelegate` ->
+    `CobaltContentBrowserClient` -> `CobaltBrowserMainParts` ->
+    `ShellBrowserMainParts`.
+3.  **Initialization:** `ShellBrowserMainParts::PreMainMessageLoopRun` calls
+    `Shell::Initialize`, passing the visibility state.
+4.  **Splash Screen Skip:** `Shell::CreateNewWindow` checks the visibility state
+    and skips creating the splash screen `WebContents` if the application is
+    initially hidden.
+5.  **Platform Delegate:** `Shell::Initialize` passes the state to
+    `ShellPlatformDelegate::Initialize`. Each platform implementation (e.g.,
+    Aura, Views) stores this in a member variable.
+6.  **Deferred Resource Creation:** `CreatePlatformWindow` checks `IsVisible()`
+    (or `IsConcealed()`) and defers creating the `NativeWindow` and `Widget` if
+    the application is not yet visible.
+7.  **Revelation:** When `kSbEventTypeReveal` is received, `Shell::OnReveal()` is
+    triggered. This calls `ShellPlatformDelegate::RevealShell`, which creates
+    the deferred window resources and calls `WasShown()` on the `WebContents`,
+    triggering the `visibilitychange` event for the web application.
+
+### Unit Testing
+
+Application lifecycle and visibility transitions are covered by the following
+unit tests in the `cobalt_unittests` binary:
+
+-   **`LifecycleTest`** (`cobalt/shell/browser/lifecycle_unittest.cc`): Verifies
+    correct window creation and visibility state propagation during startup,
+    revelation, and redundant signals.
+-   **`SplashScreenTest`** (`cobalt/shell/browser/splash_screen_unittest.cc`):
+    Includes tests for ensuring the splash screen is skipped during preloading.
+
+### Integration Testing
+
+A robust integration test is provided in `cobalt/tools/test_preload.sh`. This
+test:
+
+1.  Launches Cobalt in preload mode.
+2.  Uses the Chrome DevTools Protocol (CDP) to verify that
+    `document.visibilityState` is initially `"hidden"`.
+3.  Sends a `SIGCONT` signal to reveal the application.
+4.  Verifies via CDP that `document.visibilityState` transitions to `"visible"`.
+5.  Sends a `SIGPWR` signal to verify clean shutdown.