From 12422f1a3168725b1ebb68c4a053cfb2480a15f6 Mon Sep 17 00:00:00 2001
From: Adam Osman <kawaiiyou3@gmail.com>
Date: Fri, 1 May 2026 20:31:36 -0400
Subject: [PATCH 1/3] fix(docs): prevent dark-mode flash before theme script
 runs

Move theme bootstrap before render-blocking font stylesheet; add critical
body background rules; normalize stored theme; reapply on DOMContentLoaded
and bfcache pageshow.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/layouts/BaseLayout.astro | 62 +++++++++++++++++++++++++++---------
 1 file changed, 47 insertions(+), 15 deletions(-)
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index eed0e4bf..6fc109ab 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -22,31 +22,63 @@ const fullTitle = title === 'Spicetify' ? title : `${title} | Spicetify`;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link rel="icon" href="/images/favicon.ico" />
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Syne:wght@600;700;800&display=swap" />
-    <title>{fullTitle}</title>
-    <SEO title={title} description={description} image={image} type={type} />
+    <!-- Theme must run before any render-blocking stylesheets (e.g. fonts) or the
+         page can paint once with the UA / :root light palette before data-theme is set. -->
     <script is:inline>
       const applyTheme = (theme) => {
-        document.documentElement.dataset.theme = theme;
-        document.documentElement.style.colorScheme = theme;
-        document.documentElement.style.backgroundColor =
-          theme === 'dark' ? '#1b1b1d' : '#ffffff';
+        const t = theme === 'dark' ? 'dark' : 'light';
+        document.documentElement.dataset.theme = t;
+        document.documentElement.style.colorScheme = t;
+        const bg = t === 'dark' ? '#1b1b1d' : '#ffffff';
+        document.documentElement.style.backgroundColor = bg;
+        if (document.body) {
+          document.body.style.backgroundColor = bg;
+        }
       };
       window.__setTheme = applyTheme;
-      const theme = (() => {
-        if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
-          return localStorage.getItem('theme');
+      const resolveTheme = () => {
+        try {
+          const stored = localStorage.getItem('theme');
+          if (stored === 'dark' || stored === 'light') {
+            return stored;
+          }
+        } catch {
+          /* private mode / disabled storage */
         }
         if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
           return 'dark';
         }
         return 'light';
-      })();
-      applyTheme(theme);
+      };
+      applyTheme(resolveTheme());
+      document.addEventListener(
+        'DOMContentLoaded',
+        () => {
+          applyTheme(resolveTheme());
+        },
+        { once: true },
+      );
+      window.addEventListener('pageshow', (event) => {
+        if (event.persisted) {
+          applyTheme(resolveTheme());
+        }
+      });
     </script>
+    <style is:inline>
+      /* Beat UA default body background until global CSS loads */
+      html[data-theme='dark'] body {
+        background-color: #1b1b1d;
+      }
+      html[data-theme='light'] body {
+        background-color: #ffffff;
+      }
+    </style>
+    <link rel="icon" href="/images/favicon.ico" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Syne:wght@600;700;800&display=swap" />
+    <title>{fullTitle}</title>
+    <SEO title={title} description={description} image={image} type={type} />
   </head>
   <body>
     <a href="#main-content" class="skip-to-content">Skip to content</a>

From 78404079233a594c439512605a10d2b1e8286a8d Mon Sep 17 00:00:00 2001
From: Adam Osman <kawaiiyou3@gmail.com>
Date: Fri, 1 May 2026 20:36:14 -0400
Subject: [PATCH 2/3] feat(docs): client-side navigations with Astro
 ClientRouter

Use ClientRouter for in-site link clicks instead of full document reloads.
Reapply theme after view transitions swap root attributes; rebind navbar
handlers on astro:page-load; delegate search modal to document listeners;
reinit tabs and homepage install block on page-load.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/components/Navbar.astro                  |  68 ++++----
 src/components/SearchModal.astro             | 168 +++++++++++--------
 src/components/Tabs.astro                    |   1 +
 src/components/homepage/InstallSection.astro |   9 +
 src/layouts/BaseLayout.astro                 |   5 +
 5 files changed, 155 insertions(+), 96 deletions(-)

diff --git a/src/components/Navbar.astro b/src/components/Navbar.astro
index c1c2bd4e..5550cbc1 100644
--- a/src/components/Navbar.astro
+++ b/src/components/Navbar.astro
@@ -151,37 +151,49 @@ const isBlogActive = currentPath.startsWith('/blog');
 </header>
 
 <script>
-  function setupThemeToggle() {
-    const toggle = document.getElementById('theme-toggle');
-    toggle?.addEventListener('click', () => {
-      const current = document.documentElement.dataset.theme;
-      const next = current === 'dark' ? 'light' : 'dark';
-      if (window.__setTheme) {
-        window.__setTheme(next);
-      } else {
-        document.documentElement.dataset.theme = next;
-      }
-      localStorage.setItem('theme', next);
-    });
-  }
+  let navListenersAbort = new AbortController();
+
+  function setupNavbarInteractions() {
+    navListenersAbort.abort();
+    navListenersAbort = new AbortController();
+    const { signal } = navListenersAbort;
+
+    const themeToggle = document.getElementById('theme-toggle');
+    themeToggle?.addEventListener(
+      'click',
+      () => {
+        const current = document.documentElement.dataset.theme;
+        const next = current === 'dark' ? 'light' : 'dark';
+        if (window.__setTheme) {
+          window.__setTheme(next);
+        } else {
+          document.documentElement.dataset.theme = next;
+        }
+        localStorage.setItem('theme', next);
+      },
+      { signal },
+    );
 
-  function setupMobileMenu() {
-    const toggle = document.querySelector('.mobile-menu-toggle');
-    toggle?.addEventListener('click', () => {
-      const sidebar = document.querySelector('.docs-sidebar');
-      const mobileNav = document.querySelector('.mobile-nav');
-      const expanded = toggle.getAttribute('aria-expanded') === 'true';
-      toggle.setAttribute('aria-expanded', String(!expanded));
-      if (sidebar) {
-        sidebar.classList.toggle('open');
-      } else if (mobileNav) {
-        mobileNav.classList.toggle('open');
-      }
-    });
+    const menuToggle = document.querySelector('.mobile-menu-toggle');
+    menuToggle?.addEventListener(
+      'click',
+      () => {
+        const sidebar = document.querySelector('.docs-sidebar');
+        const mobileNav = document.querySelector('.mobile-nav');
+        const expanded = menuToggle.getAttribute('aria-expanded') === 'true';
+        menuToggle.setAttribute('aria-expanded', String(!expanded));
+        if (sidebar) {
+          sidebar.classList.toggle('open');
+        } else if (mobileNav) {
+          mobileNav.classList.toggle('open');
+        }
+      },
+      { signal },
+    );
   }
 
-  setupThemeToggle();
-  setupMobileMenu();
+  setupNavbarInteractions();
+  document.addEventListener('astro:page-load', setupNavbarInteractions);
 </script>
 
 <style>
diff --git a/src/components/SearchModal.astro b/src/components/SearchModal.astro
index 4ec510f8..1dc441d6 100644
--- a/src/components/SearchModal.astro
+++ b/src/components/SearchModal.astro
@@ -29,51 +29,72 @@
 </div>
 
 <script is:inline>
-  function setupSearch() {
-    const modal = document.getElementById('search-modal');
-    const input = document.getElementById('search-input');
-    const resultsContainer = document.getElementById('search-results');
-    const backdrop = modal?.querySelector('.search-backdrop');
-    let pagefind = null;
-    let pagefindLoading = null;
-    let debounceTimer;
-    let searchCounter = 0;
+  /* One-time document listeners: survives Astro client navigations (body swap)
+     where this inline script would not run again. */
+  (function () {
+    if (window.__spicetifySearchInit) return;
+    window.__spicetifySearchInit = true;
+
+    var pagefind = null;
+    var pagefindLoading = null;
+    var debounceTimer;
+    var searchCounter = 0;
+
+    function getEls() {
+      return {
+        modal: document.getElementById('search-modal'),
+        input: document.getElementById('search-input'),
+        resultsContainer: document.getElementById('search-results'),
+      };
+    }
 
     async function loadPagefind() {
       if (pagefind) return pagefind;
       if (pagefindLoading) return pagefindLoading;
       pagefindLoading = import(/* @vite-ignore */ '/pagefind/pagefind.js')
-        .then(function(pf) { return pf.init().then(function() { pagefind = pf; return pf; }); })
-        .catch(function() { pagefindLoading = null; return null; });
+        .then(function (pf) {
+          return pf.init().then(function () {
+            pagefind = pf;
+            return pf;
+          });
+        })
+        .catch(function () {
+          pagefindLoading = null;
+          return null;
+        });
       return pagefindLoading;
     }
 
     function openModal() {
-      if (!modal) return;
-      modal.setAttribute('aria-hidden', 'false');
+      var els = getEls();
+      if (!els.modal) return;
+      els.modal.setAttribute('aria-hidden', 'false');
       document.body.style.overflow = 'hidden';
-      input?.focus();
+      els.input?.focus();
       loadPagefind();
     }
 
     function closeModal() {
-      if (!modal) return;
-      modal.setAttribute('aria-hidden', 'true');
+      var els = getEls();
+      if (!els.modal) return;
+      els.modal.setAttribute('aria-hidden', 'true');
       document.body.style.overflow = '';
       clearTimeout(debounceTimer);
       searchCounter++;
-      if (input) input.value = '';
-      if (resultsContainer) resultsContainer.innerHTML = '';
+      if (els.input) els.input.value = '';
+      if (els.resultsContainer) els.resultsContainer.innerHTML = '';
     }
 
     function isOpen() {
-      return modal?.getAttribute('aria-hidden') === 'false';
+      return getEls().modal?.getAttribute('aria-hidden') === 'false';
     }
 
     async function performSearch(query) {
-      if (!resultsContainer) return;
+      var els = getEls();
+      if (!els.resultsContainer) return;
       if (!query.trim()) {
-        resultsContainer.innerHTML = '<div class="search-empty">Start typing to search...</div>';
+        els.resultsContainer.innerHTML =
+          '<div class="search-empty">Start typing to search...</div>';
         return;
       }
 
@@ -81,7 +102,8 @@
 
       var pf = await loadPagefind();
       if (!pf) {
-        resultsContainer.innerHTML = '<div class="search-empty">Search unavailable</div>';
+        els.resultsContainer.innerHTML =
+          '<div class="search-empty">Search unavailable</div>';
         return;
       }
 
@@ -89,17 +111,20 @@
       if (thisSearch !== searchCounter) return;
 
       if (search.results.length === 0) {
-        resultsContainer.innerHTML = '<div class="search-empty">No results found</div>';
+        els.resultsContainer.innerHTML =
+          '<div class="search-empty">No results found</div>';
         return;
       }
 
       var items = await Promise.all(
-        search.results.slice(0, 10).map(function(r) { return r.data(); }),
+        search.results.slice(0, 10).map(function (r) {
+          return r.data();
+        }),
       );
       if (thisSearch !== searchCounter) return;
 
-      resultsContainer.innerHTML = '';
-      items.forEach(function(item) {
+      els.resultsContainer.innerHTML = '';
+      items.forEach(function (item) {
         var url = item.url.replace(/\.html$/, '');
         var link = document.createElement('a');
         link.href = url;
@@ -116,70 +141,77 @@
         excerptEl.innerHTML = item.excerpt;
         link.appendChild(excerptEl);
 
-        resultsContainer.appendChild(link);
+        els.resultsContainer.appendChild(link);
       });
     }
 
-    document.addEventListener('keydown', (e) => {
+    document.addEventListener('keydown', function (e) {
       if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
         e.preventDefault();
-        if (isOpen()) {
-          closeModal();
-        } else {
-          openModal();
-        }
+        if (isOpen()) closeModal();
+        else openModal();
+      }
+      if (e.key === 'Escape' && isOpen()) closeModal();
+    });
+
+    document.addEventListener('click', function (e) {
+      var t = e.target;
+      if (t && t.closest && t.closest('[data-search-trigger]')) {
+        e.preventDefault();
+        openModal();
+        return;
       }
-      if (e.key === 'Escape' && isOpen()) {
+      if (t && t.closest && t.closest('.search-backdrop')) {
         closeModal();
       }
     });
 
-    backdrop?.addEventListener('click', closeModal);
-
-    input?.addEventListener('input', () => {
-      clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        performSearch(input.value);
-      }, 200);
+    document.addEventListener('input', function (e) {
+      if (e.target && e.target.id === 'search-input') {
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(function () {
+          performSearch(e.target.value);
+        }, 200);
+      }
     });
 
-    input?.addEventListener('keydown', (e) => {
-      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+    document.addEventListener('keydown', function (e) {
+      var els = getEls();
+      if (e.target === els.input && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
         e.preventDefault();
-        const results = resultsContainer?.querySelectorAll('.search-result');
+        var results = els.resultsContainer?.querySelectorAll('.search-result');
         if (!results?.length) return;
-        const focused = resultsContainer?.querySelector('.search-result:focus');
-        let index = focused ? Array.from(results).indexOf(focused) : -1;
+        var focused = els.resultsContainer?.querySelector('.search-result:focus');
+        var index = focused ? Array.from(results).indexOf(focused) : -1;
         if (e.key === 'ArrowDown') index = Math.min(index + 1, results.length - 1);
         else index = Math.max(index - 1, 0);
         results[index].focus();
+        return;
       }
-    });
 
-    resultsContainer?.addEventListener('keydown', (e) => {
-      const target = e.target;
-      if (e.key === 'Enter' && target.classList.contains('search-result')) {
-        target.click();
-      }
-      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
-        e.preventDefault();
-        const results = resultsContainer.querySelectorAll('.search-result');
-        const index = Array.from(results).indexOf(target);
-        if (e.key === 'ArrowDown' && index < results.length - 1) {
-          results[index + 1].focus();
-        } else if (e.key === 'ArrowUp') {
-          if (index === 0) input?.focus();
-          else results[index - 1].focus();
+      if (
+        e.target &&
+        e.target.classList &&
+        e.target.classList.contains('search-result')
+      ) {
+        if (e.key === 'Enter') {
+          e.target.click();
+        }
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+          e.preventDefault();
+          if (!els.resultsContainer) return;
+          var res = els.resultsContainer.querySelectorAll('.search-result');
+          var idx = Array.from(res).indexOf(e.target);
+          if (e.key === 'ArrowDown' && idx < res.length - 1) {
+            res[idx + 1].focus();
+          } else if (e.key === 'ArrowUp') {
+            if (idx === 0) els.input?.focus();
+            else res[idx - 1].focus();
+          }
         }
       }
     });
-
-    document.querySelectorAll('[data-search-trigger]').forEach((btn) => {
-      btn.addEventListener('click', openModal);
-    });
-  }
-
-  setupSearch();
+  })();
 </script>
 
 <style>
diff --git a/src/components/Tabs.astro b/src/components/Tabs.astro
index 71c19a4d..c6394269 100644
--- a/src/components/Tabs.astro
+++ b/src/components/Tabs.astro
@@ -109,4 +109,5 @@ const { groupId } = Astro.props;
   }
 
   initTabs();
+  document.addEventListener('astro:page-load', initTabs);
 </script>
diff --git a/src/components/homepage/InstallSection.astro b/src/components/homepage/InstallSection.astro
index a9d0ac57..91f0eac8 100644
--- a/src/components/homepage/InstallSection.astro
+++ b/src/components/homepage/InstallSection.astro
@@ -66,6 +66,11 @@ type Props = {};
 
 <script is:inline>
   (function () {
+    function bindInstallSection() {
+      var root = document.querySelector('.install-section');
+      if (!root || root.dataset.interactiveInit) return;
+      root.dataset.interactiveInit = '1';
+
     function setupInstallTabs() {
       var tabs = Array.from(document.querySelectorAll('.install-tab'));
       var panels = document.querySelectorAll('.install-panel');
@@ -164,6 +169,10 @@ type Props = {};
 
     setupInstallTabs();
     setupCopyButton();
+    }
+
+    document.addEventListener('astro:page-load', bindInstallSection);
+    bindInstallSection();
   })();
 </script>
 
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 6fc109ab..7a414d0e 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -1,4 +1,5 @@
 ---
+import { ClientRouter } from 'astro:transitions';
 import Footer from '../components/Footer.astro';
 import Navbar from '../components/Navbar.astro';
 import SEO from '../components/SEO.astro';
@@ -63,6 +64,9 @@ const fullTitle = title === 'Spicetify' ? title : `${title} | Spicetify`;
           applyTheme(resolveTheme());
         }
       });
+      document.addEventListener('astro:after-swap', () => {
+        applyTheme(resolveTheme());
+      });
     </script>
     <style is:inline>
       /* Beat UA default body background until global CSS loads */
@@ -79,6 +83,7 @@ const fullTitle = title === 'Spicetify' ? title : `${title} | Spicetify`;
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Syne:wght@600;700;800&display=swap" />
     <title>{fullTitle}</title>
     <SEO title={title} description={description} image={image} type={type} />
+    <ClientRouter />
   </head>
   <body>
     <a href="#main-content" class="skip-to-content">Skip to content</a>

From 07cd1502da77eaf28c5a37a125b5049e4e334eb0 Mon Sep 17 00:00:00 2001
From: Adam Osman <kawaiiyou3@gmail.com>
Date: Fri, 1 May 2026 20:53:17 -0400
Subject: [PATCH 3/3] fix(docs): disable default link prefetch with
 ClientRouter

prefetch-all plus many doc links caused noisy background fetches and made
the tab/URL UI feel like it was constantly updating.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 astro.config.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/astro.config.ts b/astro.config.ts
index a80d695b..ab372d65 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -11,6 +11,10 @@ import { remarkReadingTime } from './src/plugins/remark-reading-time.mjs';
 export default defineConfig({
   site: 'https://spicetify.app',
   trailingSlash: 'never',
+  // `<ClientRouter />` defaults to prefetch-all links, which spams fetches and can make
+  // the tab title / URL bar look like they’re constantly updating. Opt out; navigations
+  // are still client-side on click.
+  prefetch: false,
   build: {
     format: 'file',
   },

No results found