fix(docs): resolve duplicate mobile burger menu and delegate popover toggle

[max-ostapenko]

Description

Resolves an issue where two hamburger buttons appeared side-by-side in docs on mobile viewports.

Root Cause

When @astrojs/starlight was upgraded to 0.42.4, the mobile menu toggle mechanism was refactored to use the native HTML Popover API with <button class="sl-menu-button">, deprecating the older <starlight-menu-button> custom element.

Solution

• astro.config.mjs: Overrode MobileMenuToggle with ./src/components/docs/EmptyComponent.astro (matching the pattern already used for ThemeSelect). Starlight no longer renders <button class="sl-menu-button">.
• Header.astro:
  • Removed obsolete starlight-menu-button style rule.
  • Added background body scroll locking on mobile using body:has(.sidebar-pane:popover-open) { overflow: hidden; } (which respects stylelint rules and replaces the style previously bundled in Starlight's default toggle component).
  • Updated the .hamburger click listener to control #starlight__sidebar directly using the native Popover API (sidebar.togglePopover()).
  • Synced aria-expanded via native toggle events dispatched on #starlight__sidebar.
  • Removed obsolete MutationObserver watching data-mobile-menu-expanded on document.body.

Verification

• DOM verification: 0 instances of sl-menu-button generated.
• Mobile viewport testing (Puppeteer @ 375x667): tapping .hamburger opens and closes the drawer, updates aria-expanded, and dismisses properly via Escape key.
• starlight-custom.css is completely untouched, eliminating stylelint selector-id-pattern errors in CI.
• Verified npm run astro:build builds cleanly.
• Verified npm test passes (all 78 tests passed).

[github-actions]

Visit the preview URL for this PR (updated for commit 52a867c):

https://httparchive--pr1366-fix-docs-duplicate-m-6w5tdte4.web.app

_{(expires Sun, 11 Oct 2026 20:16:06 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 1069cba7974889c25bacf4f0a19ddb6735592729}

[tunetheweb]

Pity there isn’t a programmatic way to turn it off in Starlight.

[max-ostapenko]

A straightforward override now.