fix: sticky package header offset

Author: vinnymac

app/components/ReadmeTocDropdown.vue

@@ -99,7 +99,7 @@ function close() {
 }
 
 function select(id: string) {
-  scrollToAnchor(id, props.scrollToHeading)
+  scrollToAnchor(id, { scrollFn: props.scrollToHeading })
   close()
   triggerRef.value?.focus()
 }

app/composables/useActiveTocItem.ts

@@ -1,5 +1,6 @@
 import type { TocItem } from '#shared/types/readme'
 import type { Ref } from 'vue'
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
 
 /**
  * Composable for tracking the currently visible heading in a TOC.
@@ -93,8 +94,7 @@ export function useActiveTocItem(toc: Ref<TocItem[]>) {
 
   // Scroll to a heading with observer disconnection during scroll
   const scrollToHeading = (id: string) => {
-    const element = document.getElementById(id)
-    if (!element) return
+    if (!document.getElementById(id)) return
 
     // Clean up any previous scroll monitoring
     if (scrollCleanup) {
@@ -110,19 +110,8 @@ export function useActiveTocItem(toc: Ref<TocItem[]>) {
       observer.disconnect()
     }
 
-    // Calculate scroll position with header offset (5rem = 80px)
-    // This matches the scroll-padding-top in main.css
-    const HEADER_OFFSET = 80
-    const elementTop = element.getBoundingClientRect().top + window.scrollY
-    const targetScrollY = elementTop - HEADER_OFFSET
-
-    // Use scrollTo for precise control (respects CSS scroll-behavior: smooth)
-    // Don't update URL hash yet - do it after scroll completes to avoid
-    // browser native scroll-to-anchor behavior interfering
-    window.scrollTo({
-      top: targetScrollY,
-      behavior: 'smooth',
-    })
+    // Scroll, but do not update url until scroll ends
+    scrollToAnchor(id, { updateUrl: false })
 
     const handleScrollEnd = () => {
       history.replaceState(null, '', `#${id}`)

app/utils/scrollToAnchor.ts

@@ -1,11 +1,20 @@
+export interface ScrollToAnchorOptions {
+  /** Custom scroll function (e.g., from useActiveTocItem) */
+  scrollFn?: (id: string) => void
+  /** Whether to update the URL hash (default: true) */
+  updateUrl?: boolean
+}
+
 /**
  * Scroll to an element by ID, using a custom scroll function if provided,
  * otherwise falling back to default scroll behavior with header offset.
  *
  * @param id - The element ID to scroll to
- * @param scrollFn - Optional custom scroll function (e.g., from useActiveTocItem)
+ * @param options - Optional configuration for scroll behavior
  */
-export function scrollToAnchor(id: string, scrollFn?: (id: string) => void): void {
+export function scrollToAnchor(id: string, options?: ScrollToAnchorOptions): void {
+  const { scrollFn, updateUrl = true } = options ?? {}
+
   // Use custom scroll function if provided
   if (scrollFn) {
     scrollFn(id)
@@ -18,8 +27,9 @@ export function scrollToAnchor(id: string, scrollFn?: (id: string) => void): voi
 
   // Calculate scroll position with header offset (matches scroll-padding-top in main.css)
   const HEADER_OFFSET = 80
+  const PKG_STICKY_HEADER_OFFSET = 52
   const elementTop = element.getBoundingClientRect().top + window.scrollY
-  const targetScrollY = elementTop - HEADER_OFFSET
+  const targetScrollY = elementTop - (HEADER_OFFSET + PKG_STICKY_HEADER_OFFSET)
 
   // Use scrollTo for precise control
   window.scrollTo({
@@ -29,5 +39,7 @@ export function scrollToAnchor(id: string, scrollFn?: (id: string) => void): voi
 
   // Update URL hash after initiating scroll
   // Use replaceState to avoid triggering native scroll-to-anchor behavior
-  history.replaceState(null, '', `#${id}`)
+  if (updateUrl) {
+    history.replaceState(null, '', `#${id}`)
+  }
 }