Synchronous JS initionalization of the dark theme.

app/lib/frontend/templates/views/shared/layout.dart

@@ -167,6 +167,10 @@ d.Node pageLayoutNode({
             if (activeConfiguration.isStaging) 'staging-banner',
           ],
           children: [
+            // The initialization of dark theme must be in a synchronous, blocking
+            // script execution, as otherwise users may see flash of unstyled content
+            // (usually white background instead of a dark theme).
+            d.script(src: staticUrls.getAssetUrl('/static/js/dark-init.js')),
             if (activeConfiguration.isStaging)
               d.div(classes: ['staging-ribbon'], text: 'staging'),
             // <!-- Google Tag Manager (noscript) -->

pkg/web_app/lib/script.dart

@@ -26,31 +26,6 @@ void main() {
   window.onPageShow.listen((_) {
     adjustQueryTextAfterPageShow();
   });
-  _setupDarkTheme();
-}
-
-void _setupDarkTheme() {
-  // Only trigger dark mode when the experiment is enabled on the server.
-  final classes = document.body?.classes;
-  if (classes != null && classes.contains('-experimental-dark-mode')) {
-    // Detects OS or browser-level theme preference by using media queries.
-    bool mediaPrefersDarkScheme = false;
-    try {
-      mediaPrefersDarkScheme =
-          window.matchMedia('(prefers-color-scheme: dark)').matches;
-    } catch (_) {
-      // ignore errors e.g. when media query matching is not supported
-    }
-
-    // Detects whether the dartdoc control was set to use dark theme
-    final dartdocDarkThemeIsSet = window.localStorage['colorTheme'] == 'true';
-
-    // Switch the top-level style marker to use dark theme instead of the light theme default.
-    if (mediaPrefersDarkScheme || dartdocDarkThemeIsSet) {
-      classes.remove('light-theme');
-      classes.add('dark-theme');
-    }
-  }
 }
 
 void _setupAllEvents() {

static/js/dark-init.js

@@ -0,0 +1,29 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// This script is run blocking at the beginning of the page load to ensure that
+// we don't have flashing white background before switching to dark mode.
+(function () {
+  if (!document.body.classList.contains('-experimental-dark-mode')) {
+    return;
+  }
+
+  // Detects OS or browser-level theme preference by using media queries.
+  let mediaPrefersDarkScheme = false;
+  try {
+    mediaPrefersDarkScheme =
+      window.matchMedia('(prefers-color-scheme: dark)').matches;
+  } catch (e) {
+    // ignore errors e.g. when media query matching is not supported
+  }
+
+  // Detects whether the dartdoc control was set to use dark theme
+  let dartdocDarkThemeIsSet = window.localStorage.getItem('colorTheme') == 'true';
+
+  // Switch the top-level style marker to use dark theme instead of the light theme default.
+  if (mediaPrefersDarkScheme || dartdocDarkThemeIsSet) {
+    document.body.classList.remove('light-theme');
+    document.body.classList.add('dark-theme');
+  }
+})();