fix: enable hash link scrolling in README

app/components/Readme.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
+
 defineProps<{
   html: string
 }>()
@@ -9,6 +11,7 @@ const { copy } = useClipboard()
 // Combined click handler for:
 // 1. Intercepting npmjs.com links to route internally
 // 2. Copy button functionality for code blocks
+// 3. Hash link scrolling for internal README navigation (Table of Contents)
 function handleClick(event: MouseEvent) {
   const target = event.target as HTMLElement | undefined
   if (!target) return
@@ -40,13 +43,23 @@ function handleClick(event: MouseEvent) {
     return
   }
 
-  // Handle npmjs.com link clicks - route internally
+  // Handle anchor link clicks
   const anchor = target.closest('a')
   if (!anchor) return
 
   const href = anchor.getAttribute('href')
   if (!href) return
 
+  // Handle hash links for internal README navigation (e.g., Table of Contents)
+  if (href.startsWith('#')) {
+    event.preventDefault()
+    // Lowercase the ID to match heading slugs (generated with toLowerCase in slugify)
+    const id = href.slice(1).toLowerCase()
+    scrollToAnchor(id)
+    return
+  }
+
+  // Handle npmjs.com link clicks - route internally
   const match = href.match(/^(?:https?:\/\/)?(?:www\.)?npmjs\.(?:com|org)(\/.+)$/)
   if (!match || !match[1]) return
 

test/nuxt/components/Readme.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import Readme from '~/components/Readme.vue'
+
+// Mock scrollToAnchor
+vi.mock('~/utils/scrollToAnchor', () => ({
+  scrollToAnchor: vi.fn(),
+}))
+
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
+
+describe('Readme', () => {
+  describe('rendering', () => {
+    it('renders the provided HTML content', async () => {
+      const component = await mountSuspended(Readme, {
+        props: { html: '<p>Hello world</p>' },
+      })
+      expect(component.html()).toContain('Hello world')
+    })
+  })
+
+  describe('hash link click handling', () => {
+    it('intercepts hash link clicks and calls scrollToAnchor with lowercase ID', async () => {
+      const component = await mountSuspended(Readme, {
+        props: { html: '<a href="#Installation">Installation</a>' },
+      })
+
+      const link = component.find('a')
+      await link.trigger('click')
+
+      expect(scrollToAnchor).toHaveBeenCalledWith('installation')
+    })
+
+    it('handles user-content prefixed hash links', async () => {
+      vi.mocked(scrollToAnchor).mockClear()
+      const component = await mountSuspended(Readme, {
+        props: { html: '<a href="#user-content-getting-started">Getting Started</a>' },
+      })
+
+      const link = component.find('a')
+      await link.trigger('click')
+
+      expect(scrollToAnchor).toHaveBeenCalledWith('user-content-getting-started')
+    })
+  })
+})

test/nuxt/utils/scrollToAnchor.spec.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
+
+describe('scrollToAnchor', () => {
+  let scrollToSpy: ReturnType<typeof vi.fn>
+  let replaceStateSpy: ReturnType<typeof vi.fn>
+  let testElement: HTMLElement
+
+  beforeEach(() => {
+    // Spy on window.scrollTo
+    scrollToSpy = vi.fn()
+    vi.stubGlobal('scrollTo', scrollToSpy)
+
+    // Spy on history.replaceState
+    replaceStateSpy = vi.spyOn(history, 'replaceState').mockImplementation(() => {})
+
+    // Create a test element
+    testElement = document.createElement('div')
+    testElement.id = 'test-section'
+    document.body.appendChild(testElement)
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+    // Clean up test element
+    if (testElement && testElement.parentNode) {
+      testElement.parentNode.removeChild(testElement)
+    }
+  })
+
+  describe('with custom scrollFn', () => {
+    it('calls the provided scroll function with the id', () => {
+      const scrollFn = vi.fn()
+      scrollToAnchor('test-section', { scrollFn })
+
+      expect(scrollFn).toHaveBeenCalledWith('test-section')
+      expect(scrollToSpy).not.toHaveBeenCalled()
+    })
+
+    it('does not update URL when using custom scrollFn', () => {
+      const scrollFn = vi.fn()
+      scrollToAnchor('test-section', { scrollFn })
+
+      expect(replaceStateSpy).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('with default scroll behavior', () => {
+    it('does nothing when element is not found', () => {
+      scrollToAnchor('non-existent-id')
+
+      expect(scrollToSpy).not.toHaveBeenCalled()
+      expect(replaceStateSpy).not.toHaveBeenCalled()
+    })
+
+    it('scrolls to element with smooth behavior', () => {
+      scrollToAnchor('test-section')
+
+      expect(scrollToSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          behavior: 'smooth',
+        }),
+      )
+    })
+
+    it('calculates scroll position with header offset', () => {
+      scrollToAnchor('test-section')
+
+      // Verify scrollTo was called with a top property (exact value depends on element position)
+      expect(scrollToSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          top: expect.any(Number),
+        }),
+      )
+    })
+
+    it('updates URL hash by default', () => {
+      scrollToAnchor('test-section')
+
+      expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '#test-section')
+    })
+
+    it('does not update URL when updateUrl is false', () => {
+      scrollToAnchor('test-section', { updateUrl: false })
+
+      expect(scrollToSpy).toHaveBeenCalled()
+      expect(replaceStateSpy).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles empty id string without errors', () => {
+      expect(() => scrollToAnchor('')).not.toThrow()
+      expect(scrollToSpy).not.toHaveBeenCalled()
+    })
+
+    it('handles id with user-content prefix (GitHub-style anchors)', () => {
+      const userContentElement = document.createElement('div')
+      userContentElement.id = 'user-content-installation'
+      document.body.appendChild(userContentElement)
+
+      scrollToAnchor('user-content-installation')
+
+      expect(scrollToSpy).toHaveBeenCalled()
+      expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '#user-content-installation')
+
+      document.body.removeChild(userContentElement)
+    })
+  })
+})