fix(docs): theme flash + client-side navigation

[aosmannn]

Summary

• Theme flash: Run the theme bootstrap script before render-blocking stylesheets (e.g. Google Fonts), add critical body background rules, normalize localStorage theme values, reapply on DOMContentLoaded / bfcache pageshow, and on astro:after-swap so dark mode stays consistent during view transitions.
• Navigation: Enable Astro ClientRouter so in-site doc links use client-side navigations instead of a full document reload. Rebind navbar listeners on astro:page-load, use document-level delegation for the search modal, and reinit tabs / homepage install section after navigations.

Test plan

• npm run dev — dark mode, click many doc sidebar links — no light flash, no full reload feel
• Theme toggle, Cmd/Ctrl+K search, mobile menu
• Pages with Tabs (MDX) and homepage Install block after navigating away and back

Made with Cursor

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Improved search modal stability across page navigations
  • Enhanced theme toggle and mobile menu interaction persistence
  • Strengthened theme initialization with better error handling and fallback logic
  • Fixed tab initialization timing during page transitions

• New Features

  • Implemented client-side routing for smoother navigation experiences

[aosmannn]

Closing per author request.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b1410627-07e4-4639-a9e4-9d49e3c03226

📥 Commits

Reviewing files that changed from the base of the PR and between 2740b2c and 7840407.

📒 Files selected for processing (5)

• src/components/Navbar.astro
• src/components/SearchModal.astro
• src/components/Tabs.astro
• src/components/homepage/InstallSection.astro
• src/layouts/BaseLayout.astro

---

Walkthrough

Multiple Astro components are refactored to prevent duplicate event listeners across client navigations by adopting persistent, guarded initialization patterns. The Navbar uses an AbortController to rebind listeners, SearchModal switches to one-time document-level handlers with a guard flag, Tabs and InstallSection are wired to astro:page-load, and BaseLayout reworks theme initialization with defensive code and adds the ClientRouter component.

Changes

Component Event Listener Lifecycle Management

Layer / File(s)	Summary
Listener Abort & Rebind src/components/Navbar.astro	Introduces navListenersAbort AbortController and setupNavbarInteractions() to abort prior theme-toggle and mobile-menu listeners before re-registering on each page load. Wires to astro:page-load for rebinding across navigations.
One-Time Document Listeners src/components/SearchModal.astro	Refactors setupSearch() into a self-invoking IIFE guarded by window.__spicetifySearchInit to install document-level listeners once across navigations. Moves DOM lookups to runtime via getEls() helper. Centralizes modal open/close, search triggering, and keyboard navigation into single document event handlers.
Page-Load Event Registration src/components/Tabs.astro, src/components/homepage/InstallSection.astro	Registers initTabs and bindInstallSection() to fire on astro:page-load. InstallSection adds data-interactive-init guard to prevent duplicate setup within a page instance.

Theme & Routing Infrastructure

Layer / File(s)	Summary
Defensive Theme Initialization src/layouts/BaseLayout.astro	Replaces inline theme IIFE with applyTheme/resolveTheme flow: includes try/catch around localStorage, media-query fallback, and re-applies theme on DOMContentLoaded, pageshow, and astro:after-swap. Also sets document.body background when available.
Flash Prevention & Routing Setup src/layouts/BaseLayout.astro	Adds inline stylesheet to set initial body background based on html[data-theme] before global CSS loads, preventing theme flash. Imports and renders <ClientRouter /> in document head to manage client-side transitions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: redesign homepage with new hero, themes bento grid, and features section #205: Modifies src/components/homepage/InstallSection.astro alongside the main PR, suggesting related work on the install section component structure and initialization.

Poem

🐰 Hops through the nav with grace so fleet,
One-time listeners, no skipped beats,
Guard flags guard and abort controls guide,
Theme persists, with ClientRouter's pride!
Astro's dance—no more duplicate fate, ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}