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

Summary by CodeRabbit

• Bug Fixes
  • Improved theme persistence across page navigations with enhanced storage handling
  • Fixed search, tabs, and install section interactions to work reliably on client-side page transitions
  • Added sidebar scroll position preservation across navigation events

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

The PR refactors interactive components to safely initialize and re-initialize across Astro's client-side navigation. BaseLayout establishes theme and scroll lifecycle; Navbar consolidates interactions with lifecycle-aware listeners; SearchModal moves to delegated document listeners; Tabs and InstallSection register astro:page-load handlers to re-init on navigation.

Changes

Astro Lifecycle Navigation Support

Layer / File(s)	Summary
BaseLayout: Theme and scroll lifecycle src/layouts/BaseLayout.astro	Theme application split into resolve/apply functions that run on DOMContentLoaded, pageshow (persisted), and astro:after-swap. Inline CSS ensures body background matches the theme before global styles load. Separate inline script preserves .docs-sidebar scroll position across astro:before-swap and astro:after-swap. ClientRouter import added.
Navbar: Consolidated theme and menu interactions with AbortController src/components/Navbar.astro	setupNavbarInteractions consolidates theme toggle and mobile menu into one initializer using AbortController for clean listener re-registration on astro:page-load. Theme persists to localStorage with try/catch fallback, and mobile menu updates aria-expanded and the open class on .docs-sidebar or .mobile-nav.
SearchModal: One-time initialization with delegated document listeners src/components/SearchModal.astro	Replaces per-element listeners with document-level delegated handlers guarded by window.__spicetifySearchInit. Keyboard shortcuts (Ctrl/⌘+K, Escape, Arrow keys for result navigation), click-to-open via [data-search-trigger], and debounced input search are consolidated into global listeners. Modal and results elements are resolved dynamically.
Tabs and InstallSection: astro:page-load lifecycle hooks src/components/Tabs.astro, src/components/homepage/InstallSection.astro	Tabs registers initTabs on astro:page-load. InstallSection wraps initialization in bindInstallSection with a data-interactive-init guard flag and registers for astro:page-load to re-initialize without double-initialization.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• spicetify/docs#205: Directly related to the InstallSection lifecycle integration; introduces the component and inline interaction logic that this PR now wires to Astro's astro:page-load event.

Poem

A navigation so swift, with lifecycles tight,
Components now dance through each Astro flight.
Where toggles consolidate, listeners spread wide,
Guards and AbortControllers walk side by side.
The sidebar scrolls sweetly through every new view— 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly addresses the main objectives: preventing theme flash and enabling client-side navigation (both explicitly stated in PR objectives), making it fully related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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

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