From 983adc53470d9445d4bcb09ba477bfea993b5fa6 Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Sun, 21 Jun 2026 18:49:20 +0000
Subject: [PATCH] fix(docs): stop Scalar's global body bg from bleeding into
 the docs on client-nav

Scalar's /api reference injects a *global* `body { background-color:
var(--scalar-background-1) }` (via its linked stylesheet + a runtime
<style id=scalar-style>) that TanStack doesn't remove on a client-side route
change. After navigating /api -> /docs without a reload, that rule kept
painting the docs body: Scalar's stock gray (#0f0f0f) while .dark-mode lingered
on <body>, or transparent once the class was gone. A hard reload was fine
because the stylesheet was never loaded there.

Fix: give --scalar-background-1 a global fallback = --color-fd-background so any
non-API page paints its own surface while Scalar's sheet lingers; /api itself
overrides it via the higher-specificity body.{dark,light}-mode rule. Also strip
the leftover #scalar-style/#scalar-refs nodes and body mode-class when /api
unmounts so the DOM matches a fresh load. Verified light + dark via headless
CDP: post-nav docs body now equals a fresh reload (#141019 / #f0ebff).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs-site/src/routes/api/index.tsx | 18 ++++++++++++++++++
 docs-site/src/styles/app.css       | 10 ++++++++++
 2 files changed, 28 insertions(+)
diff --git a/docs-site/src/routes/api/index.tsx b/docs-site/src/routes/api/index.tsx
index 633be21..65c5df2 100644
--- a/docs-site/src/routes/api/index.tsx
+++ b/docs-site/src/routes/api/index.tsx
@@ -158,6 +158,24 @@ function ApiReference() {
   useEffect(() => setMounted(true), [])
   const isDark = !mounted || resolvedTheme !== 'light'
 
+  // Scalar pollutes global scope and never cleans up: it appends a persistent
+  // <style id="scalar-style"> to <head> that includes a *global*
+  // `body { background-color: var(--scalar-background-1) }`, adds its #scalar-refs
+  // teleport target, and toggles .dark-mode/.light-mode on <body>. After a
+  // client-side route change (no reload) that residue bleeds into the next page —
+  // the docs body kept painting Scalar's bg instead of --color-fd-background, so
+  // the docs looked gray until a hard reload. Strip it when /api unmounts so
+  // leaving the page restores the same DOM a fresh load has; Scalar re-injects a
+  // fresh instance on re-entry.
+  useEffect(
+    () => () => {
+      document.getElementById('scalar-style')?.remove()
+      document.getElementById('scalar-refs')?.remove()
+      document.body.classList.remove('dark-mode', 'light-mode')
+    },
+    [],
+  )
+
   // A fresh object on each theme flip so the React wrapper's
   // `updateConfiguration` effect fires and Scalar swaps the body mode class.
   const configuration = useMemo(
diff --git a/docs-site/src/styles/app.css b/docs-site/src/styles/app.css
index e0810d7..b19781a 100644
--- a/docs-site/src/styles/app.css
+++ b/docs-site/src/styles/app.css
@@ -28,6 +28,16 @@
   /* Fumadocs accent → brand violet (light mode). */
   --color-fd-primary: var(--pf-brand);
   --color-fd-ring: var(--pf-brand);
+
+  /* The /api Scalar reference injects a *global* `body { background-color:
+     var(--scalar-background-1) }` (via its own stylesheet + a runtime
+     <style id="scalar-style">) that TanStack does NOT remove on a client-side
+     route change. Give that variable a fallback = the docs surface so every
+     non-API page still paints correctly while Scalar's sheet lingers (without
+     this the docs body went gray, or transparent once the body mode-class was
+     stripped). On /api itself the reference's body.{dark,light}-mode rule
+     (higher specificity) overrides this back to the brand chrome. */
+  --scalar-background-1: var(--color-fd-background);
 }
 
 .dark {
