diff --git a/app/pages/package/[[org]]/[name].vue b/app/pages/package/[[org]]/[name].vue
index 092071131..6990e3046 100644
--- a/app/pages/package/[[org]]/[name].vue
+++ b/app/pages/package/[[org]]/[name].vue
@@ -5,6 +5,7 @@ import type {
   PackumentVersion,
   ProvenanceDetails,
   ReadmeResponse,
+  ReadmeMarkdownResponse,
   SkillsListResponse,
 } from '#shared/types'
 import type { JsrPackageInfo } from '#shared/types/jsr'
@@ -106,15 +107,47 @@ const { data: readmeData } = useLazyFetch<ReadmeResponse>(
     const version = requestedVersion.value
     return version ? `${base}/v/${version}` : base
   },
-  { default: () => ({ html: '', md: '', playgroundLinks: [], toc: [] }) },
+  { default: () => ({ html: '', mdExists: false, playgroundLinks: [], toc: [] }) },
+)
+
+const {
+  data: readmeMarkdownData,
+  status: readmeMarkdownStatus,
+  execute: fetchReadmeMarkdown,
+} = useLazyFetch<ReadmeMarkdownResponse>(
+  () => {
+    const base = `/api/registry/readme/markdown/${packageName.value}`
+    const version = requestedVersion.value
+    return version ? `${base}/v/${version}` : base
+  },
+  {
+    server: false,
+    immediate: false,
+    default: () => ({}),
+  },
 )
 
 //copy README file as Markdown
 const { copied: copiedReadme, copy: copyReadme } = useClipboard({
-  source: () => readmeData.value?.md ?? '',
+  source: () => '',
   copiedDuring: 2000,
 })
 
+function prefetchReadmeMarkdown() {
+  if (readmeMarkdownStatus.value === 'idle') {
+    fetchReadmeMarkdown()
+  }
+}
+
+async function copyReadmeHandler() {
+  await fetchReadmeMarkdown()
+
+  const markdown = readmeMarkdownData.value?.markdown
+  if (!markdown) return
+
+  await copyReadme(markdown)
+}
+
 // Track active TOC item based on scroll position
 const tocItems = computed(() => readmeData.value?.toc ?? [])
 const { activeId: activeTocId } = useActiveTocItem(tocItems)
@@ -1238,12 +1271,14 @@ const showSkeleton = shallowRef(false)
           <div class="flex gap-2">
             <!-- Copy readme as Markdown button -->
             <TooltipApp
-              v-if="readmeData?.md"
+              v-if="readmeData?.mdExists"
               :text="$t('package.readme.copy_as_markdown')"
               position="bottom"
             >
               <ButtonBase
-                @click="copyReadme()"
+                @mouseenter="prefetchReadmeMarkdown"
+                @focus="prefetchReadmeMarkdown"
+                @click="copyReadmeHandler()"
                 :aria-pressed="copiedReadme"
                 :aria-label="
                   copiedReadme ? $t('common.copied') : $t('package.readme.copy_as_markdown')
diff --git a/server/api/registry/readme/[...pkg].get.ts b/server/api/registry/readme/[...pkg].get.ts
index ca64a55c0..c6f8e4ebd 100644
--- a/server/api/registry/readme/[...pkg].get.ts
+++ b/server/api/registry/readme/[...pkg].get.ts
@@ -1,50 +1,5 @@
-import * as v from 'valibot'
-import { PackageRouteParamsSchema } from '#shared/schemas/package'
-import {
-  CACHE_MAX_AGE_ONE_HOUR,
-  NPM_MISSING_README_SENTINEL,
-  ERROR_NPM_FETCH_FAILED,
-} from '#shared/utils/constants'
-
-/** Standard README filenames to try when fetching from jsdelivr (case-sensitive CDN) */
-const standardReadmeFilenames = [
-  'README.md',
-  'readme.md',
-  'Readme.md',
-  'README',
-  'readme',
-  'README.markdown',
-  'readme.markdown',
-]
-
-/** Matches standard README filenames (case-insensitive, for checking registry metadata) */
-const standardReadmePattern = /^readme(?:\.md|\.markdown)?$/i
-
-/**
- * Fetch README from jsdelivr CDN for a specific package version.
- * Falls back through common README filenames.
- */
-async function fetchReadmeFromJsdelivr(
-  packageName: string,
-  readmeFilenames: string[],
-  version?: string,
-): Promise<string | null> {
-  const versionSuffix = version ? `@${version}` : ''
-
-  for (const filename of readmeFilenames) {
-    try {
-      const url = `https://cdn.jsdelivr.net/npm/${packageName}${versionSuffix}/${filename}`
-      const response = await fetch(url)
-      if (response.ok) {
-        return await response.text()
-      }
-    } catch {
-      // Try next filename
-    }
-  }
-
-  return null
-}
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+import { resolvePackageReadmeSource } from '#server/utils/readme-loaders'
 
 /**
  * Returns rendered README HTML for a package.
@@ -57,63 +12,15 @@ async function fetchReadmeFromJsdelivr(
  */
 export default defineCachedEventHandler(
   async event => {
-    // Parse package name and optional version from URL segments
-    // Patterns: [pkg] or [pkg, 'v', version] or [@scope, pkg] or [@scope, pkg, 'v', version]
-    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
-
-    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
-
     try {
-      // 1. Validate
-      const { packageName, version } = v.parse(PackageRouteParamsSchema, {
-        packageName: rawPackageName,
-        version: rawVersion,
-      })
-
-      const packageData = await fetchNpmPackage(packageName)
+      const packagePath = getRouterParam(event, 'pkg') ?? ''
+      const { packageName, markdown, repoInfo } = await resolvePackageReadmeSource(packagePath)
 
-      let readmeContent: string | undefined
-      let readmeFilename: string | undefined
-
-      // If a specific version is requested, get README from that version
-      if (version) {
-        const versionData = packageData.versions[version]
-        if (versionData) {
-          readmeContent = versionData.readme
-          readmeFilename = versionData.readmeFilename
-        }
-      } else {
-        // Use the packument-level readme (from latest version)
-        readmeContent = packageData.readme
-        readmeFilename = packageData.readmeFilename
+      if (!markdown) {
+        return { html: '', mdExists: false, playgroundLinks: [], toc: [] }
       }
 
-      const hasValidNpmReadme = readmeContent && readmeContent !== NPM_MISSING_README_SENTINEL
-
-      // If no README in packument, or if readmeFilename is non-standard (e.g., README.zh-TW.md),
-      // try fetching a standard README from jsdelivr (package tarball).
-      // Note: When readmeFilename is missing, we defensively fetch from jsdelivr to ensure
-      // we get a standard English README if one exists.
-      if (!hasValidNpmReadme || !isStandardReadme(readmeFilename)) {
-        const jsdelivrReadme = await fetchReadmeFromJsdelivr(
-          packageName,
-          standardReadmeFilenames,
-          version,
-        )
-        // Only replace npm content if jsdelivr returned something
-        if (jsdelivrReadme) {
-          readmeContent = jsdelivrReadme
-        }
-      }
-
-      if (!readmeContent || readmeContent === NPM_MISSING_README_SENTINEL) {
-        return { html: '', playgroundLinks: [], toc: [] }
-      }
-
-      // Parse repository info for resolving relative URLs to GitHub
-      const repoInfo = parseRepositoryInfo(packageData.repository)
-
-      return await renderReadmeHtml(readmeContent, packageName, repoInfo)
+      return await renderReadmeHtml(markdown, packageName, repoInfo)
     } catch (error: unknown) {
       handleApiError(error, {
         statusCode: 502,
@@ -130,7 +37,3 @@ export default defineCachedEventHandler(
     },
   },
 )
-
-function isStandardReadme(filename: string | undefined): boolean {
-  return !!filename && standardReadmePattern.test(filename)
-}
diff --git a/server/api/registry/readme/markdown/[...pkg].get.ts b/server/api/registry/readme/markdown/[...pkg].get.ts
new file mode 100644
index 000000000..6e8690418
--- /dev/null
+++ b/server/api/registry/readme/markdown/[...pkg].get.ts
@@ -0,0 +1,15 @@
+import type { H3Event } from 'h3'
+import { ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+import { resolvePackageReadmeSource } from '#server/utils/readme-loaders'
+
+export default async function getMarkdownReadme(event: H3Event) {
+  try {
+    const packagePath = getRouterParam(event, 'pkg') ?? ''
+    return await resolvePackageReadmeSource(packagePath)
+  } catch (error: unknown) {
+    handleApiError(error, {
+      statusCode: 502,
+      message: ERROR_NPM_FETCH_FAILED,
+    })
+  }
+}
diff --git a/server/utils/readme-loaders.ts b/server/utils/readme-loaders.ts
new file mode 100644
index 000000000..8af25d7a9
--- /dev/null
+++ b/server/utils/readme-loaders.ts
@@ -0,0 +1,112 @@
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+import { CACHE_MAX_AGE_ONE_HOUR, NPM_MISSING_README_SENTINEL } from '#shared/utils/constants'
+
+/** Standard README filenames to try when fetching from jsdelivr (case-sensitive CDN) */
+const standardReadmeFilenames = [
+  'README.md',
+  'readme.md',
+  'Readme.md',
+  'README',
+  'readme',
+  'README.markdown',
+  'readme.markdown',
+]
+
+/** Matches standard README filenames (case-insensitive, for checking registry metadata) */
+const standardReadmePattern = /^readme(?:\.md|\.markdown)?$/i
+
+export function isStandardReadme(filename: string | undefined): boolean {
+  return !!filename && standardReadmePattern.test(filename)
+}
+
+/**
+ * Fetch README from jsdelivr CDN for a specific package version.
+ * Falls back through common README filenames.
+ */
+export async function fetchReadmeFromJsdelivr(
+  packageName: string,
+  readmeFilenames: string[],
+  version?: string,
+): Promise<string | null> {
+  const versionSuffix = version ? `@${version}` : ''
+
+  for (const filename of readmeFilenames) {
+    try {
+      const url = `https://cdn.jsdelivr.net/npm/${packageName}${versionSuffix}/${filename}`
+      const response = await fetch(url)
+      if (response.ok) {
+        return await response.text()
+      }
+    } catch {
+      // Try next filename
+    }
+  }
+
+  return null
+}
+
+export const resolvePackageReadmeSource = defineCachedFunction(
+  async (packagePath: string) => {
+    const pkgParamSegments = packagePath.split('/')
+
+    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
+
+    const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+      packageName: rawPackageName,
+      version: rawVersion,
+    })
+
+    const packageData = await fetchNpmPackage(packageName)
+
+    let readmeContent: string | undefined
+    let readmeFilename: string | undefined
+
+    if (version) {
+      const versionData = packageData.versions[version]
+      if (versionData) {
+        readmeContent = versionData.readme
+        readmeFilename = versionData.readmeFilename
+      }
+    } else {
+      readmeContent = packageData.readme
+      readmeFilename = packageData.readmeFilename
+    }
+
+    const hasValidNpmReadme = readmeContent && readmeContent !== NPM_MISSING_README_SENTINEL
+
+    if (!hasValidNpmReadme || !isStandardReadme(readmeFilename)) {
+      const jsdelivrReadme = await fetchReadmeFromJsdelivr(
+        packageName,
+        standardReadmeFilenames,
+        version,
+      )
+      if (jsdelivrReadme) {
+        readmeContent = jsdelivrReadme
+      }
+    }
+
+    if (!readmeContent || readmeContent === NPM_MISSING_README_SENTINEL) {
+      return {
+        packageName,
+        version,
+        markdown: undefined,
+        repoInfo: undefined,
+      }
+    }
+
+    const repoInfo = parseRepositoryInfo(packageData.repository)
+
+    return {
+      packageName,
+      version,
+      markdown: readmeContent,
+      repoInfo,
+    }
+  },
+  {
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
+    swr: true,
+    getKey: (packagePath: string) => packagePath,
+  },
+)
diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index 8f50a0350..441ade1d9 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -319,7 +319,7 @@ export async function renderReadmeHtml(
   packageName: string,
   repoInfo?: RepositoryInfo,
 ): Promise<ReadmeResponse> {
-  if (!content) return { html: '', md: '', playgroundLinks: [], toc: [] }
+  if (!content) return { html: '', playgroundLinks: [], toc: [] }
 
   const shiki = await getShikiHighlighter()
   const renderer = new marked.Renderer()
@@ -511,7 +511,7 @@ ${html}
 
   return {
     html: convertToEmoji(sanitized),
-    md: content,
+    mdExists: Boolean(content),
     playgroundLinks: collectedLinks,
     toc,
   }
diff --git a/shared/types/readme.ts b/shared/types/readme.ts
index 3e8c9607c..05657aa44 100644
--- a/shared/types/readme.ts
+++ b/shared/types/readme.ts
@@ -28,12 +28,17 @@ export interface TocItem {
  * Response from README API endpoint
  */
 export interface ReadmeResponse {
+  /** Whether the README exists */
+  mdExists?: boolean
   /** Rendered HTML content */
   html: string
-  /** Original markdown content */
-  md: string
   /** Extracted playground/demo links */
   playgroundLinks: PlaygroundLink[]
   /** Table of contents extracted from headings */
   toc: TocItem[]
 }
+
+export interface ReadmeMarkdownResponse {
+  /** Original markdown content */
+  markdown?: string
+}
diff --git a/test/unit/server/utils/readme-loaders.spec.ts b/test/unit/server/utils/readme-loaders.spec.ts
new file mode 100644
index 000000000..8fb2ce818
--- /dev/null
+++ b/test/unit/server/utils/readme-loaders.spec.ts
@@ -0,0 +1,238 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { parsePackageParams } from '../../../../server/utils/parse-package-params'
+import { NPM_MISSING_README_SENTINEL } from '#shared/utils/constants'
+
+// Mock Nitro globals before importing the module
+vi.stubGlobal('defineCachedFunction', (fn: Function) => fn)
+const $fetchMock = vi.fn()
+vi.stubGlobal('$fetch', $fetchMock)
+vi.stubGlobal('parsePackageParams', parsePackageParams)
+
+const fetchNpmPackageMock = vi.fn()
+vi.stubGlobal('fetchNpmPackage', fetchNpmPackageMock)
+
+const parseRepositoryInfoMock = vi.fn()
+vi.stubGlobal('parseRepositoryInfo', parseRepositoryInfoMock)
+
+const { fetchReadmeFromJsdelivr, isStandardReadme, resolvePackageReadmeSource } =
+  await import('../../../../server/utils/readme-loaders')
+
+describe('isStandardReadme', () => {
+  it('returns true for standard README filenames', () => {
+    expect(isStandardReadme('README.md')).toBe(true)
+    expect(isStandardReadme('readme.md')).toBe(true)
+    expect(isStandardReadme('Readme.md')).toBe(true)
+    expect(isStandardReadme('README')).toBe(true)
+    expect(isStandardReadme('readme')).toBe(true)
+    expect(isStandardReadme('README.markdown')).toBe(true)
+    expect(isStandardReadme('readme.markdown')).toBe(true)
+  })
+
+  it('returns false for non-standard filenames', () => {
+    expect(isStandardReadme('CONTRIBUTING.md')).toBe(false)
+    expect(isStandardReadme('README.txt')).toBe(false)
+    expect(isStandardReadme('readme.rst')).toBe(false)
+    expect(isStandardReadme(undefined)).toBe(false)
+    expect(isStandardReadme('')).toBe(false)
+  })
+})
+
+describe('fetchReadmeFromJsdelivr', () => {
+  it('returns content when first filename succeeds', async () => {
+    const content = '# Package'
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => content,
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await fetchReadmeFromJsdelivr('some-pkg', ['README.md'])
+
+    expect(result).toBe(content)
+    expect(fetchMock).toHaveBeenCalledWith('https://cdn.jsdelivr.net/npm/some-pkg/README.md')
+  })
+
+  it('includes version in URL when version is passed', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => '',
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await fetchReadmeFromJsdelivr('pkg', ['README.md'], '1.2.3')
+
+    expect(fetchMock).toHaveBeenCalledWith('https://cdn.jsdelivr.net/npm/pkg@1.2.3/README.md')
+  })
+
+  it('returns null when all fetches fail', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: false })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await fetchReadmeFromJsdelivr('pkg', ['README.md', 'readme.md'])
+
+    expect(result).toBeNull()
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('resolvePackageReadmeSource', () => {
+  beforeEach(() => {
+    fetchNpmPackageMock.mockReset()
+    parseRepositoryInfoMock.mockReset()
+  })
+
+  it('returns markdown and repoInfo when package has valid npm readme (latest)', async () => {
+    const markdown = '# Hello'
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: markdown,
+      readmeFilename: 'README.md',
+      repository: { url: 'https://github.com/u/r' },
+      versions: {},
+    })
+    parseRepositoryInfoMock.mockReturnValue({
+      provider: 'github',
+      owner: 'u',
+      repo: 'r',
+      rawBaseUrl: 'https://raw.githubusercontent.com/u/r/HEAD',
+      blobBaseUrl: 'https://github.com/u/r/blob/HEAD',
+    })
+
+    const result = await resolvePackageReadmeSource('some-pkg')
+
+    expect(result).toMatchObject({
+      packageName: 'some-pkg',
+      version: undefined,
+      markdown,
+      repoInfo: { provider: 'github', owner: 'u', repo: 'r' },
+    })
+    expect(fetchNpmPackageMock).toHaveBeenCalledWith('some-pkg')
+  })
+
+  it('returns markdown from version when packagePath includes version', async () => {
+    const markdown = '# Version readme'
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: 'latest readme',
+      readmeFilename: 'README.md',
+      repository: undefined,
+      versions: {
+        '1.0.0': { readme: markdown, readmeFilename: 'README.md' },
+      },
+    })
+    parseRepositoryInfoMock.mockReturnValue(undefined)
+
+    const result = await resolvePackageReadmeSource('some-pkg/v/1.0.0')
+
+    expect(result).toMatchObject({
+      packageName: 'some-pkg',
+      version: '1.0.0',
+      markdown,
+    })
+  })
+
+  it('falls back to jsdelivr when npm readme is missing sentinel', async () => {
+    const jsdelivrContent = '# From CDN'
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: NPM_MISSING_README_SENTINEL,
+      readmeFilename: 'README.md',
+      repository: undefined,
+      versions: {},
+    })
+    parseRepositoryInfoMock.mockReturnValue(undefined)
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => jsdelivrContent,
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await resolvePackageReadmeSource('pkg')
+
+    expect(result).toMatchObject({
+      packageName: 'pkg',
+      markdown: jsdelivrContent,
+      repoInfo: undefined,
+    })
+    expect(fetchMock).toHaveBeenCalled()
+  })
+
+  it('falls back to jsdelivr when readmeFilename is not standard', async () => {
+    const jsdelivrContent = '# From CDN'
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: 'content',
+      readmeFilename: 'DOCS.md',
+      repository: undefined,
+      versions: {},
+    })
+    parseRepositoryInfoMock.mockReturnValue(undefined)
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => jsdelivrContent,
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await resolvePackageReadmeSource('pkg')
+
+    expect(result).toMatchObject({ markdown: jsdelivrContent })
+  })
+
+  it('returns undefined markdown when no content and jsdelivr fails', async () => {
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: undefined,
+      readmeFilename: undefined,
+      repository: undefined,
+      versions: {},
+    })
+    parseRepositoryInfoMock.mockReturnValue(undefined)
+    const fetchMock = vi.fn().mockResolvedValue({ ok: false })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await resolvePackageReadmeSource('pkg')
+
+    expect(result).toMatchObject({
+      packageName: 'pkg',
+      version: undefined,
+      markdown: undefined,
+      repoInfo: undefined,
+    })
+  })
+
+  it('returns undefined markdown when content is NPM_MISSING_README_SENTINEL and jsdelivr fails', async () => {
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: NPM_MISSING_README_SENTINEL,
+      readmeFilename: 'README.md',
+      repository: undefined,
+      versions: {},
+    })
+    const fetchMock = vi.fn().mockResolvedValue({ ok: false })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await resolvePackageReadmeSource('pkg')
+
+    expect(result).toMatchObject({
+      packageName: 'pkg',
+      markdown: undefined,
+      repoInfo: undefined,
+    })
+  })
+
+  it('uses package repository for repoInfo when markdown is present', async () => {
+    fetchNpmPackageMock.mockResolvedValue({
+      readme: '# Hi',
+      readmeFilename: 'README.md',
+      repository: { url: 'https://github.com/a/b' },
+      versions: {},
+    })
+    const repoInfo = {
+      provider: 'github' as const,
+      owner: 'a',
+      repo: 'b',
+      rawBaseUrl: 'https://raw.githubusercontent.com/a/b/HEAD',
+      blobBaseUrl: 'https://github.com/a/b/blob/HEAD',
+    }
+    parseRepositoryInfoMock.mockReturnValue(repoInfo)
+
+    const result = await resolvePackageReadmeSource('pkg')
+
+    expect(result?.repoInfo).toEqual(repoInfo)
+    expect(parseRepositoryInfoMock).toHaveBeenCalledWith({ url: 'https://github.com/a/b' })
+  })
+})
diff --git a/test/unit/server/utils/readme.spec.ts b/test/unit/server/utils/readme.spec.ts
index cc580d929..08db45be2 100644
--- a/test/unit/server/utils/readme.spec.ts
+++ b/test/unit/server/utils/readme.spec.ts
@@ -331,23 +331,52 @@ describe('Markdown File URL Resolution', () => {
   })
 })
 
-describe('Markdown Content Extraction', () => {
-  describe('Markdown', () => {
-    it('returns original markdown content unchanged', async () => {
-      const markdown = `# Title\n\nSome **bold** text and a [link](https://example.com).`
-      const result = await renderReadmeHtml(markdown, 'test-pkg')
+describe('ReadmeResponse shape (HTML route contract)', () => {
+  it('returns ReadmeResponse with html, mdExists, playgroundLinks, toc', async () => {
+    const markdown = `# Title\n\nSome **bold** text.`
+    const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+    expect(result).toMatchObject({
+      html: expect.any(String),
+      mdExists: true,
+      playgroundLinks: [],
+      toc: expect.any(Array),
+    })
+    expect(result.html).toContain('Title')
+    expect(result.html).toContain('bold')
+  })
+
+  it('returns empty-state shape when content is empty', async () => {
+    const result = await renderReadmeHtml('', 'test-pkg')
 
-      expect(result.md).toBe(markdown)
+    expect(result).toMatchObject({
+      html: '',
+      playgroundLinks: [],
+      toc: [],
     })
+    expect(result.playgroundLinks).toHaveLength(0)
+    expect(result.toc).toHaveLength(0)
   })
-  describe('HTML', () => {
-    it('returns sanitized html', async () => {
-      const markdown = `# Title\n\nSome **bold** text and a [link](https://example.com).`
-      const result = await renderReadmeHtml(markdown, 'test-pkg')
 
-      expect(result.html).toBe(`<h3 id="user-content-title" data-level="1">Title</h3>
+  it('extracts toc from headings', async () => {
+    const markdown = `# Install\n\n## CLI\n\n## API`
+    const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+    expect(result.toc).toHaveLength(3)
+    expect(result.toc[0]).toMatchObject({ text: 'Install', depth: 1 })
+    expect(result.toc[1]).toMatchObject({ text: 'CLI', depth: 2 })
+    expect(result.toc[2]).toMatchObject({ text: 'API', depth: 2 })
+    expect(result.toc.every(t => t.id.startsWith('user-content-'))).toBe(true)
+  })
+})
+
+describe('HTML output', () => {
+  it('returns sanitized html', async () => {
+    const markdown = `# Title\n\nSome **bold** text and a [link](https://example.com).`
+    const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+    expect(result.html).toBe(`<h3 id="user-content-title" data-level="1">Title</h3>
 <p>Some <strong>bold</strong> text and a <a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">link</a>.</p>
 `)
-    })
   })
 })