From 7099e4b6585d9fa05e06e9e30dcfcb543f16c1c4 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.stories.ts  |  80 ++++++
 app/components/EntrypointSelector.vue         |  64 +++++
 app/composables/useCommandPaletteCommands.ts  |   5 +
 .../useCommandPaletteEntrypointCommands.ts    |  51 ++++
 app/pages/package-docs/[...path].vue          |  83 ++++--
 app/types/command-palette.ts                  |   1 +
 app/utils/router.ts                           |  22 +-
 i18n/locales/en.json                          |  11 +-
 i18n/locales/fr-FR.json                       |  11 +-
 i18n/schema.json                              |  21 ++
 server/api/registry/docs/[...pkg].get.ts      |  48 +++-
 server/utils/docs/client.ts                   | 160 ++++++++++-
 server/utils/docs/index.ts                    |  49 +++-
 shared/types/docs.ts                          |   4 +
 test/nuxt/a11y.spec.ts                        |  29 ++
 .../components/EntrypointSelector.spec.ts     |  68 +++++
 test/nuxt/components/VersionSelector.spec.ts  |   5 -
 .../server/api/registry/docs/pkg.get.spec.ts  | 222 +++++++++++++++
 test/unit/server/utils/docs/client.spec.ts    | 263 ++++++++++++++++++
 test/unit/server/utils/docs/index.spec.ts     | 129 +++++++++
 20 files changed, 1270 insertions(+), 56 deletions(-)
 create mode 100644 app/components/EntrypointSelector.stories.ts
 create mode 100644 app/components/EntrypointSelector.vue
 create mode 100644 app/composables/useCommandPaletteEntrypointCommands.ts
 create mode 100644 test/nuxt/components/EntrypointSelector.spec.ts
 create mode 100644 test/unit/server/api/registry/docs/pkg.get.spec.ts
 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.stories.ts b/app/components/EntrypointSelector.stories.ts
new file mode 100644
index 0000000000..830746c170
--- /dev/null
+++ b/app/components/EntrypointSelector.stories.ts
@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import EntrypointSelector from './EntrypointSelector.vue'
+
+const meta = {
+  component: EntrypointSelector,
+} satisfies Meta<typeof EntrypointSelector>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const SingleEntrypoint: Story = {
+  args: {
+    packageName: 'vue',
+    version: '3.5.0',
+    currentEntrypoint: '.',
+    entrypoints: ['.'],
+  },
+}
+
+export const MultipleEntrypoints: Story = {
+  args: {
+    packageName: '@nuxt/kit',
+    version: '4.3.1',
+    currentEntrypoint: '.',
+    entrypoints: ['.', 'compatibility', 'loader'],
+  },
+}
+
+export const ManyEntrypoints: Story = {
+  args: {
+    packageName: '@radix-ui/themes',
+    version: '3.0.0',
+    currentEntrypoint: 'button',
+    entrypoints: [
+      'accordion',
+      'alert-dialog',
+      'avatar',
+      'badge',
+      'box',
+      'button',
+      'callout',
+      'card',
+      'checkbox',
+      'container',
+      'dialog',
+      'flex',
+      'grid',
+      'heading',
+      'icon-button',
+      'inset',
+      'link',
+      'popover',
+      'progress',
+      'radio-group',
+      'scroll-area',
+      'select',
+      'separator',
+      'skeleton',
+      'slider',
+      'spinner',
+      'switch',
+      'table',
+      'tabs',
+      'text',
+      'text-area',
+      'text-field',
+      'theme',
+      'tooltip',
+    ],
+  },
+}
+
+export const NestedEntrypoint: Story = {
+  args: {
+    packageName: '@nuxt/kit',
+    version: '4.3.1',
+    currentEntrypoint: 'compat/utils',
+    entrypoints: ['.', 'compat/utils', 'compat/legacy'],
+  },
+}
diff --git a/app/components/EntrypointSelector.vue b/app/components/EntrypointSelector.vue
new file mode 100644
index 0000000000..1a97dc62d5
--- /dev/null
+++ b/app/components/EntrypointSelector.vue
@@ -0,0 +1,64 @@
+<script setup lang="ts">
+const props = defineProps<{
+  packageName: string
+  version: string
+  currentEntrypoint: string
+  entrypoints: string[]
+}>()
+
+const hasMultiple = computed(() => props.entrypoints.length > 1)
+const selectId = useId()
+
+const selectedEntrypoint = shallowRef(props.currentEntrypoint)
+
+watch(
+  () => props.currentEntrypoint,
+  entrypoint => {
+    selectedEntrypoint.value = entrypoint
+  },
+)
+
+const entrypointItems = computed(() =>
+  props.entrypoints.map(entrypoint => ({
+    value: entrypoint,
+    label: formatEntrypointLabel(entrypoint),
+  })),
+)
+
+function formatEntrypointLabel(entrypoint: string): string {
+  return entrypoint === '.' ? '.' : `./${entrypoint}`
+}
+
+function handleEntrypointChange(entrypoint: string | undefined) {
+  if (!entrypoint || entrypoint === props.currentEntrypoint) {
+    return
+  }
+
+  selectedEntrypoint.value = entrypoint
+  navigateTo(docsRoute(props.packageName, props.version, entrypoint))
+}
+</script>
+
+<template>
+  <div
+    v-if="!hasMultiple"
+    class="text-fg-subtle font-mono text-sm inline-flex items-center gap-1.5"
+  >
+    <span class="i-lucide:package w-3.5 h-3.5" aria-hidden="true" />
+    <span dir="ltr">{{ formatEntrypointLabel(currentEntrypoint) }}</span>
+  </div>
+
+  <div v-else class="inline-flex items-center gap-1.5">
+    <span class="i-lucide:package w-3.5 h-3.5 text-fg-subtle shrink-0" aria-hidden="true" />
+    <SelectField
+      :id="selectId"
+      v-model="selectedEntrypoint"
+      :items="entrypointItems"
+      :label="$t('package.docs.select_entrypoint')"
+      hidden-label
+      size="sm"
+      :select-attrs="{ dir: 'ltr' }"
+      @update:model-value="handleEntrypointChange"
+    />
+  </div>
+</template>
diff --git a/app/composables/useCommandPaletteCommands.ts b/app/composables/useCommandPaletteCommands.ts
index 9c07149131..d52212d227 100644
--- a/app/composables/useCommandPaletteCommands.ts
+++ b/app/composables/useCommandPaletteCommands.ts
@@ -17,6 +17,7 @@ const GROUP_ORDER: CommandPaletteGroup[] = [
   'settings',
   'help',
   'npmx',
+  'entrypoints',
   'versions',
 ]
 
@@ -68,6 +69,10 @@ export function useCommandPaletteCommands() {
         return packageName
           ? t('command_palette.groups.versions_with_name', { name: packageName })
           : t('command_palette.groups.versions')
+      case 'entrypoints':
+        return packageName
+          ? t('command_palette.groups.entrypoints_with_name', { name: packageName })
+          : t('command_palette.groups.entrypoints')
     }
   }
 
diff --git a/app/composables/useCommandPaletteEntrypointCommands.ts b/app/composables/useCommandPaletteEntrypointCommands.ts
new file mode 100644
index 0000000000..3c3a337b6f
--- /dev/null
+++ b/app/composables/useCommandPaletteEntrypointCommands.ts
@@ -0,0 +1,51 @@
+// @unocss-include
+import type { MaybeRefOrGetter } from 'vue'
+import type {
+  CommandPaletteContextCommandInput,
+  CommandPalettePackageContext,
+} from '~/types/command-palette'
+
+interface EntrypointContext {
+  packageContext: CommandPalettePackageContext
+  entrypoints: string[]
+  currentEntrypoint: string | null
+}
+
+function getEntrypointLabel(entrypoint: string): string {
+  return entrypoint === '.' ? '.' : `./${entrypoint}`
+}
+
+export function useCommandPaletteEntrypointCommands(
+  context: MaybeRefOrGetter<EntrypointContext | null>,
+) {
+  const { t } = useI18n()
+
+  useCommandPaletteContextCommands(
+    computed((): CommandPaletteContextCommandInput[] => {
+      const ctx = toValue(context)
+      if (!ctx?.packageContext.resolvedVersion) return []
+      if (ctx.entrypoints.length === 0) return []
+
+      return ctx.entrypoints.map(entrypoint => ({
+        id: `entrypoint:${entrypoint}`,
+        group: 'entrypoints' as const,
+        label: t('command_palette.entrypoint.label', {
+          entrypoint: getEntrypointLabel(entrypoint),
+        }),
+        keywords: [
+          ctx.packageContext.packageName,
+          entrypoint,
+          getEntrypointLabel(entrypoint),
+          t('command_palette.groups.entrypoints'),
+        ],
+        iconClass: 'i-lucide:package',
+        active: entrypoint === ctx.currentEntrypoint,
+        to: docsRoute(
+          ctx.packageContext.packageName,
+          ctx.packageContext.resolvedVersion!,
+          entrypoint,
+        ),
+      }))
+    }),
+  )
+}
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index d07a3d023d..ee8bf85fa4 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { setResponseHeader } from 'h3'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
 
 definePageMeta({
   name: 'docs',
@@ -13,24 +14,19 @@ const router = useRouter()
 const { t } = useI18n()
 
 const parsedRoute = computed(() => {
-  const segments = route.params.path?.filter(Boolean)
-  const vIndex = segments.indexOf('v')
-
-  if (vIndex === -1 || vIndex >= segments.length - 1) {
-    return {
-      packageName: segments.join('/'),
-      version: null as string | null,
-    }
-  }
+  const rawPath = route.params.path?.filter(Boolean).join('/') ?? ''
+  const { packageName, version, rest } = parsePackageParam(rawPath)
 
   return {
-    packageName: segments.slice(0, vIndex).join('/'),
-    version: segments.slice(vIndex + 1).join('/'),
+    packageName,
+    version: version ?? null,
+    entrypoint: rest.length > 0 ? rest.join('/') : null,
   }
 })
 
 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) {
@@ -48,12 +44,8 @@ if (import.meta.server && !requestedVersion.value && packageName.value) {
   const version = await fetchLatestVersion(packageName.value)
   if (version) {
     setResponseHeader(useRequestEvent()!, 'Cache-Control', 'no-cache')
-    const pathSegments = [...packageName.value.split('/'), 'v', version]
     app.runWithContext(() =>
-      navigateTo(
-        { name: 'docs', params: { path: pathSegments as [string, ...string[]] } },
-        { redirectCode: 302 },
-      ),
+      navigateTo(docsRoute(packageName.value, version), { redirectCode: 302 }),
     )
   }
 }
@@ -62,8 +54,7 @@ watch(
   [requestedVersion, latestVersion, packageName],
   ([version, latest, name]) => {
     if (!version && latest && name) {
-      const pathSegments = [...name.split('/'), 'v', latest]
-      router.replace({ name: 'docs', params: { path: pathSegments as [string, ...string[]] } })
+      router.replace(docsRoute(name, latest))
     }
   },
   { immediate: true },
@@ -90,7 +81,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 +111,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 && entrypoint.value !== '.' ? `${base}/${entrypoint.value}` : base
+})
 
 useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
 
@@ -171,6 +164,39 @@ const stickyStyle = computed(() => {
     '--combined-header-height': `${56 + (packageHeaderHeight.value || 44)}px`,
   }
 })
+
+// Multi-entrypoint support
+const entrypoints = computed(() => docsData.value?.entrypoints ?? null)
+const hasRootEntrypoint = computed(() => entrypoints.value?.includes('.') ?? false)
+const currentEntrypoint = computed(
+  () => docsData.value?.entrypoint ?? entrypoint.value ?? (hasRootEntrypoint.value ? '.' : ''),
+)
+
+// Redirect to first entrypoint for multi-entrypoint packages
+watch(docsData, data => {
+  if (
+    data?.entrypoints?.length &&
+    !data.entrypoints.includes('.') &&
+    !entrypoint.value &&
+    resolvedVersion.value
+  ) {
+    const firstEntrypoint = data.entrypoints[0]!
+    router.replace(docsRoute(packageName.value, resolvedVersion.value, firstEntrypoint))
+  }
+})
+
+useCommandPaletteEntrypointCommands(
+  computed(() => {
+    const packageContext = commandPalettePackageContext.value
+    const allEntrypoints = entrypoints.value
+    if (!packageContext || !allEntrypoints?.length || allEntrypoints.length < 2) return null
+    return {
+      packageContext,
+      entrypoints: allEntrypoints,
+      currentEntrypoint: currentEntrypoint.value || null,
+    }
+  }),
+)
 </script>
 
 <template>
@@ -184,6 +210,19 @@ const stickyStyle = computed(() => {
       page="docs"
     />
 
+    <nav
+      v-if="entrypoints?.length && currentEntrypoint && resolvedVersion"
+      :aria-label="$t('package.docs.entrypoints')"
+      class="container py-2 border-b border-border"
+    >
+      <EntrypointSelector
+        :package-name="packageName"
+        :version="resolvedVersion"
+        :current-entrypoint="currentEntrypoint"
+        :entrypoints="entrypoints"
+      />
+    </nav>
+
     <div class="flex" dir="ltr">
       <!-- Sidebar TOC -->
       <aside
diff --git a/app/types/command-palette.ts b/app/types/command-palette.ts
index 656cb03356..70f4496d3c 100644
--- a/app/types/command-palette.ts
+++ b/app/types/command-palette.ts
@@ -11,6 +11,7 @@ export type CommandPaletteGroup =
   | 'settings'
   | 'npmx'
   | 'versions'
+  | 'entrypoints'
 
 export type CommandPaletteView = 'root' | 'languages' | 'accent-colors' | 'background-themes'
 
diff --git a/app/utils/router.ts b/app/utils/router.ts
index ac3c9a46a6..ef0d841c49 100644
--- a/app/utils/router.ts
+++ b/app/utils/router.ts
@@ -32,7 +32,7 @@ export function packageRoute(
 
 /** Full version history page (`/package/.../versions`) */
 export function packageVersionsRoute(packageName: string): RouteLocationRaw {
-  const [org, name = ''] = packageName.startsWith('@') ? packageName.split('/') : ['', packageName]
+  const { org, name } = splitPackageName(packageName)
   return { name: 'package-versions', params: { org, name } }
 }
 
@@ -52,3 +52,23 @@ export function diffRoute(
     },
   }
 }
+
+export function docsRoute(
+  packageName: string,
+  version: string,
+  entrypoint?: string | null,
+): RouteLocationRaw {
+  const { org, name } = splitPackageName(packageName)
+  const pathSegments = [...(org ? [org, name] : [name]), 'v', version]
+
+  if (entrypoint && entrypoint !== '.') {
+    pathSegments.push(...entrypoint.split('/'))
+  }
+
+  return {
+    name: 'docs',
+    params: {
+      path: pathSegments as [string, ...string[]],
+    },
+  }
+}
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index 6851ed5511..7839d3e075 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -113,7 +113,9 @@
       "package": "Package",
       "package_with_name": "Package ({name})",
       "versions": "Versions",
-      "versions_with_name": "Versions of {name}"
+      "versions_with_name": "Versions of {name}",
+      "entrypoints": "Entrypoints",
+      "entrypoints_with_name": "Entrypoints of {name}"
     },
     "actions": {
       "search": "Search",
@@ -168,6 +170,9 @@
     "version": {
       "label": "{version}"
     },
+    "entrypoint": {
+      "label": "{entrypoint}"
+    },
     "status": {
       "available_in_context": "{context}. No commands available | {context}. 1 command available | {context}. {count} commands available",
       "matching_in_context": "{context}. No matching commands | {context}. 1 matching command | {context}. {count} matching commands",
@@ -462,7 +467,9 @@
       "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",
+      "entrypoints": "Package entrypoints"
     },
     "get_started": {
       "title": "Get started",
diff --git a/i18n/locales/fr-FR.json b/i18n/locales/fr-FR.json
index 0e40fa415b..e0d67cef53 100644
--- a/i18n/locales/fr-FR.json
+++ b/i18n/locales/fr-FR.json
@@ -110,7 +110,9 @@
       "package": "Paquet",
       "package_with_name": "Paquet ({name})",
       "versions": "Versions",
-      "versions_with_name": "Versions de {name}"
+      "versions_with_name": "Versions de {name}",
+      "entrypoints": "Points d'entrée",
+      "entrypoints_with_name": "Points d'entrée de {name}"
     },
     "actions": {
       "search": "Recherche",
@@ -165,6 +167,9 @@
     "version": {
       "label": "{version}"
     },
+    "entrypoint": {
+      "label": "{entrypoint}"
+    },
     "status": {
       "available_in_context": "{context}. Aucune commande disponible | {context}. 1 commande disponible | {context}. {count} commandes disponibles",
       "matching_in_context": "{context}. Aucune commande correspondante | {context}. 1 commande correspondante | {context}. {count} commandes correspondantes",
@@ -450,7 +455,9 @@
       "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",
+      "entrypoints": "Points d'entrée du paquet"
     },
     "get_started": {
       "title": "Commencer",
diff --git a/i18n/schema.json b/i18n/schema.json
index 7b6a3b3945..e29a83c2fd 100644
--- a/i18n/schema.json
+++ b/i18n/schema.json
@@ -345,6 +345,12 @@
             },
             "versions_with_name": {
               "type": "string"
+            },
+            "entrypoints": {
+              "type": "string"
+            },
+            "entrypoints_with_name": {
+              "type": "string"
             }
           },
           "additionalProperties": false
@@ -508,6 +514,15 @@
           },
           "additionalProperties": false
         },
+        "entrypoint": {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
         "status": {
           "type": "object",
           "properties": {
@@ -1392,6 +1407,12 @@
             },
             "view_package": {
               "type": "string"
+            },
+            "select_entrypoint": {
+              "type": "string"
+            },
+            "entrypoints": {
+              "type": "string"
             }
           },
           "additionalProperties": false
diff --git a/server/api/registry/docs/[...pkg].get.ts b/server/api/registry/docs/[...pkg].get.ts
index 1ef86cd578..20a7326426 100644
--- a/server/api/registry/docs/[...pkg].get.ts
+++ b/server/api/registry/docs/[...pkg].get.ts
@@ -1,3 +1,9 @@
+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'
+import type { DocsFetch } from '#server/utils/docs/client'
+
 export default defineCachedEventHandler(
   async event => {
     const pkgParam = getRouterParam(event, 'pkg')
@@ -6,7 +12,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 +25,42 @@ 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
+
+    // Wrap the request-scoped cached fetch (set by the cache module) when available;
+    // otherwise fall back to the global $fetch. Either way the doc helpers see one
+    // consistent DocsFetch contract.
+    const cachedFetch = event.context?.cachedFetch
+    const docsFetch: DocsFetch = cachedFetch
+      ? async (url, options) => (await cachedFetch(url, options)).data
+      : async (url, options) => await $fetch(url, options)
+
+    // Discover available entrypoints (null for single-entrypoint packages)
+    const entrypoints = await getEntrypoints(packageName, version, docsFetch)
+    const hasRootEntrypoint = entrypoints?.includes('.') ?? false
+    const requestedEntrypoint = entrypoint === '.' ? undefined : entrypoint
+    const currentEntrypoint =
+      requestedEntrypoint ?? (entrypoints && hasRootEntrypoint ? '.' : undefined)
+    const entrypointFields = entrypoints ? { entrypoints, entrypoint: currentEntrypoint } : {}
+
+    // If the package only has subpath entrypoints, return the list so the
+    // client can redirect to the first concrete entrypoint page.
+    if (entrypoints && !hasRootEntrypoint && !requestedEntrypoint) {
+      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, requestedEntrypoint, docsFetch)
     } catch (error) {
       // eslint-disable-next-line no-console
       console.error(`Doc generation failed for ${packageName}@${version}:`, error)
@@ -32,6 +71,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'error',
         message: 'Failed to generate documentation. Please try again later.',
+        ...entrypointFields,
       } satisfies DocsResponse
     }
 
@@ -43,6 +83,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 +93,7 @@ export default defineCachedEventHandler(
       html: generated.html,
       toc: generated.toc,
       status: 'ok',
+      ...entrypointFields,
     } satisfies DocsResponse
   },
   {
@@ -59,7 +101,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..d41eee610b 100644
--- a/server/utils/docs/client.ts
+++ b/server/utils/docs/client.ts
@@ -10,6 +10,8 @@
 import { doc, type DocNode } from '@deno/doc'
 import type { DenoDocNode, DenoDocResult } from '#shared/types/deno-doc'
 import { isBuiltin } from 'node:module'
+import { NPM_REGISTRY } from '#shared/utils/constants'
+import { encodePackageName } from '#shared/utils/npm'
 
 // =============================================================================
 // Configuration
@@ -18,6 +20,34 @@ 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
+
+/**
+ * Minimal fetch contract used by the docs pipeline. The docs module casts the
+ * response at use sites since responses come from external sources (npm registry,
+ * esm.sh) and have to be runtime-validated anyway.
+ *
+ * Kept non-generic on purpose: making this `<T>` triggers TS2321 "Excessive stack
+ * depth" when TypeScript checks assignability of any function involving `$fetch`
+ * (which carries a heavy route-map generic) against this type.
+ */
+export type DocsFetch = (url: string, options?: { timeout?: number }) => Promise<unknown>
+
+function hasTypesCondition(value: unknown): boolean {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  if (Array.isArray(value)) {
+    return value.some(item => hasTypesCondition(item))
+  }
+
+  return Object.entries(value).some(
+    ([key, nestedValue]) => key === 'types' || hasTypesCondition(nestedValue),
+  )
+}
+
 // =============================================================================
 // Main Export
 // =============================================================================
@@ -25,18 +55,28 @@ 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)
+export async function getDocNodes(
+  packageName: string,
+  version: string,
+  registryFetch: DocsFetch,
+): Promise<DenoDocResult> {
+  // Get types URL from esm.sh header for the root entry
+  const typesUrls = await getTypesUrls(packageName, version, registryFetch)
+  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 +193,47 @@ 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,
+  registryFetch: DocsFetch,
+): 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, registryFetch)
+  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 +241,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 +256,64 @@ async function getTypesUrl(packageName: string, version: string): Promise<string
       timeout: FETCH_TIMEOUT_MS,
     })
     return response.headers.get('x-typescript-types')
-  } catch (e) {
+  } catch (error) {
     // eslint-disable-next-line no-console
-    console.error(e)
+    console.error(error)
     return null
   }
 }
+
+async function fetchPackageManifest(
+  packageName: string,
+  version: string,
+  registryFetch: DocsFetch,
+): Promise<Record<string, unknown>> {
+  const encodedName = encodePackageName(packageName)
+  return (await registryFetch(`${NPM_REGISTRY}/${encodedName}/${version}`, {
+    timeout: FETCH_TIMEOUT_MS,
+  })) as Record<string, unknown>
+}
+
+/**
+ * Get subpath export paths from the npm registry's package.json `exports` field.
+ * Only returns subpaths that declare types, either directly or in nested conditions.
+ *
+ * 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,
+  registryFetch: DocsFetch,
+): Promise<string[]> {
+  try {
+    const pkgJson = await fetchPackageManifest(packageName, version, registryFetch)
+
+    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
+      }
+
+      if (hasTypesCondition(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..ce7f0bd584 100644
--- a/server/utils/docs/index.ts
+++ b/server/utils/docs/index.ts
@@ -9,34 +9,38 @@
  */
 
 import type { DocsGenerationResult } from '#shared/types/deno-doc'
-import { getDocNodes } from './client'
+import {
+  getDocNodes,
+  getDocNodesForEntrypoint,
+  getSubpathExports,
+  getTypesUrlForSubpath,
+  type DocsFetch,
+} 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
+ * @param registryFetch - Fetch function for npm registry calls (request-scoped, may be cached)
  * @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 | undefined,
+  registryFetch: DocsFetch,
 ): Promise<DocsGenerationResult | null> {
-  // Get doc nodes using @deno/doc WASM
-  const result = await getDocNodes(packageName, version)
+  const normalizedEntrypoint = entrypoint === '.' ? undefined : entrypoint
+  const result = normalizedEntrypoint
+    ? await getDocNodesForEntrypoint(packageName, version, normalizedEntrypoint)
+    : await getDocNodes(packageName, version, registryFetch)
 
   if (!result.nodes || result.nodes.length === 0) {
     return null
@@ -53,3 +57,24 @@ export async function generateDocsWithDeno(
 
   return { html, toc, nodes: flattenedNodes }
 }
+
+/**
+ * Get the list of docs entrypoints for a package. Returns `.` for the root
+ * entrypoint when the package has both root docs and typed subpath exports.
+ */
+export async function getEntrypoints(
+  packageName: string,
+  version: string,
+  registryFetch: DocsFetch,
+): Promise<string[] | null> {
+  const [rootTypesUrl, subpaths] = await Promise.all([
+    getTypesUrlForSubpath(packageName, version),
+    getSubpathExports(packageName, version, registryFetch),
+  ])
+
+  if (subpaths.length === 0) {
+    return null
+  }
+
+  return rootTypesUrl ? ['.', ...subpaths] : subpaths
+}
diff --git a/shared/types/docs.ts b/shared/types/docs.ts
index a59164f811..ffd5762de5 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 docs entrypoints. `.` denotes the package root entrypoint. */
+  entrypoints?: string[]
+  /** The current docs entrypoint being viewed. `.` denotes the package root entrypoint. */
+  entrypoint?: string
 }
 
 export interface DocsSearchResponse {
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
index 901c85e562..331c6d4491 100644
--- a/test/nuxt/a11y.spec.ts
+++ b/test/nuxt/a11y.spec.ts
@@ -236,6 +236,7 @@ import {
   TooltipAnnounce,
   TooltipApp,
   TooltipBase,
+  EntrypointSelector,
   UserAvatar,
   VersionSelector,
   ViewModeToggle,
@@ -3227,6 +3228,34 @@ describe('component accessibility audits', () => {
     })
   })
 
+  describe('EntrypointSelector', () => {
+    it('should have no accessibility violations with a single entrypoint (read-only)', async () => {
+      const component = await mountSuspended(EntrypointSelector, {
+        props: {
+          packageName: 'vue',
+          version: '3.5.0',
+          currentEntrypoint: '.',
+          entrypoints: ['.'],
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations with multiple entrypoints (closed)', async () => {
+      const component = await mountSuspended(EntrypointSelector, {
+        props: {
+          packageName: '@nuxt/kit',
+          version: '4.3.1',
+          currentEntrypoint: '.',
+          entrypoints: ['.', 'compatibility', 'loader'],
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+  })
+
   describe('VersionSelector', () => {
     const mockVersions = {
       '3.5.0': {},
diff --git a/test/nuxt/components/EntrypointSelector.spec.ts b/test/nuxt/components/EntrypointSelector.spec.ts
new file mode 100644
index 0000000000..10f5893b18
--- /dev/null
+++ b/test/nuxt/components/EntrypointSelector.spec.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import EntrypointSelector from '~/components/EntrypointSelector.vue'
+
+const baseProps = {
+  packageName: '@nuxt/kit',
+  version: '4.3.1',
+  currentEntrypoint: '.',
+  entrypoints: ['.', 'compatibility', 'loader'],
+}
+
+describe('EntrypointSelector', () => {
+  describe('single entrypoint', () => {
+    it('renders the path as text without a select', async () => {
+      const component = await mountSuspended(EntrypointSelector, {
+        props: { ...baseProps, currentEntrypoint: '.', entrypoints: ['.'] },
+      })
+
+      expect(component.find('select').exists()).toBe(false)
+      expect(component.text()).toContain('.')
+    })
+
+    it('formats non-root single entrypoints with the "./" prefix', async () => {
+      const component = await mountSuspended(EntrypointSelector, {
+        props: { ...baseProps, currentEntrypoint: 'client', entrypoints: ['client'] },
+      })
+
+      expect(component.text()).toContain('./client')
+    })
+  })
+
+  describe('multi-entrypoint select', () => {
+    it('renders a select with the current entrypoint selected', async () => {
+      const component = await mountSuspended(EntrypointSelector, { props: baseProps })
+      const select = component.get('select')
+
+      expect(select.element.value).toBe('.')
+      expect(component.findAll('option')).toHaveLength(3)
+    })
+
+    it('formats option labels with the root marker and "./" prefixes', async () => {
+      const component = await mountSuspended(EntrypointSelector, { props: baseProps })
+      const options = component.findAll('option')
+
+      expect(options[0]?.text()).toBe('.')
+      expect(options[1]?.text()).toBe('./compatibility')
+      expect(options[2]?.text()).toBe('./loader')
+    })
+
+    it('updates the selected option when the current entrypoint prop changes', async () => {
+      const component = await mountSuspended(EntrypointSelector, { props: baseProps })
+      const select = component.get('select')
+
+      await component.setProps({ currentEntrypoint: 'compatibility' })
+
+      expect(select.element.value).toBe('compatibility')
+    })
+
+    it('updates the displayed selection immediately when a new entrypoint is chosen', async () => {
+      const component = await mountSuspended(EntrypointSelector, { props: baseProps })
+      const select = component.get('select')
+
+      await select.setValue('compatibility')
+
+      expect(select.element.value).toBe('compatibility')
+    })
+  })
+})
diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index bbc259bdd0..a48be35011 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -9,14 +9,9 @@ vi.mock('~/utils/npm/api', () => ({
   fetchAllPackageVersions: (...args: unknown[]) => mockFetchAllPackageVersions(...args),
 }))
 
-// Mock navigateTo
-const mockNavigateTo = vi.fn()
-vi.stubGlobal('navigateTo', mockNavigateTo)
-
 describe('VersionSelector', () => {
   beforeEach(() => {
     mockFetchAllPackageVersions.mockReset()
-    mockNavigateTo.mockReset()
   })
 
   describe('basic rendering', () => {
diff --git a/test/unit/server/api/registry/docs/pkg.get.spec.ts b/test/unit/server/api/registry/docs/pkg.get.spec.ts
new file mode 100644
index 0000000000..de1b1859f5
--- /dev/null
+++ b/test/unit/server/api/registry/docs/pkg.get.spec.ts
@@ -0,0 +1,222 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createError, type H3Event } from 'h3'
+
+const getEntrypointsMock = vi.fn()
+const generateDocsWithDenoMock = vi.fn()
+const assertValidPackageNameMock = vi.fn()
+
+vi.mock('#server/utils/docs', () => ({
+  getEntrypoints: (...args: unknown[]) => getEntrypointsMock(...args),
+  generateDocsWithDeno: (...args: unknown[]) => generateDocsWithDenoMock(...args),
+}))
+
+vi.mock('#shared/utils/npm', () => ({
+  assertValidPackageName: (...args: unknown[]) => assertValidPackageNameMock(...args),
+}))
+
+vi.stubGlobal('defineCachedEventHandler', (fn: Function) => fn)
+
+let routerParam: string | undefined
+
+vi.stubGlobal('getRouterParam', (_event: unknown, _name: string) => routerParam)
+vi.stubGlobal('createError', createError)
+
+const handler = (await import('#server/api/registry/docs/[...pkg].get')).default
+
+const fakeEvent = { context: {} } as H3Event
+
+afterAll(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('docs API handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    routerParam = undefined
+  })
+
+  describe('happy paths', () => {
+    it('returns the first concrete entrypoint when the package has no root docs', async () => {
+      routerParam = 'pkg/v/1.0.0'
+      getEntrypointsMock.mockResolvedValue(['router.js', 'api.js'])
+
+      const result = await handler(fakeEvent)
+
+      // No doc generation happens — the client redirects to the first concrete entrypoint URL.
+      expect(generateDocsWithDenoMock).not.toHaveBeenCalled()
+      expect(result).toEqual({
+        package: 'pkg',
+        version: '1.0.0',
+        html: '',
+        toc: null,
+        status: 'ok',
+        entrypoints: ['router.js', 'api.js'],
+        entrypoint: 'router.js',
+      })
+    })
+
+    it('returns root docs when the package has both root and subpath entrypoints', async () => {
+      routerParam = 'vue/v/3.5.30'
+      getEntrypointsMock.mockResolvedValue(['.', 'server-renderer'])
+      generateDocsWithDenoMock.mockResolvedValue({
+        html: '<div>docs</div>',
+        toc: '<nav>toc</nav>',
+        nodes: [],
+      })
+
+      const result = await handler(fakeEvent)
+
+      expect(generateDocsWithDenoMock).toHaveBeenCalledWith(
+        'vue',
+        '3.5.30',
+        undefined,
+        expect.any(Function),
+      )
+      expect(result).toEqual({
+        package: 'vue',
+        version: '3.5.30',
+        html: '<div>docs</div>',
+        toc: '<nav>toc</nav>',
+        status: 'ok',
+        entrypoints: ['.', 'server-renderer'],
+        entrypoint: '.',
+      })
+    })
+
+    it('returns root docs without entrypoints metadata for single-entrypoint packages', async () => {
+      routerParam = 'ufo/v/1.5.0'
+      getEntrypointsMock.mockResolvedValue(null)
+      generateDocsWithDenoMock.mockResolvedValue({
+        html: '<div>ufo</div>',
+        toc: '<nav>toc</nav>',
+        nodes: [],
+      })
+
+      const result = await handler(fakeEvent)
+
+      expect(result).toEqual({
+        package: 'ufo',
+        version: '1.5.0',
+        html: '<div>ufo</div>',
+        toc: '<nav>toc</nav>',
+        status: 'ok',
+      })
+      // Critical: no `entrypoints` or `entrypoint` field — frontend uses presence of `entrypoints` to decide whether to render the selector.
+      expect(result).not.toHaveProperty('entrypoints')
+      expect(result).not.toHaveProperty('entrypoint')
+    })
+
+    it('normalizes the "." entrypoint to undefined for the root', async () => {
+      // The client may navigate to /package-docs/foo/v/1.0.0/. — the handler must treat this as the root.
+      routerParam = 'foo/v/1.0.0/.'
+      getEntrypointsMock.mockResolvedValue(['.', 'sub'])
+      generateDocsWithDenoMock.mockResolvedValue({ html: 'h', toc: 't', nodes: [] })
+
+      await handler(fakeEvent)
+
+      expect(generateDocsWithDenoMock).toHaveBeenCalledWith(
+        'foo',
+        '1.0.0',
+        undefined,
+        expect.any(Function),
+      )
+    })
+
+    it('passes a non-root entrypoint through unchanged', async () => {
+      routerParam = 'vue/v/3.5.30/server-renderer'
+      getEntrypointsMock.mockResolvedValue(['.', 'server-renderer'])
+      generateDocsWithDenoMock.mockResolvedValue({ html: 'h', toc: 't', nodes: [] })
+
+      const result = await handler(fakeEvent)
+
+      expect(generateDocsWithDenoMock).toHaveBeenCalledWith(
+        'vue',
+        '3.5.30',
+        'server-renderer',
+        expect.any(Function),
+      )
+      expect(result).toMatchObject({ entrypoint: 'server-renderer' })
+    })
+  })
+
+  describe('failure responses', () => {
+    it('returns status: "error" with a user-facing message when generation throws', async () => {
+      routerParam = 'broken/v/1.0.0'
+      getEntrypointsMock.mockResolvedValue(['.', 'sub'])
+      generateDocsWithDenoMock.mockRejectedValue(new Error('@deno/doc exploded'))
+      // Suppress expected console.error from the handler's catch branch.
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const result = await handler(fakeEvent)
+
+      expect(result).toMatchObject({
+        package: 'broken',
+        version: '1.0.0',
+        html: '',
+        toc: null,
+        status: 'error',
+        // Entrypoint metadata is preserved on error so the selector still renders.
+        entrypoints: ['.', 'sub'],
+        entrypoint: '.',
+      })
+      expect((result as { message?: string }).message).toBeTruthy()
+
+      consoleSpy.mockRestore()
+    })
+
+    it('returns status: "missing" when generation succeeds but produces no docs', async () => {
+      routerParam = 'no-types/v/1.0.0'
+      getEntrypointsMock.mockResolvedValue(null)
+      generateDocsWithDenoMock.mockResolvedValue(null)
+
+      const result = await handler(fakeEvent)
+
+      expect(result).toMatchObject({
+        package: 'no-types',
+        version: '1.0.0',
+        html: '',
+        toc: null,
+        status: 'missing',
+      })
+      expect((result as { message?: string }).message).toBeTruthy()
+    })
+
+    it('preserves entrypoint metadata in "missing" responses', async () => {
+      // A specific entrypoint of a multi-entrypoint package may have no types — selector still needs to render.
+      routerParam = 'pkg/v/1.0.0/empty'
+      getEntrypointsMock.mockResolvedValue(['.', 'empty'])
+      generateDocsWithDenoMock.mockResolvedValue(null)
+
+      const result = await handler(fakeEvent)
+
+      expect(result).toMatchObject({
+        status: 'missing',
+        entrypoints: ['.', 'empty'],
+        entrypoint: 'empty',
+      })
+    })
+  })
+
+  describe('input validation', () => {
+    it('throws 404 when the package param is missing entirely', async () => {
+      routerParam = undefined
+
+      await expect(handler(fakeEvent)).rejects.toMatchObject({ statusCode: 404 })
+    })
+
+    it('throws 404 when the version is missing', async () => {
+      routerParam = 'pkg-only'
+
+      await expect(handler(fakeEvent)).rejects.toMatchObject({ statusCode: 404 })
+    })
+
+    it('propagates errors from assertValidPackageName', async () => {
+      routerParam = 'bad name/v/1.0.0'
+      assertValidPackageNameMock.mockImplementation(() => {
+        throw createError({ statusCode: 400, message: 'invalid package name' })
+      })
+
+      await expect(handler(fakeEvent)).rejects.toMatchObject({ statusCode: 400 })
+    })
+  })
+})
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..713de4bb5c
--- /dev/null
+++ b/test/unit/server/utils/docs/client.spec.ts
@@ -0,0 +1,263 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock @deno/doc
+const docMock = vi.fn()
+vi.mock('@deno/doc', () => ({
+  doc: (...args: unknown[]) => docMock(...args),
+}))
+
+vi.mock('#shared/utils/npm', () => ({
+  encodePackageName: (name: string) => name.replaceAll('/', '%2f'),
+}))
+
+// $fetch.raw() is used for esm.sh HEAD requests (still global). The npm registry path
+// is now injected via the DocsFetch parameter — we pass `testFetch` below.
+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')
+
+// Test seam for the injected `DocsFetch`: delegates to the global $fetch mock so each
+// test can set responses via `setupMocks(...)` exactly as before.
+const testFetch = (url: string, options?: { timeout?: number }): Promise<unknown> =>
+  $fetchMock(url, options)
+
+/**
+ * @param headMap - Maps esm.sh URLs to their `x-typescript-types` header value.
+ *   `string` = types URL returned, `null` = 200 with no header, key absent = 404.
+ * @param registryResponse - Single response served for any npm registry GET.
+ */
+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()
+  })
+
+  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 })
+    docMock.mockResolvedValue({ [typesUrl]: [{ name: 'parseURL', kind: 'function' }] })
+
+    const result = await getDocNodes('ufo', '1.5.0', testFetch)
+
+    expect(result.nodes).toEqual([{ name: 'parseURL', kind: 'function' }])
+    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 and no exports', async () => {
+    setupMocks({ 'https://esm.sh/pkg@1.0.0': null }, { exports: undefined })
+
+    const result = await getDocNodes('pkg', '1.0.0', testFetch)
+
+    expect(result.nodes).toEqual([])
+    expect(docMock).not.toHaveBeenCalled()
+  })
+
+  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', testFetch)
+
+    expect(result.nodes).toHaveLength(2)
+    expect(result.nodes.map(n => n.name).sort()).toEqual(['Bar', 'foo'])
+  })
+
+  describe('failure isolation', () => {
+    it('returns empty nodes when esm.sh, the npm registry, or @deno/doc throws', async () => {
+      // All three external boundaries fail simultaneously — the function still resolves.
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+      docMock.mockRejectedValue(new Error('WASM error'))
+
+      const result = await getDocNodes('pkg', '1.0.0', testFetch)
+
+      expect(result.nodes).toEqual([])
+    })
+  })
+
+  describe('subpath exports fallback', () => {
+    it('falls back to subpath exports when root returns 404', async () => {
+      const routerTypes = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/router/index.d.ts'
+      const apiTypes = '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': routerTypes,
+          'https://esm.sh/@thepassle/app-tools@0.10.2/api.js': apiTypes,
+        },
+        {
+          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({
+        [routerTypes]: [{ name: 'Router', kind: 'class' }],
+        [apiTypes]: [{ name: 'createApi', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('@thepassle/app-tools', '0.10.2', testFetch)
+
+      expect(result.nodes).toHaveLength(2)
+      expect(docMock).toHaveBeenCalledWith(
+        expect.arrayContaining([routerTypes, apiTypes]),
+        expect.any(Object),
+      )
+    })
+
+    it('skips wildcard, root, and untyped exports', async () => {
+      const stateTypes = 'https://esm.sh/pkg@1.0.0/types/state/index.d.ts'
+
+      setupMocks(
+        { 'https://esm.sh/pkg@1.0.0/state.js': stateTypes },
+        {
+          exports: {
+            '.': { types: './index.d.ts', default: './index.js' },
+            './utils/*': { types: './types/utils/*', default: './utils/*' },
+            './no-types.js': { default: './no-types.js' },
+            './state.js': { types: './types/state/index.d.ts', default: './state.js' },
+            './package.json': './package.json',
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({ [stateTypes]: [{ name: 'createState', kind: 'function' }] })
+
+      const result = await getDocNodes('pkg', '1.0.0', testFetch)
+
+      // Only `./state.js` is processed — wildcards, root, untyped, and string-valued exports are skipped.
+      expect(result.nodes).toHaveLength(1)
+      expect(docMock).toHaveBeenCalledWith([stateTypes], expect.any(Object))
+    })
+
+    it('handles partial subpath failures gracefully', async () => {
+      const apiTypes = 'https://esm.sh/pkg@1.0.0/api.d.ts'
+
+      setupMocks(
+        // router.js HEAD fails (key absent → throws), api.js succeeds
+        { 'https://esm.sh/pkg@1.0.0/api.js': apiTypes },
+        {
+          exports: {
+            './router.js': { types: './router.d.ts', default: './router.js' },
+            './api.js': { types: './api.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({ [apiTypes]: [{ name: 'createApi', kind: 'function' }] })
+
+      const result = await getDocNodes('pkg', '1.0.0', testFetch)
+
+      expect(result.nodes).toHaveLength(1)
+      expect(result.nodes[0]!.name).toBe('createApi')
+    })
+
+    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', testFetch)
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+  })
+})
+
+describe('docs/client - getDocNodesForEntrypoint', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  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 })
+    docMock.mockResolvedValue({ [typesUrl]: [{ name: 'Router', kind: 'class' }] })
+
+    const result = await getDocNodesForEntrypoint('@thepassle/app-tools', '0.10.2', 'router.js')
+
+    expect(result.nodes).toEqual([{ name: 'Router', kind: 'class' }])
+    expect(docMock).toHaveBeenCalledWith([typesUrl], expect.any(Object))
+  })
+
+  it('returns empty nodes when the 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()
+  })
+})
+
+describe('docs/client - getSubpathExports', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('extracts subpaths from nested condition objects (vue-style import/require)', async () => {
+    // Real-world shape: vue declares types inside `import` and `require` conditions.
+    setupMocks(
+      {},
+      {
+        exports: {
+          './server-renderer': {
+            import: { types: './dist/server-renderer.d.mts', default: './server-renderer.mjs' },
+            require: { types: './dist/server-renderer.d.ts', default: './server-renderer.js' },
+          },
+          './compiler-sfc': {
+            browser: './compiler-sfc/index.browser.js',
+            import: { types: './compiler-sfc/index.d.mts', default: './compiler-sfc/index.mjs' },
+          },
+        },
+      },
+    )
+
+    const result = await getSubpathExports('pkg', '1.0.0', testFetch)
+
+    expect(result).toEqual(['server-renderer', 'compiler-sfc'])
+  })
+
+  it('returns empty array when the package has no exports field', async () => {
+    setupMocks({}, { name: 'pkg' })
+
+    const result = await getSubpathExports('pkg', '1.0.0', testFetch)
+
+    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..c3a1bf399e
--- /dev/null
+++ b/test/unit/server/utils/docs/index.spec.ts
@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+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),
+}))
+
+vi.mock('../../../../../server/utils/docs/processing', () => ({
+  flattenNamespaces: (nodes: unknown[]) => nodes,
+  mergeOverloads: (nodes: unknown[]) => nodes,
+  buildSymbolLookup: () => new Map(),
+}))
+
+vi.mock('../../../../../server/utils/docs/render', () => ({
+  renderDocNodes: async () => '<div>docs</div>',
+  renderToc: () => '<nav>toc</nav>',
+}))
+
+const { generateDocsWithDeno, getEntrypoints } =
+  await import('../../../../../server/utils/docs/index')
+
+// Sentinel passed as the required `registryFetch` arg. The underlying client functions
+// are mocked, so this is never invoked — but the helpers verify it's threaded through.
+const stubFetch: (url: string) => Promise<unknown> = vi.fn()
+
+describe('docs/index', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('getEntrypoints', () => {
+    it('returns null when the package only has root docs', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue('https://esm.sh/ufo@1.5.0/dist/index.d.ts')
+      getSubpathExportsMock.mockResolvedValue([])
+
+      expect(await getEntrypoints('ufo', '1.5.0', stubFetch)).toBeNull()
+    })
+
+    it('returns null when the package has neither root types nor subpath exports', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue(null)
+      getSubpathExportsMock.mockResolvedValue([])
+
+      expect(await getEntrypoints('pkg', '1.0.0', stubFetch)).toBeNull()
+    })
+
+    it('prepends the root entrypoint marker when both root docs and subpath docs exist', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue('https://esm.sh/vue@3.5.30/dist/index.d.mts')
+      getSubpathExportsMock.mockResolvedValue(['server-renderer', 'compiler-sfc'])
+
+      expect(await getEntrypoints('vue', '3.5.30', stubFetch)).toEqual([
+        '.',
+        'server-renderer',
+        'compiler-sfc',
+      ])
+    })
+
+    it('returns subpath exports without the root marker when root has no types', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue(null)
+      getSubpathExportsMock.mockResolvedValue(['router.js', 'api.js'])
+
+      expect(await getEntrypoints('@thepassle/app-tools', '0.10.2', stubFetch)).toEqual([
+        'router.js',
+        'api.js',
+      ])
+    })
+
+    it('threads the registryFetch through to getSubpathExports', async () => {
+      getTypesUrlForSubpathMock.mockResolvedValue(null)
+      getSubpathExportsMock.mockResolvedValue([])
+
+      await getEntrypoints('pkg', '1.0.0', stubFetch)
+
+      expect(getSubpathExportsMock).toHaveBeenCalledWith('pkg', '1.0.0', stubFetch)
+    })
+  })
+
+  describe('generateDocsWithDeno', () => {
+    it('uses getDocNodes (with registryFetch) for the package root', async () => {
+      getDocNodesMock.mockResolvedValue({ version: 1, nodes: [{ name: 'foo', kind: 'function' }] })
+
+      const result = await generateDocsWithDeno('ufo', '1.5.0', undefined, stubFetch)
+
+      expect(getDocNodesMock).toHaveBeenCalledWith('ufo', '1.5.0', stubFetch)
+      expect(result).toEqual({
+        html: '<div>docs</div>',
+        toc: '<nav>toc</nav>',
+        nodes: [{ name: 'foo', kind: 'function' }],
+      })
+    })
+
+    it('uses getDocNodesForEntrypoint when an entrypoint is specified', async () => {
+      getDocNodesForEntrypointMock.mockResolvedValue({
+        version: 1,
+        nodes: [{ name: 'Router', kind: 'class' }],
+      })
+
+      await generateDocsWithDeno('@thepassle/app-tools', '0.10.2', 'router.js', stubFetch)
+
+      expect(getDocNodesForEntrypointMock).toHaveBeenCalledWith(
+        '@thepassle/app-tools',
+        '0.10.2',
+        'router.js',
+      )
+    })
+
+    it('treats the "." entrypoint marker as the package root', async () => {
+      // Non-obvious normalization: callers pass "." for clarity, but the root API takes undefined.
+      getDocNodesMock.mockResolvedValue({ version: 1, nodes: [{ name: 'createApp' }] })
+
+      await generateDocsWithDeno('vue', '3.5.30', '.', stubFetch)
+
+      expect(getDocNodesMock).toHaveBeenCalledWith('vue', '3.5.30', stubFetch)
+      expect(getDocNodesForEntrypointMock).not.toHaveBeenCalled()
+    })
+
+    it('returns null when no doc nodes are produced', async () => {
+      getDocNodesMock.mockResolvedValue({ version: 1, nodes: [] })
+
+      expect(await generateDocsWithDeno('pkg', '1.0.0', undefined, stubFetch)).toBeNull()
+    })
+  })
+})