From d3460dc84352859a982324385a6cbe707ac9e7ec Mon Sep 17 00:00:00 2001
From: Thomas Deinhamer <code@thasmo.dev>
Date: Sun, 8 Feb 2026 13:49:03 +0100
Subject: [PATCH] fix: streamline anchor scrolling

---
 app/assets/main.css                          |  2 +-
 app/components/CollapsibleSection.vue        | 17 +---
 app/components/Link/Base.vue                 |  4 +-
 app/components/PackageProvenanceSection.vue  | 11 +--
 app/components/Readme.vue                    |  9 +-
 app/components/ReadmeTocDropdown.vue         | 28 +++---
 app/composables/useActiveTocItem.ts          | 90 +-------------------
 app/pages/package/[[org]]/[name].vue         |  3 +-
 app/utils/scrollToAnchor.ts                  | 45 ----------
 nuxt.config.ts                               |  6 ++
 test/nuxt/components/PackageVersions.spec.ts |  4 +-
 11 files changed, 43 insertions(+), 176 deletions(-)
 delete mode 100644 app/utils/scrollToAnchor.ts

diff --git a/app/assets/main.css b/app/assets/main.css
index 0e46a37b8..dbf096b22 100644
--- a/app/assets/main.css
+++ b/app/assets/main.css
@@ -192,11 +192,11 @@
 */
 
 html {
+  @apply scroll-pt-20;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   text-rendering: optimizeLegibility;
   /* Offset for fixed header - otherwise anchor headers are cutted */
-  scroll-padding-top: 5rem;
   scrollbar-gutter: stable;
 }
 
diff --git a/app/components/CollapsibleSection.vue b/app/components/CollapsibleSection.vue
index bf48c9eb0..7727202c2 100644
--- a/app/components/CollapsibleSection.vue
+++ b/app/components/CollapsibleSection.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { shallowRef, computed } from 'vue'
+import { LinkBase } from '#components'
 
 interface Props {
   title: string
@@ -18,7 +19,6 @@ const appSettings = useSettings()
 
 const buttonId = `${props.id}-collapsible-button`
 const contentId = `${props.id}-collapsible-content`
-const headingId = `${props.id}-heading`
 
 const isOpen = shallowRef(true)
 
@@ -75,11 +75,10 @@ useHead({
 </script>
 
 <template>
-  <section class="scroll-mt-20" :data-anchor-id="id">
+  <section :id="id" :data-anchor-id="id" class="scroll-mt-20 xl:scroll-mt-0">
     <div class="flex items-center justify-between mb-3 px-1">
       <component
         :is="headingLevel"
-        :id="headingId"
         class="group text-xs text-fg-subtle uppercase tracking-wider flex items-center gap-2"
       >
         <button
@@ -104,17 +103,9 @@ useHead({
           />
         </button>
 
-        <a
-          :href="`#${id}`"
-          class="inline-flex items-center gap-1.5 text-fg-subtle hover:text-fg-muted transition-colors duration-200 no-underline"
-        >
-          <span v-if="icon" :class="icon" aria-hidden="true" />
+        <LinkBase :to="`#${id}`" class="">
           {{ title }}
-          <span
-            class="i-carbon:link w-3 h-3 opacity-0 group-hover:opacity-100 transition-opacity duration-200"
-            aria-hidden="true"
-          />
-        </a>
+        </LinkBase>
       </component>
 
       <!-- Actions slot for buttons or other elements -->
diff --git a/app/components/Link/Base.vue b/app/components/Link/Base.vue
index 2c4521e24..52d474d5d 100644
--- a/app/components/Link/Base.vue
+++ b/app/components/Link/Base.vue
@@ -73,7 +73,7 @@ const isButtonMedium = computed(() => props.size === 'medium' && props.variant !
   /></span>
   <NuxtLink
     v-else
-    class="group inline-flex gap-x-1 items-center justify-center"
+    class="group/link inline-flex gap-x-1 items-center justify-center"
     :class="{
       'underline-offset-[0.2rem] underline decoration-1 decoration-fg/30': !isLinkAnchor && isLink,
       'font-mono text-fg hover:(decoration-accent text-accent) focus-visible:(decoration-accent text-accent) transition-colors duration-200':
@@ -103,7 +103,7 @@ const isButtonMedium = computed(() => props.size === 'medium' && props.variant !
     />
     <span
       v-else-if="isLinkAnchor && isLink"
-      class="i-carbon:link w-3 h-3 opacity-0 group-hover:opacity-100 transition-opacity duration-200"
+      class="i-carbon:link w-3 h-3 opacity-0 group-hover/link:opacity-100 transition-opacity duration-200"
       aria-hidden="true"
     />
     <kbd
diff --git a/app/components/PackageProvenanceSection.vue b/app/components/PackageProvenanceSection.vue
index 27cbeb5ea..caf6cd36d 100644
--- a/app/components/PackageProvenanceSection.vue
+++ b/app/components/PackageProvenanceSection.vue
@@ -9,16 +9,9 @@ defineProps<{
 <template>
   <section id="provenance" aria-labelledby="provenance-heading" class="scroll-mt-20">
     <h2 id="provenance-heading" class="group text-xs text-fg-subtle uppercase tracking-wider mb-3">
-      <a
-        href="#provenance"
-        class="inline-flex items-center gap-1.5 text-fg-subtle hover:text-fg-muted transition-colors duration-200 no-underline"
-      >
+      <LinkBase to="#provenance">
         {{ $t('package.provenance_section.title') }}
-        <span
-          class="i-carbon-link w-3 h-3 block opacity-0 group-hover:opacity-100 transition-opacity duration-200"
-          aria-hidden="true"
-        />
-      </a>
+      </LinkBase>
     </h2>
 
     <div class="space-y-3 border border-border rounded-lg p-4 sm:p-5">
diff --git a/app/components/Readme.vue b/app/components/Readme.vue
index 38f76bee7..512e217cf 100644
--- a/app/components/Readme.vue
+++ b/app/components/Readme.vue
@@ -47,6 +47,13 @@ function handleClick(event: MouseEvent) {
   const href = anchor.getAttribute('href')
   if (!href) return
 
+  // Handle relative anchor links
+  if (href.startsWith('#')) {
+    event.preventDefault()
+    router.push(href)
+    return
+  }
+
   const match = href.match(/^(?:https?:\/\/)?(?:www\.)?npmjs\.(?:com|org)(\/.+)$/)
   if (!match || !match[1]) return
 
@@ -95,8 +102,8 @@ function handleClick(event: MouseEvent) {
 .readme :deep(h4),
 .readme :deep(h5),
 .readme :deep(h6) {
+  @apply font-mono scroll-mt-20;
   color: var(--fg);
-  @apply font-mono;
   font-weight: 500;
   margin-top: 1rem;
   margin-bottom: 1rem;
diff --git a/app/components/ReadmeTocDropdown.vue b/app/components/ReadmeTocDropdown.vue
index 65d1da3e4..16cbdad65 100644
--- a/app/components/ReadmeTocDropdown.vue
+++ b/app/components/ReadmeTocDropdown.vue
@@ -1,12 +1,10 @@
 <script setup lang="ts">
 import type { TocItem } from '#shared/types/readme'
 import { onClickOutside, useEventListener } from '@vueuse/core'
-import { scrollToAnchor } from '~/utils/scrollToAnchor'
 
 const props = defineProps<{
   toc: TocItem[]
   activeId?: string | null
-  scrollToHeading?: (id: string) => void
 }>()
 
 interface TocNode extends TocItem {
@@ -98,8 +96,7 @@ function close() {
   highlightedIndex.value = -1
 }
 
-function select(id: string) {
-  scrollToAnchor(id, { scrollFn: props.scrollToHeading })
+function select() {
   close()
   triggerRef.value?.focus()
 }
@@ -132,7 +129,7 @@ function handleKeydown(event: KeyboardEvent) {
       event.preventDefault()
       const item = props.toc[highlightedIndex.value]
       if (item) {
-        select(item.id)
+        select()
       }
       break
     }
@@ -189,8 +186,9 @@ function handleKeydown(event: KeyboardEvent) {
         class="fixed bg-bg-subtle border border-border rounded-md shadow-lg z-50 max-h-80 overflow-y-auto w-56 overscroll-contain"
       >
         <template v-for="node in tocTree" :key="node.id">
-          <div
+          <NuxtLink
             :id="`${listboxId}-${node.id}`"
+            :to="`#${node.id}`"
             role="option"
             :aria-selected="activeId === node.id"
             class="flex items-center gap-2 px-3 py-1.5 text-sm cursor-pointer transition-colors duration-150"
@@ -199,15 +197,16 @@ function handleKeydown(event: KeyboardEvent) {
               highlightedIndex === getIndex(node.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
             ]"
             dir="auto"
-            @click="select(node.id)"
+            @click="select()"
             @mouseenter="highlightedIndex = getIndex(node.id)"
           >
             <span class="truncate">{{ node.text }}</span>
-          </div>
+          </NuxtLink>
 
           <template v-for="child in node.children" :key="child.id">
-            <div
+            <NuxtLink
               :id="`${listboxId}-${child.id}`"
+              :to="`#${child.id}`"
               role="option"
               :aria-selected="activeId === child.id"
               class="flex items-center gap-2 px-3 py-1.5 ps-6 text-sm cursor-pointer transition-colors duration-150"
@@ -216,15 +215,16 @@ function handleKeydown(event: KeyboardEvent) {
                 highlightedIndex === getIndex(child.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
               ]"
               dir="auto"
-              @click="select(child.id)"
+              @click="select()"
               @mouseenter="highlightedIndex = getIndex(child.id)"
             >
               <span class="truncate">{{ child.text }}</span>
-            </div>
+            </NuxtLink>
 
-            <div
+            <NuxtLink
               v-for="grandchild in child.children"
               :id="`${listboxId}-${grandchild.id}`"
+              :to="`#${grandchild.id}`"
               :key="grandchild.id"
               role="option"
               :aria-selected="activeId === grandchild.id"
@@ -236,11 +236,11 @@ function handleKeydown(event: KeyboardEvent) {
                   : 'hover:bg-bg-elevated',
               ]"
               dir="auto"
-              @click="select(grandchild.id)"
+              @click="select()"
               @mouseenter="highlightedIndex = getIndex(grandchild.id)"
             >
               <span class="truncate">{{ grandchild.text }}</span>
-            </div>
+            </NuxtLink>
           </template>
         </template>
       </div>
diff --git a/app/composables/useActiveTocItem.ts b/app/composables/useActiveTocItem.ts
index 3898e6a23..db3fb1594 100644
--- a/app/composables/useActiveTocItem.ts
+++ b/app/composables/useActiveTocItem.ts
@@ -1,13 +1,12 @@
 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.
  * Uses IntersectionObserver to detect which heading is at the top of the viewport.
  *
  * @param toc - Reactive array of TOC items
- * @returns Object containing activeId and scrollToHeading function
+ * @returns Object containing activeId
  * @public
  */
 export function useActiveTocItem(toc: Ref<TocItem[]>) {
@@ -16,12 +15,11 @@ export function useActiveTocItem(toc: Ref<TocItem[]>) {
   // Only run observer logic on client
   if (import.meta.server) {
     // eslint-disable-next-line @typescript-eslint/no-empty-function
-    return { activeId, scrollToHeading: (_id: string) => {} }
+    return { activeId }
   }
 
   let observer: IntersectionObserver | null = null
   const headingElements = new Map<string, Element>()
-  let scrollCleanup: (() => void) | null = null
 
   const setupObserver = () => {
     // Clean up previous observer
@@ -92,84 +90,6 @@ export function useActiveTocItem(toc: Ref<TocItem[]>) {
     }
   }
 
-  // Scroll to a heading with observer disconnection during scroll
-  const scrollToHeading = (id: string) => {
-    if (!document.getElementById(id)) return
-
-    // Clean up any previous scroll monitoring
-    if (scrollCleanup) {
-      scrollCleanup()
-      scrollCleanup = null
-    }
-
-    // Immediately set activeId
-    activeId.value = id
-
-    // Disconnect observer to prevent interference during scroll
-    if (observer) {
-      observer.disconnect()
-    }
-
-    // Scroll, but do not update url until scroll ends
-    scrollToAnchor(id, { updateUrl: false })
-
-    const handleScrollEnd = () => {
-      history.replaceState(null, '', `#${id}`)
-      setupObserver()
-      scrollCleanup = null
-    }
-
-    // Check for scrollend support (Chrome 114+, Firefox 109+, Safari 18+)
-    const supportsScrollEnd = 'onscrollend' in window
-
-    if (supportsScrollEnd) {
-      window.addEventListener('scrollend', handleScrollEnd, { once: true })
-      scrollCleanup = () => window.removeEventListener('scrollend', handleScrollEnd)
-    } else {
-      // Fallback: use RAF polling for older browsers
-      let lastScrollY = window.scrollY
-      let stableFrames = 0
-      let rafId: number | null = null
-      const STABLE_THRESHOLD = 5 // Number of frames with no movement to consider settled
-
-      const checkScrollSettled = () => {
-        const currentScrollY = window.scrollY
-
-        if (Math.abs(currentScrollY - lastScrollY) < 1) {
-          stableFrames++
-          if (stableFrames >= STABLE_THRESHOLD) {
-            handleScrollEnd()
-            return
-          }
-        } else {
-          stableFrames = 0
-        }
-
-        lastScrollY = currentScrollY
-        rafId = requestAnimationFrame(checkScrollSettled)
-      }
-
-      rafId = requestAnimationFrame(checkScrollSettled)
-
-      scrollCleanup = () => {
-        if (rafId !== null) {
-          cancelAnimationFrame(rafId)
-          rafId = null
-        }
-      }
-    }
-
-    // Safety timeout - reconnect observer after max scroll time
-    setTimeout(() => {
-      if (scrollCleanup) {
-        scrollCleanup()
-        scrollCleanup = null
-        history.replaceState(null, '', `#${id}`)
-        setupObserver()
-      }
-    }, 1000)
-  }
-
   // Set up observer when TOC changes
   watch(
     toc,
@@ -182,15 +102,11 @@ export function useActiveTocItem(toc: Ref<TocItem[]>) {
 
   // Clean up on unmount
   onUnmounted(() => {
-    if (scrollCleanup) {
-      scrollCleanup()
-      scrollCleanup = null
-    }
     if (observer) {
       observer.disconnect()
       observer = null
     }
   })
 
-  return { activeId, scrollToHeading }
+  return { activeId }
 }
diff --git a/app/pages/package/[[org]]/[name].vue b/app/pages/package/[[org]]/[name].vue
index a30da386e..e806983be 100644
--- a/app/pages/package/[[org]]/[name].vue
+++ b/app/pages/package/[[org]]/[name].vue
@@ -72,7 +72,7 @@ const { copied: copiedReadme, copy: copyReadme } = useClipboard({
 
 // Track active TOC item based on scroll position
 const tocItems = computed(() => readmeData.value?.toc ?? [])
-const { activeId: activeTocId, scrollToHeading } = useActiveTocItem(tocItems)
+const { activeId: activeTocId } = useActiveTocItem(tocItems)
 
 // Check if package exists on JSR (only for scoped packages)
 const { data: jsrInfo } = useLazyFetch<JsrPackageInfo>(() => `/api/jsr/${packageName.value}`, {
@@ -1079,7 +1079,6 @@ onKeyStroke(
                 v-if="readmeData?.toc && readmeData.toc.length > 1"
                 :toc="readmeData.toc"
                 :active-id="activeTocId"
-                :scroll-to-heading="scrollToHeading"
               />
             </div>
           </ClientOnly>
diff --git a/app/utils/scrollToAnchor.ts b/app/utils/scrollToAnchor.ts
deleted file mode 100644
index f0ec64be4..000000000
--- a/app/utils/scrollToAnchor.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-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 options - Optional configuration for scroll behavior
- */
-export function scrollToAnchor(id: string, options?: ScrollToAnchorOptions): void {
-  const { scrollFn, updateUrl = true } = options ?? {}
-
-  // Use custom scroll function if provided
-  if (scrollFn) {
-    scrollFn(id)
-    return
-  }
-
-  // Fallback: scroll with header offset
-  const element = document.getElementById(id)
-  if (!element) return
-
-  // 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 + PKG_STICKY_HEADER_OFFSET)
-
-  // Use scrollTo for precise control
-  window.scrollTo({
-    top: targetScrollY,
-    behavior: 'smooth',
-  })
-
-  // Update URL hash after initiating scroll
-  // Use replaceState to avoid triggering native scroll-to-anchor behavior
-  if (updateUrl) {
-    history.replaceState(null, '', `#${id}`)
-  }
-}
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 65eee74cc..753a467b6 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -79,6 +79,12 @@ export default defineNuxtConfig({
     description: 'A fast, modern browser for the npm registry',
   },
 
+  router: {
+    options: {
+      scrollBehaviorType: 'smooth',
+    },
+  },
+
   routeRules: {
     // API routes
     '/api/**': { isr: 60 },
diff --git a/test/nuxt/components/PackageVersions.spec.ts b/test/nuxt/components/PackageVersions.spec.ts
index 0853d1b3d..366c9217e 100644
--- a/test/nuxt/components/PackageVersions.spec.ts
+++ b/test/nuxt/components/PackageVersions.spec.ts
@@ -33,7 +33,7 @@ describe('PackageVersions', () => {
   })
 
   describe('basic rendering', () => {
-    it('renders the Versions heading', async () => {
+    it('renders the Versions section', async () => {
       const component = await mountSuspended(PackageVersions, {
         props: {
           packageName: 'test-package',
@@ -45,7 +45,7 @@ describe('PackageVersions', () => {
         },
       })
 
-      expect(component.find('#versions-heading').text()).toBe('Versions')
+      expect(component.find('#versions').exists()).toBe(true)
     })
 
     it('does not render when there are no dist-tags', async () => {