From 57c6bd98d130c4f9cfac94685fd1d8cfe85e6338 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Fri, 27 Feb 2026 19:51:25 -0500
Subject: [PATCH] feat: add per-entrypoint API docs pages for multi-export
 packages

Packages with only subpath exports (no root export) previously got no
docs because esm.sh returns 404 for their root URL. Fix by falling back
to the npm registry  field to discover typed subpath entries.

Additionally, multi-entrypoint packages now get separate docs pages per
subpath with an EntrypointSelector dropdown, instead of dumping all
symbols into one flat page. The base URL redirects to the first
entrypoint.

URL structure: /package-docs/{pkg}/v/{version}/{entrypoint}

Closes #1479
---
 app/components/EntrypointSelector.vue      |  28 ++
 app/pages/package-docs/[...path].vue       |  54 ++-
 i18n/locales/en.json                       |   3 +-
 i18n/locales/fr-FR.json                    |   3 +-
 server/api/registry/docs/[...pkg].get.ts   |  35 +-
 server/utils/docs/client.ts                | 114 +++++-
 server/utils/docs/index.ts                 |  43 ++-
 shared/types/docs.ts                       |   4 +
 test/unit/a11y-component-coverage.spec.ts  |   1 +
 test/unit/server/utils/docs/client.spec.ts | 405 +++++++++++++++++++++
 test/unit/server/utils/docs/index.spec.ts  | 123 +++++++
 11 files changed, 782 insertions(+), 31 deletions(-)
 create mode 100644 app/components/EntrypointSelector.vue
 create mode 100644 test/unit/server/utils/docs/client.spec.ts
 create mode 100644 test/unit/server/utils/docs/index.spec.ts

diff --git a/app/components/EntrypointSelector.vue b/app/components/EntrypointSelector.vue
new file mode 100644
index 0000000000..243b71613a
--- /dev/null
+++ b/app/components/EntrypointSelector.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+const props = defineProps<{
+  packageName: string
+  version: string
+  currentEntrypoint: string
+  entrypoints: string[]
+}>()
+
+function getEntrypointUrl(entrypoint: string): string {
+  return `/package-docs/${props.packageName}/v/${props.version}/${entrypoint}`
+}
+
+function onSelect(event: Event) {
+  const target = event.target as HTMLSelectElement
+  navigateTo(getEntrypointUrl(target.value))
+}
+</script>
+
+<template>
+  <select
+    :value="currentEntrypoint"
+    :aria-label="$t('package.docs.select_entrypoint')"
+    class="text-fg-subtle font-mono text-sm bg-transparent border border-border rounded px-2 py-1 hover:text-fg hover:border-border-subtle transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring shrink-0"
+    @change="onSelect"
+  >
+    <option v-for="ep in entrypoints" :key="ep" :value="ep">./{{ ep }}</option>
+  </select>
+</template>
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index 31aba3bd52..7558661aed 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -20,17 +20,26 @@ const parsedRoute = computed(() => {
     return {
       packageName: segments.join('/'),
       version: null as string | null,
+      entrypoint: null as string | null,
     }
   }
 
+  // Version is the segment right after "v"
+  const version = segments[vIndex + 1]!
+  // Everything after the version is the entrypoint path (e.g., "router.js")
+  const entrypointSegments = segments.slice(vIndex + 2)
+  const entrypoint = entrypointSegments.length > 0 ? entrypointSegments.join('/') : null
+
   return {
     packageName: segments.slice(0, vIndex).join('/'),
-    version: segments.slice(vIndex + 1).join('/'),
+    version,
+    entrypoint,
   }
 })
 
 const packageName = computed(() => parsedRoute.value.packageName)
 const requestedVersion = computed(() => parsedRoute.value.version)
+const entrypoint = computed(() => parsedRoute.value.entrypoint)
 
 // Validate package name on server-side for early error detection
 if (import.meta.server && packageName.value) {
@@ -90,7 +99,8 @@ useCommandPalettePackageCommands(commandPalettePackageContext)
 
 const docsUrl = computed(() => {
   if (!packageName.value || !resolvedVersion.value) return null
-  return `/api/registry/docs/${packageName.value}/v/${resolvedVersion.value}`
+  const base = `/api/registry/docs/${packageName.value}/v/${resolvedVersion.value}`
+  return entrypoint.value ? `${base}/${entrypoint.value}` : base
 })
 
 const shouldFetch = computed(() => !!docsUrl.value)
@@ -119,9 +129,10 @@ const latestVersionDetailed = computed(() => {
   return pkg.value.versions[latestTag] ?? null
 })
 
-const versionUrlPattern = computed(
-  () => `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`,
-)
+const versionUrlPattern = computed(() => {
+  const base = `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`
+  return entrypoint.value ? `${base}/${entrypoint.value}` : base
+})
 
 useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
 
@@ -159,6 +170,27 @@ const stickyStyle = computed(() => {
     '--combined-header-height': `${56 + (packageHeaderHeight.value || 44)}px`,
   }
 })
+
+// Multi-entrypoint support
+const entrypoints = computed(() => docsData.value?.entrypoints ?? null)
+const currentEntrypoint = computed(() => docsData.value?.entrypoint ?? entrypoint.value ?? '')
+
+// Redirect to first entrypoint for multi-entrypoint packages
+watch(docsData, data => {
+  if (data?.entrypoints?.length && !entrypoint.value && resolvedVersion.value) {
+    const firstEntrypoint = data.entrypoints[0]!
+    const pathSegments = [
+      ...packageName.value.split('/'),
+      'v',
+      resolvedVersion.value,
+      ...firstEntrypoint.split('/'),
+    ]
+    router.replace({
+      name: 'docs',
+      params: { path: pathSegments as [string, ...string[]] },
+    })
+  }
+})
 </script>
 
 <template>
@@ -172,6 +204,18 @@ const stickyStyle = computed(() => {
       page="docs"
     />
 
+    <div
+      v-if="entrypoints && currentEntrypoint && resolvedVersion"
+      class="container py-2 border-b border-border"
+    >
+      <EntrypointSelector
+        :package-name="packageName"
+        :version="resolvedVersion"
+        :current-entrypoint="currentEntrypoint"
+        :entrypoints="entrypoints"
+      />
+    </div>
+
     <div class="flex" dir="ltr">
       <!-- Sidebar TOC -->
       <aside
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index ac8f7ffd3f..cc0ac0364a 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -448,7 +448,8 @@
       "page_title_name": "{name} docs - npmx",
       "page_title_version": "{name} docs - npmx",
       "og_title": "{name} - Docs",
-      "view_package": "View package"
+      "view_package": "View package",
+      "select_entrypoint": "Select entrypoint"
     },
     "get_started": {
       "title": "Get started",
diff --git a/i18n/locales/fr-FR.json b/i18n/locales/fr-FR.json
index c5a37f2f48..096b204d3f 100644
--- a/i18n/locales/fr-FR.json
+++ b/i18n/locales/fr-FR.json
@@ -445,7 +445,8 @@
       "page_title_name": "Documentation {name} - npmx",
       "page_title_version": "Documentation {name} - npmx",
       "og_title": "{name} - Documentation",
-      "view_package": "Voir le paquet"
+      "view_package": "Voir le paquet",
+      "select_entrypoint": "Sélectionner le point d'entrée"
     },
     "get_started": {
       "title": "Commencer",
diff --git a/server/api/registry/docs/[...pkg].get.ts b/server/api/registry/docs/[...pkg].get.ts
index 1ef86cd578..67da03aa2f 100644
--- a/server/api/registry/docs/[...pkg].get.ts
+++ b/server/api/registry/docs/[...pkg].get.ts
@@ -1,3 +1,8 @@
+import type { DocsResponse } from '#shared/types'
+import { assertValidPackageName } from '#shared/utils/npm'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
+import { generateDocsWithDeno, getEntrypoints } from '#server/utils/docs'
+
 export default defineCachedEventHandler(
   async event => {
     const pkgParam = getRouterParam(event, 'pkg')
@@ -6,7 +11,7 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package name is required' })
     }
 
-    const { packageName, version } = parsePackageParam(pkgParam)
+    const { packageName, version, rest } = parsePackageParam(pkgParam)
 
     if (!packageName) {
       // TODO: throwing 404 rather than 400 as it's cacheable
@@ -19,9 +24,30 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package version is required' })
     }
 
+    // Extract entrypoint from remaining path segments (e.g., ["router.js"] -> "router.js")
+    const entrypoint = rest.length > 0 ? rest.join('/') : undefined
+
+    // Discover available entrypoints (null for single-entrypoint packages)
+    const entrypoints = await getEntrypoints(packageName, version)
+    const entrypointFields = entrypoints ? { entrypoints, entrypoint } : {}
+
+    // If multi-entrypoint but no specific entrypoint requested, return early
+    // with the entrypoints list so the client can redirect to the first one
+    if (entrypoints && !entrypoint) {
+      return {
+        package: packageName,
+        version,
+        html: '',
+        toc: null,
+        status: 'ok',
+        entrypoints,
+        entrypoint: entrypoints[0],
+      } satisfies DocsResponse
+    }
+
     let generated
     try {
-      generated = await generateDocsWithDeno(packageName, version)
+      generated = await generateDocsWithDeno(packageName, version, entrypoint)
     } catch (error) {
       // eslint-disable-next-line no-console
       console.error(`Doc generation failed for ${packageName}@${version}:`, error)
@@ -32,6 +58,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'error',
         message: 'Failed to generate documentation. Please try again later.',
+        ...entrypointFields,
       } satisfies DocsResponse
     }
 
@@ -43,6 +70,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'missing',
         message: 'Docs are not available for this package. It may not have TypeScript types.',
+        ...entrypointFields,
       } satisfies DocsResponse
     }
 
@@ -52,6 +80,7 @@ export default defineCachedEventHandler(
       html: generated.html,
       toc: generated.toc,
       status: 'ok',
+      ...entrypointFields,
     } satisfies DocsResponse
   },
   {
@@ -59,7 +88,7 @@ export default defineCachedEventHandler(
     swr: true,
     getKey: event => {
       const pkg = getRouterParam(event, 'pkg') ?? ''
-      return `docs:v2:${pkg}`
+      return `docs:v3:${pkg}`
     },
   },
 )
diff --git a/server/utils/docs/client.ts b/server/utils/docs/client.ts
index dc3f78d1b1..d87e7d5c84 100644
--- a/server/utils/docs/client.ts
+++ b/server/utils/docs/client.ts
@@ -10,6 +10,7 @@
 import { doc, type DocNode } from '@deno/doc'
 import type { DenoDocNode, DenoDocResult } from '#shared/types/deno-doc'
 import { isBuiltin } from 'node:module'
+import { encodePackageName } from '#shared/utils/npm'
 
 // =============================================================================
 // Configuration
@@ -18,6 +19,9 @@ import { isBuiltin } from 'node:module'
 /** Timeout for fetching modules in milliseconds */
 const FETCH_TIMEOUT_MS = 30 * 1000
 
+/** Maximum number of subpath exports to process */
+const MAX_SUBPATH_EXPORTS = 20
+
 // =============================================================================
 // Main Export
 // =============================================================================
@@ -26,17 +30,23 @@ const FETCH_TIMEOUT_MS = 30 * 1000
  * Get documentation nodes for a package using @deno/doc WASM.
  */
 export async function getDocNodes(packageName: string, version: string): Promise<DenoDocResult> {
-  // Get types URL from esm.sh header
-  const typesUrl = await getTypesUrl(packageName, version)
+  // Get types URL from esm.sh header for the root entry
+  const typesUrls = await getTypesUrls(packageName, version)
+  return runDoc(typesUrls)
+}
 
-  if (!typesUrl) {
+/**
+ * Run @deno/doc on a list of types URLs and collect all resulting nodes.
+ */
+async function runDoc(typesUrls: string[]): Promise<DenoDocResult> {
+  if (typesUrls.length === 0) {
     return { version: 1, nodes: [] }
   }
 
   // Generate docs using @deno/doc WASM
   let result: Record<string, DocNode[]>
   try {
-    result = await doc([typesUrl], {
+    result = await doc(typesUrls, {
       load: createLoader(),
       resolve: createResolver(),
     })
@@ -153,6 +163,43 @@ function createResolver(): (specifier: string, referrer: string) => string {
   }
 }
 
+/**
+ * Get TypeScript types URLs for a package, trying the root entry first,
+ * then falling back to subpath exports if the package has no default export.
+ */
+async function getTypesUrls(packageName: string, version: string): Promise<string[]> {
+  // Try root entry first
+  const rootTypesUrl = await getTypesUrlForSubpath(packageName, version)
+  if (rootTypesUrl) {
+    return [rootTypesUrl]
+  }
+
+  // Root has no types — check subpath exports from the npm registry
+  const subpaths = await getSubpathExports(packageName, version)
+  if (subpaths.length === 0) {
+    return []
+  }
+
+  // Fetch types URLs for each subpath export in parallel
+  const results = await Promise.all(
+    subpaths.map(subpath => getTypesUrlForSubpath(packageName, version, subpath)),
+  )
+
+  return results.filter((url): url is string => url !== null)
+}
+
+/**
+ * Get documentation nodes for a specific subpath export of a package.
+ */
+export async function getDocNodesForEntrypoint(
+  packageName: string,
+  version: string,
+  entrypoint: string,
+): Promise<DenoDocResult> {
+  const typesUrl = await getTypesUrlForSubpath(packageName, version, entrypoint)
+  return runDoc(typesUrl ? [typesUrl] : [])
+}
+
 /**
  * Get the TypeScript types URL from esm.sh's x-typescript-types header.
  *
@@ -160,8 +207,14 @@ function createResolver(): (specifier: string, referrer: string) => string {
  * Example: curl -sI 'https://esm.sh/ufo@1.5.0' returns header:
  *   x-typescript-types: https://esm.sh/ufo@1.5.0/dist/index.d.ts
  */
-async function getTypesUrl(packageName: string, version: string): Promise<string | null> {
-  const url = `https://esm.sh/${packageName}@${version}`
+export async function getTypesUrlForSubpath(
+  packageName: string,
+  version: string,
+  subpath?: string,
+): Promise<string | null> {
+  const url = subpath
+    ? `https://esm.sh/${packageName}@${version}/${subpath}`
+    : `https://esm.sh/${packageName}@${version}`
 
   try {
     const response = await $fetch.raw(url, {
@@ -169,9 +222,52 @@ async function getTypesUrl(packageName: string, version: string): Promise<string
       timeout: FETCH_TIMEOUT_MS,
     })
     return response.headers.get('x-typescript-types')
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error(e)
+  } catch {
     return null
   }
 }
+
+/**
+ * Get subpath export paths from the npm registry's package.json `exports` field.
+ * Only returns subpaths that declare types (have a `types` condition).
+ *
+ * Skips the root export (".") since that's handled by the main getTypesUrl call.
+ * Skips wildcard patterns ("./foo/*") since they can't be resolved to specific files.
+ */
+export async function getSubpathExports(packageName: string, version: string): Promise<string[]> {
+  try {
+    const encodedName = encodePackageName(packageName)
+    const pkgJson = await $fetch<Record<string, unknown>>(
+      `https://registry.npmjs.org/${encodedName}/${version}`,
+      { timeout: FETCH_TIMEOUT_MS },
+    )
+
+    const exports = pkgJson.exports
+    if (!exports || typeof exports !== 'object') {
+      return []
+    }
+
+    const subpaths: string[] = []
+
+    for (const [key, value] of Object.entries(exports as Record<string, unknown>)) {
+      // Skip root export (already tried), non-subpath entries, and wildcards
+      if (key === '.' || !key.startsWith('./') || key.includes('*')) {
+        continue
+      }
+
+      // Only include exports that declare types
+      if (value && typeof value === 'object' && 'types' in value) {
+        // Strip leading "./" for the esm.sh URL
+        subpaths.push(key.slice(2))
+      }
+
+      if (subpaths.length >= MAX_SUBPATH_EXPORTS) {
+        break
+      }
+    }
+
+    return subpaths
+  } catch {
+    return []
+  }
+}
diff --git a/server/utils/docs/index.ts b/server/utils/docs/index.ts
index 66a7394489..aec71aaf8a 100644
--- a/server/utils/docs/index.ts
+++ b/server/utils/docs/index.ts
@@ -9,34 +9,34 @@
  */
 
 import type { DocsGenerationResult } from '#shared/types/deno-doc'
-import { getDocNodes } from './client'
+import {
+  getDocNodes,
+  getDocNodesForEntrypoint,
+  getSubpathExports,
+  getTypesUrlForSubpath,
+} from './client'
 import { buildSymbolLookup, flattenNamespaces, mergeOverloads } from './processing'
 import { renderDocNodes, renderToc } from './render'
 
 /**
- * Generate API documentation for an npm package.
+ * Generate API documentation for an npm package (or a specific entrypoint).
  *
  * Uses @deno/doc (WASM build of deno_doc) with esm.sh URLs to extract
  * TypeScript type information and JSDoc comments, then renders them as HTML.
  *
  * @param packageName - The npm package name (e.g., "react", "@types/lodash")
  * @param version - The package version (e.g., "19.2.3")
+ * @param entrypoint - Optional subpath export (e.g., "router.js") for multi-entrypoint packages
  * @returns Generated documentation or null if no types are available
- *
- * @example
- * ```ts
- * const docs = await generateDocsWithDeno('ufo', '1.5.0')
- * if (docs) {
- *   console.log(docs.html)
- * }
- * ```
  */
 export async function generateDocsWithDeno(
   packageName: string,
   version: string,
+  entrypoint?: string,
 ): Promise<DocsGenerationResult | null> {
-  // Get doc nodes using @deno/doc WASM
-  const result = await getDocNodes(packageName, version)
+  const result = entrypoint
+    ? await getDocNodesForEntrypoint(packageName, version, entrypoint)
+    : await getDocNodes(packageName, version)
 
   if (!result.nodes || result.nodes.length === 0) {
     return null
@@ -53,3 +53,22 @@ export async function generateDocsWithDeno(
 
   return { html, toc, nodes: flattenedNodes }
 }
+
+/**
+ * Get the list of subpath exports for a package, or null if it's a
+ * single-entrypoint package (has a root export with types).
+ */
+export async function getEntrypoints(
+  packageName: string,
+  version: string,
+): Promise<string[] | null> {
+  // Check if root entry has types
+  const rootTypesUrl = await getTypesUrlForSubpath(packageName, version)
+  if (rootTypesUrl) {
+    return null
+  }
+
+  // Multi-entrypoint: return subpath exports
+  const subpaths = await getSubpathExports(packageName, version)
+  return subpaths.length > 0 ? subpaths : null
+}
diff --git a/shared/types/docs.ts b/shared/types/docs.ts
index a59164f811..db884abdf3 100644
--- a/shared/types/docs.ts
+++ b/shared/types/docs.ts
@@ -8,6 +8,10 @@ export interface DocsResponse {
   breadcrumbs?: string | null
   status: DocsStatus
   message?: string
+  /** Available entrypoints for multi-entrypoint packages. Absent for single-entrypoint packages. */
+  entrypoints?: string[]
+  /** The current entrypoint being viewed. Absent for single-entrypoint packages. */
+  entrypoint?: string
 }
 
 export interface DocsSearchResponse {
diff --git a/test/unit/a11y-component-coverage.spec.ts b/test/unit/a11y-component-coverage.spec.ts
index 1029590fd1..eac06c1cc4 100644
--- a/test/unit/a11y-component-coverage.spec.ts
+++ b/test/unit/a11y-component-coverage.spec.ts
@@ -52,6 +52,7 @@ const SKIPPED_COMPONENTS: Record<string, string> = {
   'SkeletonInline.vue': 'Already covered indirectly via other component tests',
   'Button/Group.vue': "Wrapper component, tests wouldn't make much sense here",
   'Translation/StatusByFile.unused.vue': 'Unused component, might be needed in the future',
+  'EntrypointSelector.vue': 'Simple native <select> wrapper - minimal a11y surface',
 }
 
 function normalizeComponentPath(filePath: string): string {
diff --git a/test/unit/server/utils/docs/client.spec.ts b/test/unit/server/utils/docs/client.spec.ts
new file mode 100644
index 0000000000..9b01c9ce08
--- /dev/null
+++ b/test/unit/server/utils/docs/client.spec.ts
@@ -0,0 +1,405 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock @deno/doc
+const docMock = vi.fn()
+vi.mock('@deno/doc', () => ({
+  doc: (...args: unknown[]) => docMock(...args),
+}))
+
+// Mock encodePackageName
+vi.mock('#shared/utils/npm', () => ({
+  encodePackageName: (name: string) => name.replace('/', '%2f'),
+}))
+
+// Mock Nitro globals before importing the module.
+// $fetch.raw() is used for esm.sh HEAD requests, $fetch() directly for npm registry GETs.
+const $fetchRawMock = vi.fn()
+const $fetchMock = Object.assign(vi.fn(), { raw: $fetchRawMock })
+vi.stubGlobal('$fetch', $fetchMock)
+
+const { getDocNodes, getDocNodesForEntrypoint, getSubpathExports } =
+  await import('../../../../../server/utils/docs/client')
+
+/**
+ * Helper to mock esm.sh HEAD responses ($fetch.raw) and npm registry GETs ($fetch).
+ *
+ * @param headMap - Maps esm.sh URLs to their x-typescript-types header value.
+ *   `string` = types URL returned in header, `null` = 200 with no types header,
+ *   key absent = 404 (throws).
+ * @param registryResponse - Response for npm registry GET calls
+ */
+function setupMocks(
+  headMap: Record<string, string | null>,
+  registryResponse?: Record<string, unknown>,
+) {
+  $fetchRawMock.mockImplementation(async (url: string) => {
+    const typesUrl = headMap[url]
+    if (typesUrl === undefined) {
+      throw new Error(`404 Not Found: ${url}`)
+    }
+    return {
+      headers: new Headers(typesUrl ? { 'x-typescript-types': typesUrl } : {}),
+    }
+  })
+
+  $fetchMock.mockImplementation(async (url: string) => {
+    if (url.startsWith('https://registry.npmjs.org/') && registryResponse) {
+      return registryResponse
+    }
+    throw new Error(`Unexpected $fetch call: ${url}`)
+  })
+}
+
+describe('docs/client - getDocNodes', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('root entry (standard packages)', () => {
+    it('returns doc nodes when root entry has types', async () => {
+      const typesUrl = 'https://esm.sh/ufo@1.5.0/dist/index.d.ts'
+      setupMocks({ 'https://esm.sh/ufo@1.5.0': typesUrl })
+
+      const mockNodes = [{ name: 'parseURL', kind: 'function' }]
+      docMock.mockResolvedValue({ [typesUrl]: mockNodes })
+
+      const result = await getDocNodes('ufo', '1.5.0')
+
+      expect(result.nodes).toEqual(mockNodes)
+      expect(docMock).toHaveBeenCalledWith(
+        [typesUrl],
+        expect.objectContaining({ load: expect.any(Function), resolve: expect.any(Function) }),
+      )
+    })
+
+    it('returns empty nodes when root has no x-typescript-types header', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': null }, { exports: undefined })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when esm.sh HEAD request fails', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when @deno/doc throws', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': 'https://esm.sh/pkg@1.0.0/index.d.ts' })
+      docMock.mockRejectedValue(new Error('WASM error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('collects nodes from multiple specifiers in doc result', async () => {
+      const typesUrl = 'https://esm.sh/pkg@1.0.0/index.d.ts'
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': typesUrl })
+
+      const reExportedUrl = 'https://esm.sh/pkg@1.0.0/types.d.ts'
+      docMock.mockResolvedValue({
+        [typesUrl]: [{ name: 'foo', kind: 'function' }],
+        [reExportedUrl]: [{ name: 'Bar', kind: 'interface' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(2)
+      expect(result.nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: 'foo' }),
+          expect.objectContaining({ name: 'Bar' }),
+        ]),
+      )
+    })
+  })
+
+  describe('subpath exports fallback', () => {
+    it('falls back to subpath exports when root returns 404', async () => {
+      const routerTypesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/router/index.d.ts'
+      const apiTypesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/api/index.d.ts'
+
+      setupMocks(
+        {
+          'https://esm.sh/@thepassle/app-tools@0.10.2/router.js': routerTypesUrl,
+          'https://esm.sh/@thepassle/app-tools@0.10.2/api.js': apiTypesUrl,
+        },
+        {
+          exports: {
+            './router.js': { types: './types/router/index.d.ts', default: './router.js' },
+            './api.js': { types: './types/api/index.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [routerTypesUrl]: [{ name: 'Router', kind: 'class' }],
+        [apiTypesUrl]: [{ name: 'createApi', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('@thepassle/app-tools', '0.10.2')
+
+      expect(result.nodes).toHaveLength(2)
+      expect(docMock).toHaveBeenCalledWith(
+        expect.arrayContaining([routerTypesUrl, apiTypesUrl]),
+        expect.any(Object),
+      )
+    })
+
+    it('skips wildcard exports', async () => {
+      const stateTypesUrl = 'https://esm.sh/pkg@1.0.0/types/state/index.d.ts'
+
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/state.js': stateTypesUrl,
+        },
+        {
+          exports: {
+            './utils/*': { types: './types/utils/*', default: './utils/*' },
+            './state.js': { types: './types/state/index.d.ts', default: './state.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [stateTypesUrl]: [{ name: 'createState', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(docMock).toHaveBeenCalledWith([stateTypesUrl], expect.any(Object))
+    })
+
+    it('skips root export "." in subpath processing', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0': null,
+          'https://esm.sh/pkg@1.0.0/sub.js': 'https://esm.sh/pkg@1.0.0/sub.d.ts',
+        },
+        {
+          exports: {
+            '.': { types: './index.d.ts', default: './index.js' },
+            './sub.js': { types: './sub.d.ts', default: './sub.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        'https://esm.sh/pkg@1.0.0/sub.d.ts': [{ name: 'sub', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      // Root was called once (initial attempt), sub.js was called once (fallback)
+      const headUrls = $fetchRawMock.mock.calls.map((call: unknown[]) => call[0])
+      expect(headUrls).toEqual(['https://esm.sh/pkg@1.0.0', 'https://esm.sh/pkg@1.0.0/sub.js'])
+    })
+
+    it('skips exports without types condition', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/typed.js': 'https://esm.sh/pkg@1.0.0/typed.d.ts',
+        },
+        {
+          exports: {
+            './no-types.js': { default: './no-types.js' },
+            './typed.js': { types: './typed.d.ts', default: './typed.js' },
+            './package.json': './package.json',
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        'https://esm.sh/pkg@1.0.0/typed.d.ts': [{ name: 'typed', kind: 'variable' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(result.nodes[0]!.name).toBe('typed')
+    })
+
+    it('returns empty when no subpath exports have types on esm.sh', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/sub.js': null,
+        },
+        {
+          exports: {
+            './sub.js': { types: './sub.d.ts', default: './sub.js' },
+          },
+        },
+      )
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty when package has no exports field', async () => {
+      setupMocks({}, { name: 'pkg', version: '1.0.0' })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('returns empty when npm registry request fails', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('handles partial subpath failures gracefully', async () => {
+      const apiTypesUrl = 'https://esm.sh/pkg@1.0.0/api.d.ts'
+
+      setupMocks(
+        {
+          // router fails (key absent = throws)
+          'https://esm.sh/pkg@1.0.0/api.js': apiTypesUrl,
+        },
+        {
+          exports: {
+            './router.js': { types: './router.d.ts', default: './router.js' },
+            './api.js': { types: './api.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [apiTypesUrl]: [{ name: 'createApi', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(result.nodes[0]!.name).toBe('createApi')
+    })
+
+    it('encodes scoped package names for npm registry', async () => {
+      setupMocks({}, { exports: {} })
+
+      await getDocNodes('@scope/pkg', '1.0.0')
+
+      const registryCall = $fetchMock.mock.calls.find(
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].startsWith('https://registry.npmjs.org/'),
+      )
+      expect(registryCall).toBeDefined()
+      expect(registryCall![0]).toBe('https://registry.npmjs.org/@scope%2fpkg/1.0.0')
+    })
+  })
+
+  describe('getDocNodesForEntrypoint', () => {
+    it('returns doc nodes for a specific entrypoint', async () => {
+      const typesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/router/index.d.ts'
+      setupMocks({
+        'https://esm.sh/@thepassle/app-tools@0.10.2/router.js': typesUrl,
+      })
+
+      const mockNodes = [{ name: 'Router', kind: 'class' }]
+      docMock.mockResolvedValue({ [typesUrl]: mockNodes })
+
+      const result = await getDocNodesForEntrypoint('@thepassle/app-tools', '0.10.2', 'router.js')
+
+      expect(result.nodes).toEqual(mockNodes)
+      expect(docMock).toHaveBeenCalledWith([typesUrl], expect.any(Object))
+    })
+
+    it('returns empty nodes when entrypoint has no types', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0/sub.js': null })
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'sub.js')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when esm.sh fails for entrypoint', async () => {
+      setupMocks({})
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'missing.js')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('returns empty nodes when @deno/doc throws for entrypoint', async () => {
+      setupMocks({
+        'https://esm.sh/pkg@1.0.0/sub.js': 'https://esm.sh/pkg@1.0.0/sub.d.ts',
+      })
+      docMock.mockRejectedValue(new Error('WASM error'))
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'sub.js')
+
+      expect(result.nodes).toEqual([])
+    })
+  })
+
+  describe('getSubpathExports', () => {
+    it('returns subpath exports with types condition', async () => {
+      setupMocks(
+        {},
+        {
+          exports: {
+            './router.js': { types: './types/router/index.d.ts', default: './router.js' },
+            './api.js': { types: './types/api/index.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual(['router.js', 'api.js'])
+    })
+
+    it('skips root export, wildcards, and non-typed exports', async () => {
+      setupMocks(
+        {},
+        {
+          exports: {
+            '.': { types: './index.d.ts', default: './index.js' },
+            './utils/*': { types: './types/utils/*', default: './utils/*' },
+            './no-types.js': { default: './no-types.js' },
+            './typed.js': { types: './typed.d.ts', default: './typed.js' },
+            './package.json': './package.json',
+          },
+        },
+      )
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual(['typed.js'])
+    })
+
+    it('returns empty array when no exports field', async () => {
+      setupMocks({}, { name: 'pkg' })
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual([])
+    })
+
+    it('returns empty array on registry error', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual([])
+    })
+  })
+})
diff --git a/test/unit/server/utils/docs/index.spec.ts b/test/unit/server/utils/docs/index.spec.ts
new file mode 100644
index 0000000000..746ace8e16
--- /dev/null
+++ b/test/unit/server/utils/docs/index.spec.ts
@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock client module
+const getDocNodesMock = vi.fn()
+const getDocNodesForEntrypointMock = vi.fn()
+const getSubpathExportsMock = vi.fn()
+const getTypesUrlForSubpathMock = vi.fn()
+
+vi.mock('../../../../../server/utils/docs/client', () => ({
+  getDocNodes: (...args: unknown[]) => getDocNodesMock(...args),
+  getDocNodesForEntrypoint: (...args: unknown[]) => getDocNodesForEntrypointMock(...args),
+  getSubpathExports: (...args: unknown[]) => getSubpathExportsMock(...args),
+  getTypesUrlForSubpath: (...args: unknown[]) => getTypesUrlForSubpathMock(...args),
+}))
+
+// Mock processing module
+vi.mock('../../../../../server/utils/docs/processing', () => ({
+  flattenNamespaces: (nodes: unknown[]) => nodes,
+  mergeOverloads: (nodes: unknown[]) => nodes,
+  buildSymbolLookup: () => new Map(),
+}))
+
+// Mock render module
+vi.mock('../../../../../server/utils/docs/render', () => ({
+  renderDocNodes: async () => '<div>docs</div>',
+  renderToc: () => '<nav>toc</nav>',
+}))
+
+const { generateDocsWithDeno, getEntrypoints } =
+  await import('../../../../../server/utils/docs/index')
+
+describe('docs/index', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('getEntrypoints', () => {
+    it('returns null for single-entrypoint packages (root has types)', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue('https://esm.sh/ufo@1.5.0/dist/index.d.ts')
+
+      const result = await getEntrypoints('ufo', '1.5.0')
+
+      expect(result).toBeNull()
+      expect(getTypesUrlForSubpathMock).toHaveBeenCalledWith('ufo', '1.5.0')
+      expect(getSubpathExportsMock).not.toHaveBeenCalled()
+    })
+
+    it('returns subpath exports when root has no types', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue(null)
+      getSubpathExportsMock.mockResolvedValue(['router.js', 'api.js'])
+
+      const result = await getEntrypoints('@thepassle/app-tools', '0.10.2')
+
+      expect(result).toEqual(['router.js', 'api.js'])
+      expect(getSubpathExportsMock).toHaveBeenCalledWith('@thepassle/app-tools', '0.10.2')
+    })
+
+    it('returns null when root has no types and no subpath exports', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue(null)
+      getSubpathExportsMock.mockResolvedValue([])
+
+      const result = await getEntrypoints('pkg', '1.0.0')
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('generateDocsWithDeno', () => {
+    it('calls getDocNodes for packages without entrypoint', async () => {
+      getDocNodesMock.mockResolvedValue({
+        version: 1,
+        nodes: [{ name: 'foo', kind: 'function' }],
+      })
+
+      const result = await generateDocsWithDeno('ufo', '1.5.0')
+
+      expect(getDocNodesMock).toHaveBeenCalledWith('ufo', '1.5.0')
+      expect(getDocNodesForEntrypointMock).not.toHaveBeenCalled()
+      expect(result).toEqual({
+        html: '<div>docs</div>',
+        toc: '<nav>toc</nav>',
+        nodes: [{ name: 'foo', kind: 'function' }],
+      })
+    })
+
+    it('calls getDocNodesForEntrypoint when entrypoint is specified', async () => {
+      getDocNodesForEntrypointMock.mockResolvedValue({
+        version: 1,
+        nodes: [{ name: 'Router', kind: 'class' }],
+      })
+
+      const result = await generateDocsWithDeno('@thepassle/app-tools', '0.10.2', 'router.js')
+
+      expect(getDocNodesForEntrypointMock).toHaveBeenCalledWith(
+        '@thepassle/app-tools',
+        '0.10.2',
+        'router.js',
+      )
+      expect(getDocNodesMock).not.toHaveBeenCalled()
+      expect(result).toEqual({
+        html: '<div>docs</div>',
+        toc: '<nav>toc</nav>',
+        nodes: [{ name: 'Router', kind: 'class' }],
+      })
+    })
+
+    it('returns null when no doc nodes are found', async () => {
+      getDocNodesMock.mockResolvedValue({ version: 1, nodes: [] })
+
+      const result = await generateDocsWithDeno('pkg', '1.0.0')
+
+      expect(result).toBeNull()
+    })
+
+    it('returns null when entrypoint has no doc nodes', async () => {
+      getDocNodesForEntrypointMock.mockResolvedValue({ version: 1, nodes: [] })
+
+      const result = await generateDocsWithDeno('pkg', '1.0.0', 'missing.js')
+
+      expect(result).toBeNull()
+    })
+  })
+})