fix(api): eliminate theme flash on docs.warp.dev/api (#6)

hongyi-chen · oz-agent · web-flow · commit c266423cd1ff · 2026-04-30T15:18:16.000-07:00
* fix(api): paint /api canvas synchronously to eliminate theme flash

The /api page flashed white on first load before settling into dark mode.
The head script already set &lt;html data-theme&gt; synchronously, but no CSS
in &lt;head&gt; keyed off that attribute — the only theme-aware CSS lived
inside Scalar's runtime-injected customCss (which keys off body classes
.dark-mode / .light-mode), and that CSS only existed after the Scalar
bundle (loaded mid-&lt;body&gt;) downloaded, parsed, and mounted.

Add an inline &lt;style&gt; in &lt;head&gt; that paints html (and inheriting body)
based on data-theme, so the canvas color is correct on the very first
frame. Scalar's customCss still drives the rest of the page once it
mounts.

Co-Authored-By: Oz &lt;oz-agent@warp.dev&gt;

* fix(api): boot Scalar in resolved theme to remove dark→light→dark flash

The previous fix removed the white-on-first-frame flash but exposed a
deeper timing bug: Scalar booted in light mode on cold loads, briefly
flipped the page to light, then DOMContentLoaded restored dark.

Root cause: the Scalar config sync script reads
`document.body.classList.contains('dark-mode')` synchronously inside
&lt;body&gt;, before the head script's body-class apply runs (which is queued
for DOMContentLoaded because document.body is null in &lt;head&gt;). So
cfg.darkMode was always false on cold load → Scalar mounted light → the
mirror MutationObserver flipped html[data-theme]='light' → the new
canvas CSS painted white → DOMContentLoaded fired and corrected
everything.

Fix:
1. Expose `window.__warpResolveTheme()` — a read-only sibling of the
   existing __warpApplyTheme that just resolves localStorage +
   prefers-color-scheme to 'dark' or 'light'.
2. Add a top-of-body inline script that calls __warpResolveTheme() and
   applies the body class synchronously, before any other body-level
   script runs.
3. Switch the Scalar config sync to read __warpResolveTheme() instead
   of body.classList, decoupling Scalar's boot value from DOM apply
   ordering.

Co-Authored-By: Oz &lt;oz-agent@warp.dev&gt;

---------

Co-authored-by: Oz &lt;oz-agent@warp.dev&gt;
diff --git a/src/pages/api.astro b/src/pages/api.astro
@@ -98,6 +98,14 @@ const specJson = JSON.stringify(specObject);
           } catch (_e) {}
           apply(resolve(value === 'auto' ? '' : value));
         };
+        // Read-only sibling of __warpApplyTheme: returns the resolved
+        // 'dark' | 'light' value without touching the DOM or localStorage.
+        // Used by the body-top inline script to apply the body class as
+        // soon as <body> is parsed, and by Scalar's config sync script
+        // to compute `cfg.darkMode` independently of body-class state.
+        window.__warpResolveTheme = function () {
+          return resolve(read());
+        };
         // Re-resolve when the system preference changes, but only if
         // we're following it (stored value is empty / unknown).
         prefersDark.addEventListener('change', function () {
@@ -128,8 +136,48 @@ const specJson = JSON.stringify(specObject);
         else document.addEventListener('DOMContentLoaded', startMirror);
       })();
     </script>
+    <style>
+      /* First-paint canvas color, keyed off the `data-theme` attribute set
+         synchronously by the script above. Without this, `/api` flashes
+         white before mounting because Scalar's themed `customCss` (which
+         keys off `body.dark-mode` / `body.light-mode`) only ships inside
+         the Scalar bundle loaded mid-`<body>`, so nothing paints the
+         page background until that bundle parses + mounts.
+
+         Values mirror `--scalar-background-1` from the customCss block
+         below. If you change the canvas there (or in custom.css), update
+         these in lockstep so the first-paint color matches what Scalar
+         applies a few frames later. */
+      html[data-theme="dark"] {
+        background-color: #121212;
+        color-scheme: dark;
+      }
+      html[data-theme="light"] {
+        background-color: #ffffff;
+        color-scheme: light;
+      }
+      body {
+        background-color: inherit;
+      }
+    </style>
   </head>
   <body>
+    <script is:inline>
+      // Apply `body.dark-mode` / `body.light-mode` synchronously, before
+      // any other body-level script runs (specifically, before the Scalar
+      // config sync script and Scalar's bundle below). The <head> script
+      // can't do this itself because `document.body` is null while <head>
+      // parses; without this top-of-body apply, body would have no class
+      // until DOMContentLoaded, Scalar would boot in light mode, the
+      // mirror MutationObserver would briefly flip `html[data-theme]` to
+      // `light`, and the page would visibly flash dark → light → dark.
+      (function () {
+        var resolved = (typeof window.__warpResolveTheme === 'function')
+          ? window.__warpResolveTheme()
+          : 'dark';
+        document.body.classList.add(resolved === 'dark' ? 'dark-mode' : 'light-mode');
+      })();
+    </script>
     <WarpTopbar crumb="API Reference" />
     <script
       is:inline
@@ -254,17 +302,29 @@ const specJson = JSON.stringify(specObject);
     <script is:inline>
       // Sync Scalar's `darkMode` config to the resolved theme before the
       // Scalar bundle reads `data-configuration`. This keeps Scalar's
-      // internal `useColorMode` state aligned with the body class our
-      // <head> script already set, eliminating the one-frame mismatch
-      // where Scalar would briefly mount in its own default.
+      // internal `useColorMode` state aligned with the resolved theme,
+      // eliminating the one-frame mismatch where Scalar would briefly
+      // mount in its own default.
+      //
+      // We read directly from `__warpResolveTheme()` (which resolves
+      // `localStorage['starlight-theme']` + `prefers-color-scheme`)
+      // rather than from `document.body.classList`, because the body
+      // class is intentionally not a reliable boot-time source: the
+      // <head> script can't apply it before <body> exists, and the
+      // top-of-body apply runs in the same parser frame as us. Reading
+      // localStorage decouples Scalar's boot value from any DOM apply
+      // ordering, so dark-mode users never see a transient light boot.
       (function () {
         var el = document.getElementById('api-reference');
         if (!el) return;
         var raw = el.getAttribute('data-configuration');
         if (!raw) return;
         try {
           var cfg = JSON.parse(raw);
-          cfg.darkMode = document.body.classList.contains('dark-mode');
+          var resolved = (typeof window.__warpResolveTheme === 'function')
+            ? window.__warpResolveTheme()
+            : (document.body.classList.contains('dark-mode') ? 'dark' : 'light');
+          cfg.darkMode = resolved === 'dark';
           el.setAttribute('data-configuration', JSON.stringify(cfg));
         } catch (_e) {
           // Malformed config — let Scalar fall back to its own default.
