fix(api): paint /api canvas synchronously to eliminate theme flash

hongyi-chen · oz-agent · hongyi-chen · commit e0588d463482 · 2026-04-30T13:51:07.000-07:00
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;
diff --git a/src/pages/api.astro b/src/pages/api.astro
@@ -128,6 +128,30 @@ 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>
     <WarpTopbar crumb="API Reference" />
