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

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

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

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

Closes #1479
---
 app/components/EntrypointSelector.vue      |  28 ++
 app/pages/package-docs/[...path].vue       |  50 ++-
 server/api/registry/docs/[...pkg].get.ts   |  31 +-
 server/utils/docs/client.ts                | 128 ++++++-
 server/utils/docs/index.ts                 |  42 ++-
 shared/types/docs.ts                       |   4 +
 test/unit/a11y-component-coverage.spec.ts  |   1 +
 test/unit/server/utils/docs/client.spec.ts | 405 +++++++++++++++++++++
 8 files changed, 662 insertions(+), 27 deletions(-)
 create mode 100644 app/components/EntrypointSelector.vue
 create mode 100644 test/unit/server/utils/docs/client.spec.ts

diff --git a/app/components/EntrypointSelector.vue b/app/components/EntrypointSelector.vue
new file mode 100644
index 000000000..edbd1b385
--- /dev/null
+++ b/app/components/EntrypointSelector.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+const props = defineProps<{
+  packageName: string
+  version: string
+  currentEntrypoint: string
+  entrypoints: string[]
+}>()
+
+function getEntrypointUrl(entrypoint: string): string {
+  return `/package-docs/${props.packageName}/v/${props.version}/${entrypoint}`
+}
+
+function onSelect(event: Event) {
+  const target = event.target as HTMLSelectElement
+  navigateTo(getEntrypointUrl(target.value))
+}
+</script>
+
+<template>
+  <select
+    :value="currentEntrypoint"
+    aria-label="Select entrypoint"
+    class="text-fg-subtle font-mono text-sm bg-transparent border border-border rounded px-2 py-1 hover:text-fg hover:border-border-subtle transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring shrink-0"
+    @change="onSelect"
+  >
+    <option v-for="ep in entrypoints" :key="ep" :value="ep">./{{ ep }}</option>
+  </select>
+</template>
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index 07e6dbe92..76c28c46b 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -21,17 +21,26 @@ const parsedRoute = computed(() => {
     return {
       packageName: segments.join('/'),
       version: null as string | null,
+      entrypoint: null as string | null,
     }
   }
 
+  // Version is the segment right after "v"
+  const version = segments[vIndex + 1]!
+  // Everything after the version is the entrypoint path (e.g., "router.js")
+  const entrypointSegments = segments.slice(vIndex + 2)
+  const entrypoint = entrypointSegments.length > 0 ? entrypointSegments.join('/') : null
+
   return {
     packageName: segments.slice(0, vIndex).join('/'),
-    version: segments.slice(vIndex + 1).join('/'),
+    version,
+    entrypoint,
   }
 })
 
 const packageName = computed(() => parsedRoute.value.packageName)
 const requestedVersion = computed(() => parsedRoute.value.version)
+const entrypoint = computed(() => parsedRoute.value.entrypoint)
 
 // Validate package name on server-side for early error detection
 if (import.meta.server && packageName.value) {
@@ -72,7 +81,8 @@ const resolvedVersion = computed(() => requestedVersion.value ?? latestVersion.v
 
 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,6 +129,33 @@ const showLoading = computed(
   () => docsStatus.value === 'pending' || (docsStatus.value === 'idle' && docsUrl.value !== null),
 )
 const showEmptyState = computed(() => docsData.value?.status !== 'ok')
+
+// Multi-entrypoint support
+const entrypoints = computed(() => docsData.value?.entrypoints ?? null)
+const currentEntrypoint = computed(() => docsData.value?.entrypoint ?? entrypoint.value ?? '')
+
+// Preserve entrypoint when switching versions
+const versionUrlPattern = computed(() => {
+  const base = `/package-docs/${packageName.value}/v/{version}`
+  return entrypoint.value ? `${base}/${entrypoint.value}` : base
+})
+
+// Redirect to first entrypoint for multi-entrypoint packages
+watch(docsData, data => {
+  if (data?.entrypoints?.length && !entrypoint.value && resolvedVersion.value) {
+    const firstEntrypoint = data.entrypoints[0]!
+    const pathSegments = [
+      ...packageName.value.split('/'),
+      'v',
+      resolvedVersion.value,
+      ...firstEntrypoint.split('/'),
+    ]
+    router.replace({
+      name: 'docs',
+      params: { path: pathSegments as [string, ...string[]] },
+    })
+  }
+})
 </script>
 
 <template>
@@ -148,11 +185,18 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
               :current-version="resolvedVersion"
               :versions="pkg.versions"
               :dist-tags="pkg['dist-tags']"
-              :url-pattern="`/package-docs/${packageName}/v/{version}`"
+              :url-pattern="versionUrlPattern"
             />
             <span v-else-if="resolvedVersion" class="text-fg-subtle font-mono text-sm shrink-0">
               {{ resolvedVersion }}
             </span>
+            <EntrypointSelector
+              v-if="entrypoints && currentEntrypoint && resolvedVersion"
+              :package-name="packageName"
+              :version="resolvedVersion"
+              :current-entrypoint="currentEntrypoint"
+              :entrypoints="entrypoints"
+            />
           </div>
           <div class="flex items-center gap-3 shrink-0">
             <span class="text-xs px-2 py-1 rounded badge-green border border-badge-green/50">
diff --git a/server/api/registry/docs/[...pkg].get.ts b/server/api/registry/docs/[...pkg].get.ts
index 95402cf86..3165d4ccf 100644
--- a/server/api/registry/docs/[...pkg].get.ts
+++ b/server/api/registry/docs/[...pkg].get.ts
@@ -1,7 +1,7 @@
 import type { DocsResponse } from '#shared/types'
 import { assertValidPackageName } from '#shared/utils/npm'
 import { parsePackageParam } from '#shared/utils/parse-package-param'
-import { generateDocsWithDeno } from '#server/utils/docs'
+import { generateDocsWithDeno, getEntrypoints } from '#server/utils/docs'
 
 export default defineCachedEventHandler(
   async event => {
@@ -11,7 +11,7 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package name is required' })
     }
 
-    const { packageName, version } = parsePackageParam(pkgParam)
+    const { packageName, version, rest } = parsePackageParam(pkgParam)
 
     if (!packageName) {
       // TODO: throwing 404 rather than 400 as it's cacheable
@@ -24,9 +24,29 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package version is required' })
     }
 
+    // Extract entrypoint from remaining path segments (e.g., ["router.js"] -> "router.js")
+    const entrypoint = rest.length > 0 ? rest.join('/') : undefined
+
+    // Discover available entrypoints (null for single-entrypoint packages)
+    const entrypoints = await getEntrypoints(packageName, version)
+
+    // If multi-entrypoint but no specific entrypoint requested, return early
+    // with the entrypoints list so the client can redirect to the first one
+    if (entrypoints && !entrypoint) {
+      return {
+        package: packageName,
+        version,
+        html: '',
+        toc: null,
+        status: 'ok',
+        entrypoints,
+        entrypoint: entrypoints[0],
+      } satisfies DocsResponse
+    }
+
     let generated
     try {
-      generated = await generateDocsWithDeno(packageName, version)
+      generated = await generateDocsWithDeno(packageName, version, entrypoint)
     } catch (error) {
       // eslint-disable-next-line no-console
       console.error(`Doc generation failed for ${packageName}@${version}:`, error)
@@ -37,6 +57,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'error',
         message: 'Failed to generate documentation. Please try again later.',
+        ...(entrypoints && { entrypoints, entrypoint }),
       } satisfies DocsResponse
     }
 
@@ -48,6 +69,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'missing',
         message: 'Docs are not available for this package. It may not have TypeScript types.',
+        ...(entrypoints && { entrypoints, entrypoint }),
       } satisfies DocsResponse
     }
 
@@ -57,6 +79,7 @@ export default defineCachedEventHandler(
       html: generated.html,
       toc: generated.toc,
       status: 'ok',
+      ...(entrypoints && { entrypoints, entrypoint }),
     } satisfies DocsResponse
   },
   {
@@ -64,7 +87,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 dc3f78d1b..2fa30caf7 100644
--- a/server/utils/docs/client.ts
+++ b/server/utils/docs/client.ts
@@ -10,6 +10,7 @@
 import { doc, type DocNode } from '@deno/doc'
 import type { DenoDocNode, DenoDocResult } from '#shared/types/deno-doc'
 import { isBuiltin } from 'node:module'
+import { encodePackageName } from '#shared/utils/npm'
 
 // =============================================================================
 // Configuration
@@ -18,6 +19,9 @@ import { isBuiltin } from 'node:module'
 /** Timeout for fetching modules in milliseconds */
 const FETCH_TIMEOUT_MS = 30 * 1000
 
+/** Maximum number of subpath exports to process */
+const MAX_SUBPATH_EXPORTS = 20
+
 // =============================================================================
 // Main Export
 // =============================================================================
@@ -26,17 +30,17 @@ const FETCH_TIMEOUT_MS = 30 * 1000
  * Get documentation nodes for a package using @deno/doc WASM.
  */
 export async function getDocNodes(packageName: string, version: string): Promise<DenoDocResult> {
-  // Get types URL from esm.sh header
-  const typesUrl = await getTypesUrl(packageName, version)
+  // Get types URL from esm.sh header for the root entry
+  const typesUrls = await getTypesUrls(packageName, version)
 
-  if (!typesUrl) {
+  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 +157,63 @@ function createResolver(): (specifier: string, referrer: string) => string {
   }
 }
 
+/**
+ * Get TypeScript types URLs for a package, trying the root entry first,
+ * then falling back to subpath exports if the package has no default export.
+ */
+async function getTypesUrls(packageName: string, version: string): Promise<string[]> {
+  // Try root entry first
+  const rootTypesUrl = await getTypesUrlForSubpath(packageName, version)
+  if (rootTypesUrl) {
+    return [rootTypesUrl]
+  }
+
+  // Root has no types — check subpath exports from the npm registry
+  const subpaths = await getSubpathExports(packageName, version)
+  if (subpaths.length === 0) {
+    return []
+  }
+
+  // Fetch types URLs for each subpath export in parallel
+  const results = await Promise.all(
+    subpaths.map(subpath => getTypesUrlForSubpath(packageName, version, subpath)),
+  )
+
+  return results.filter((url): url is string => url !== null)
+}
+
+/**
+ * Get documentation nodes for a specific subpath export of a package.
+ */
+export async function getDocNodesForEntrypoint(
+  packageName: string,
+  version: string,
+  entrypoint: string,
+): Promise<DenoDocResult> {
+  const typesUrl = await getTypesUrlForSubpath(packageName, version, entrypoint)
+
+  if (!typesUrl) {
+    return { version: 1, nodes: [] }
+  }
+
+  let result: Record<string, DocNode[]>
+  try {
+    result = await doc([typesUrl], {
+      load: createLoader(),
+      resolve: createResolver(),
+    })
+  } catch {
+    return { version: 1, nodes: [] }
+  }
+
+  const allNodes: DenoDocNode[] = []
+  for (const nodes of Object.values(result)) {
+    allNodes.push(...(nodes as DenoDocNode[]))
+  }
+
+  return { version: 1, nodes: allNodes }
+}
+
 /**
  * Get the TypeScript types URL from esm.sh's x-typescript-types header.
  *
@@ -160,8 +221,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 +236,52 @@ async function getTypesUrl(packageName: string, version: string): Promise<string
       timeout: FETCH_TIMEOUT_MS,
     })
     return response.headers.get('x-typescript-types')
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error(e)
+  } catch {
     return null
   }
 }
+
+/**
+ * Get subpath export paths from the npm registry's package.json `exports` field.
+ * Only returns subpaths that declare types (have a `types` condition).
+ *
+ * Skips the root export (".") since that's handled by the main getTypesUrl call.
+ * Skips wildcard patterns ("./foo/*") since they can't be resolved to specific files.
+ */
+export async function getSubpathExports(packageName: string, version: string): Promise<string[]> {
+  try {
+    const encodedName = encodePackageName(packageName)
+    const pkgJson = await $fetch<Record<string, unknown>>(
+      `https://registry.npmjs.org/${encodedName}/${version}`,
+      { timeout: FETCH_TIMEOUT_MS },
+    )
+
+    const exports = pkgJson.exports
+    if (!exports || typeof exports !== 'object') {
+      return []
+    }
+
+    const subpaths: string[] = []
+
+    for (const [key, value] of Object.entries(exports as Record<string, unknown>)) {
+      // Skip root export (already tried), non-subpath entries, and wildcards
+      if (key === '.' || !key.startsWith('./') || key.includes('*')) {
+        continue
+      }
+
+      // Only include exports that declare types
+      if (value && typeof value === 'object' && 'types' in value) {
+        // Strip leading "./" for the esm.sh URL
+        subpaths.push(key.slice(2))
+      }
+
+      if (subpaths.length >= MAX_SUBPATH_EXPORTS) {
+        break
+      }
+    }
+
+    return subpaths
+  } catch {
+    return []
+  }
+}
diff --git a/server/utils/docs/index.ts b/server/utils/docs/index.ts
index 66a739448..de25a4d50 100644
--- a/server/utils/docs/index.ts
+++ b/server/utils/docs/index.ts
@@ -9,34 +9,35 @@
  */
 
 import type { DocsGenerationResult } from '#shared/types/deno-doc'
-import { getDocNodes } from './client'
+import {
+  getDocNodes,
+  getDocNodesForEntrypoint,
+  getSubpathExports,
+  getTypesUrlForSubpath,
+} from './client'
 import { buildSymbolLookup, flattenNamespaces, mergeOverloads } from './processing'
 import { renderDocNodes, renderToc } from './render'
 
 /**
- * Generate API documentation for an npm package.
+ * Generate API documentation for an npm package (or a specific entrypoint).
  *
  * Uses @deno/doc (WASM build of deno_doc) with esm.sh URLs to extract
  * TypeScript type information and JSDoc comments, then renders them as HTML.
  *
  * @param packageName - The npm package name (e.g., "react", "@types/lodash")
  * @param version - The package version (e.g., "19.2.3")
+ * @param entrypoint - Optional subpath export (e.g., "router.js") for multi-entrypoint packages
  * @returns Generated documentation or null if no types are available
- *
- * @example
- * ```ts
- * const docs = await generateDocsWithDeno('ufo', '1.5.0')
- * if (docs) {
- *   console.log(docs.html)
- * }
- * ```
  */
 export async function generateDocsWithDeno(
   packageName: string,
   version: string,
+  entrypoint?: string,
 ): Promise<DocsGenerationResult | null> {
   // Get doc nodes using @deno/doc WASM
-  const result = await getDocNodes(packageName, version)
+  const result = entrypoint
+    ? await getDocNodesForEntrypoint(packageName, version, entrypoint)
+    : await getDocNodes(packageName, version)
 
   if (!result.nodes || result.nodes.length === 0) {
     return null
@@ -53,3 +54,22 @@ export async function generateDocsWithDeno(
 
   return { html, toc, nodes: flattenedNodes }
 }
+
+/**
+ * Get the list of subpath exports for a package, or null if it's a
+ * single-entrypoint package (has a root export with types).
+ */
+export async function getEntrypoints(
+  packageName: string,
+  version: string,
+): Promise<string[] | null> {
+  // Check if root entry has types
+  const rootTypesUrl = await getTypesUrlForSubpath(packageName, version)
+  if (rootTypesUrl) {
+    return null
+  }
+
+  // Multi-entrypoint: return subpath exports
+  const subpaths = await getSubpathExports(packageName, version)
+  return subpaths.length > 0 ? subpaths : null
+}
diff --git a/shared/types/docs.ts b/shared/types/docs.ts
index a59164f81..db884abdf 100644
--- a/shared/types/docs.ts
+++ b/shared/types/docs.ts
@@ -8,6 +8,10 @@ export interface DocsResponse {
   breadcrumbs?: string | null
   status: DocsStatus
   message?: string
+  /** Available entrypoints for multi-entrypoint packages. Absent for single-entrypoint packages. */
+  entrypoints?: string[]
+  /** The current entrypoint being viewed. Absent for single-entrypoint packages. */
+  entrypoint?: string
 }
 
 export interface DocsSearchResponse {
diff --git a/test/unit/a11y-component-coverage.spec.ts b/test/unit/a11y-component-coverage.spec.ts
index 0f18a000e..a9b713f53 100644
--- a/test/unit/a11y-component-coverage.spec.ts
+++ b/test/unit/a11y-component-coverage.spec.ts
@@ -46,6 +46,7 @@ const SKIPPED_COMPONENTS: Record<string, string> = {
   'SkeletonBlock.vue': 'Already covered indirectly via other component tests',
   'SkeletonInline.vue': 'Already covered indirectly via other component tests',
   'Button/Group.vue': "Wrapper component, tests wouldn't make much sense here",
+  'EntrypointSelector.vue': 'Simple native <select> wrapper - minimal a11y surface',
 }
 
 /**
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 000000000..9b01c9ce0
--- /dev/null
+++ b/test/unit/server/utils/docs/client.spec.ts
@@ -0,0 +1,405 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock @deno/doc
+const docMock = vi.fn()
+vi.mock('@deno/doc', () => ({
+  doc: (...args: unknown[]) => docMock(...args),
+}))
+
+// Mock encodePackageName
+vi.mock('#shared/utils/npm', () => ({
+  encodePackageName: (name: string) => name.replace('/', '%2f'),
+}))
+
+// Mock Nitro globals before importing the module.
+// $fetch.raw() is used for esm.sh HEAD requests, $fetch() directly for npm registry GETs.
+const $fetchRawMock = vi.fn()
+const $fetchMock = Object.assign(vi.fn(), { raw: $fetchRawMock })
+vi.stubGlobal('$fetch', $fetchMock)
+
+const { getDocNodes, getDocNodesForEntrypoint, getSubpathExports } =
+  await import('../../../../../server/utils/docs/client')
+
+/**
+ * Helper to mock esm.sh HEAD responses ($fetch.raw) and npm registry GETs ($fetch).
+ *
+ * @param headMap - Maps esm.sh URLs to their x-typescript-types header value.
+ *   `string` = types URL returned in header, `null` = 200 with no types header,
+ *   key absent = 404 (throws).
+ * @param registryResponse - Response for npm registry GET calls
+ */
+function setupMocks(
+  headMap: Record<string, string | null>,
+  registryResponse?: Record<string, unknown>,
+) {
+  $fetchRawMock.mockImplementation(async (url: string) => {
+    const typesUrl = headMap[url]
+    if (typesUrl === undefined) {
+      throw new Error(`404 Not Found: ${url}`)
+    }
+    return {
+      headers: new Headers(typesUrl ? { 'x-typescript-types': typesUrl } : {}),
+    }
+  })
+
+  $fetchMock.mockImplementation(async (url: string) => {
+    if (url.startsWith('https://registry.npmjs.org/') && registryResponse) {
+      return registryResponse
+    }
+    throw new Error(`Unexpected $fetch call: ${url}`)
+  })
+}
+
+describe('docs/client - getDocNodes', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('root entry (standard packages)', () => {
+    it('returns doc nodes when root entry has types', async () => {
+      const typesUrl = 'https://esm.sh/ufo@1.5.0/dist/index.d.ts'
+      setupMocks({ 'https://esm.sh/ufo@1.5.0': typesUrl })
+
+      const mockNodes = [{ name: 'parseURL', kind: 'function' }]
+      docMock.mockResolvedValue({ [typesUrl]: mockNodes })
+
+      const result = await getDocNodes('ufo', '1.5.0')
+
+      expect(result.nodes).toEqual(mockNodes)
+      expect(docMock).toHaveBeenCalledWith(
+        [typesUrl],
+        expect.objectContaining({ load: expect.any(Function), resolve: expect.any(Function) }),
+      )
+    })
+
+    it('returns empty nodes when root has no x-typescript-types header', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': null }, { exports: undefined })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when esm.sh HEAD request fails', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when @deno/doc throws', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': 'https://esm.sh/pkg@1.0.0/index.d.ts' })
+      docMock.mockRejectedValue(new Error('WASM error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('collects nodes from multiple specifiers in doc result', async () => {
+      const typesUrl = 'https://esm.sh/pkg@1.0.0/index.d.ts'
+      setupMocks({ 'https://esm.sh/pkg@1.0.0': typesUrl })
+
+      const reExportedUrl = 'https://esm.sh/pkg@1.0.0/types.d.ts'
+      docMock.mockResolvedValue({
+        [typesUrl]: [{ name: 'foo', kind: 'function' }],
+        [reExportedUrl]: [{ name: 'Bar', kind: 'interface' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(2)
+      expect(result.nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: 'foo' }),
+          expect.objectContaining({ name: 'Bar' }),
+        ]),
+      )
+    })
+  })
+
+  describe('subpath exports fallback', () => {
+    it('falls back to subpath exports when root returns 404', async () => {
+      const routerTypesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/router/index.d.ts'
+      const apiTypesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/api/index.d.ts'
+
+      setupMocks(
+        {
+          'https://esm.sh/@thepassle/app-tools@0.10.2/router.js': routerTypesUrl,
+          'https://esm.sh/@thepassle/app-tools@0.10.2/api.js': apiTypesUrl,
+        },
+        {
+          exports: {
+            './router.js': { types: './types/router/index.d.ts', default: './router.js' },
+            './api.js': { types: './types/api/index.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [routerTypesUrl]: [{ name: 'Router', kind: 'class' }],
+        [apiTypesUrl]: [{ name: 'createApi', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('@thepassle/app-tools', '0.10.2')
+
+      expect(result.nodes).toHaveLength(2)
+      expect(docMock).toHaveBeenCalledWith(
+        expect.arrayContaining([routerTypesUrl, apiTypesUrl]),
+        expect.any(Object),
+      )
+    })
+
+    it('skips wildcard exports', async () => {
+      const stateTypesUrl = 'https://esm.sh/pkg@1.0.0/types/state/index.d.ts'
+
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/state.js': stateTypesUrl,
+        },
+        {
+          exports: {
+            './utils/*': { types: './types/utils/*', default: './utils/*' },
+            './state.js': { types: './types/state/index.d.ts', default: './state.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [stateTypesUrl]: [{ name: 'createState', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(docMock).toHaveBeenCalledWith([stateTypesUrl], expect.any(Object))
+    })
+
+    it('skips root export "." in subpath processing', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0': null,
+          'https://esm.sh/pkg@1.0.0/sub.js': 'https://esm.sh/pkg@1.0.0/sub.d.ts',
+        },
+        {
+          exports: {
+            '.': { types: './index.d.ts', default: './index.js' },
+            './sub.js': { types: './sub.d.ts', default: './sub.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        'https://esm.sh/pkg@1.0.0/sub.d.ts': [{ name: 'sub', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      // Root was called once (initial attempt), sub.js was called once (fallback)
+      const headUrls = $fetchRawMock.mock.calls.map((call: unknown[]) => call[0])
+      expect(headUrls).toEqual(['https://esm.sh/pkg@1.0.0', 'https://esm.sh/pkg@1.0.0/sub.js'])
+    })
+
+    it('skips exports without types condition', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/typed.js': 'https://esm.sh/pkg@1.0.0/typed.d.ts',
+        },
+        {
+          exports: {
+            './no-types.js': { default: './no-types.js' },
+            './typed.js': { types: './typed.d.ts', default: './typed.js' },
+            './package.json': './package.json',
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        'https://esm.sh/pkg@1.0.0/typed.d.ts': [{ name: 'typed', kind: 'variable' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(result.nodes[0]!.name).toBe('typed')
+    })
+
+    it('returns empty when no subpath exports have types on esm.sh', async () => {
+      setupMocks(
+        {
+          'https://esm.sh/pkg@1.0.0/sub.js': null,
+        },
+        {
+          exports: {
+            './sub.js': { types: './sub.d.ts', default: './sub.js' },
+          },
+        },
+      )
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty when package has no exports field', async () => {
+      setupMocks({}, { name: 'pkg', version: '1.0.0' })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('returns empty when npm registry request fails', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('handles partial subpath failures gracefully', async () => {
+      const apiTypesUrl = 'https://esm.sh/pkg@1.0.0/api.d.ts'
+
+      setupMocks(
+        {
+          // router fails (key absent = throws)
+          'https://esm.sh/pkg@1.0.0/api.js': apiTypesUrl,
+        },
+        {
+          exports: {
+            './router.js': { types: './router.d.ts', default: './router.js' },
+            './api.js': { types: './api.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      docMock.mockResolvedValue({
+        [apiTypesUrl]: [{ name: 'createApi', kind: 'function' }],
+      })
+
+      const result = await getDocNodes('pkg', '1.0.0')
+
+      expect(result.nodes).toHaveLength(1)
+      expect(result.nodes[0]!.name).toBe('createApi')
+    })
+
+    it('encodes scoped package names for npm registry', async () => {
+      setupMocks({}, { exports: {} })
+
+      await getDocNodes('@scope/pkg', '1.0.0')
+
+      const registryCall = $fetchMock.mock.calls.find(
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].startsWith('https://registry.npmjs.org/'),
+      )
+      expect(registryCall).toBeDefined()
+      expect(registryCall![0]).toBe('https://registry.npmjs.org/@scope%2fpkg/1.0.0')
+    })
+  })
+
+  describe('getDocNodesForEntrypoint', () => {
+    it('returns doc nodes for a specific entrypoint', async () => {
+      const typesUrl = 'https://esm.sh/@thepassle/app-tools@0.10.2/types/router/index.d.ts'
+      setupMocks({
+        'https://esm.sh/@thepassle/app-tools@0.10.2/router.js': typesUrl,
+      })
+
+      const mockNodes = [{ name: 'Router', kind: 'class' }]
+      docMock.mockResolvedValue({ [typesUrl]: mockNodes })
+
+      const result = await getDocNodesForEntrypoint('@thepassle/app-tools', '0.10.2', 'router.js')
+
+      expect(result.nodes).toEqual(mockNodes)
+      expect(docMock).toHaveBeenCalledWith([typesUrl], expect.any(Object))
+    })
+
+    it('returns empty nodes when entrypoint has no types', async () => {
+      setupMocks({ 'https://esm.sh/pkg@1.0.0/sub.js': null })
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'sub.js')
+
+      expect(result.nodes).toEqual([])
+      expect(docMock).not.toHaveBeenCalled()
+    })
+
+    it('returns empty nodes when esm.sh fails for entrypoint', async () => {
+      setupMocks({})
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'missing.js')
+
+      expect(result.nodes).toEqual([])
+    })
+
+    it('returns empty nodes when @deno/doc throws for entrypoint', async () => {
+      setupMocks({
+        'https://esm.sh/pkg@1.0.0/sub.js': 'https://esm.sh/pkg@1.0.0/sub.d.ts',
+      })
+      docMock.mockRejectedValue(new Error('WASM error'))
+
+      const result = await getDocNodesForEntrypoint('pkg', '1.0.0', 'sub.js')
+
+      expect(result.nodes).toEqual([])
+    })
+  })
+
+  describe('getSubpathExports', () => {
+    it('returns subpath exports with types condition', async () => {
+      setupMocks(
+        {},
+        {
+          exports: {
+            './router.js': { types: './types/router/index.d.ts', default: './router.js' },
+            './api.js': { types: './types/api/index.d.ts', default: './api.js' },
+          },
+        },
+      )
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual(['router.js', 'api.js'])
+    })
+
+    it('skips root export, wildcards, and non-typed exports', async () => {
+      setupMocks(
+        {},
+        {
+          exports: {
+            '.': { types: './index.d.ts', default: './index.js' },
+            './utils/*': { types: './types/utils/*', default: './utils/*' },
+            './no-types.js': { default: './no-types.js' },
+            './typed.js': { types: './typed.d.ts', default: './typed.js' },
+            './package.json': './package.json',
+          },
+        },
+      )
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual(['typed.js'])
+    })
+
+    it('returns empty array when no exports field', async () => {
+      setupMocks({}, { name: 'pkg' })
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual([])
+    })
+
+    it('returns empty array on registry error', async () => {
+      $fetchRawMock.mockRejectedValue(new Error('Network error'))
+      $fetchMock.mockRejectedValue(new Error('Network error'))
+
+      const result = await getSubpathExports('pkg', '1.0.0')
+
+      expect(result).toEqual([])
+    })
+  })
+})