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()
+    })
+  })
+})