feat: generate package docs using `@deno/doc` (#135)

.npmrc

···
+@jsr:registry=https://npm.jsr.io

app/components/AppHeader.vue

···
 </script>
 
 <template>
-  <header class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border">
+  <header
+    aria-label="Site header"
+    class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border"
+  >
     <nav aria-label="Main navigation" class="container h-14 flex items-center">
       <!-- Left: Logo -->
       <div class="flex-shrink-0">

app/components/DocsVersionSelector.vue

···
+<script setup lang="ts">
+import { onClickOutside } from '@vueuse/core'
+import { compare } from 'semver'
+
+const props = defineProps<{
+  packageName: string
+  currentVersion: string
+  versions: Record<string, unknown>
+  distTags: Record<string, string>
+}>()
+
+const isOpen = ref(false)
+const dropdownRef = useTemplateRef('dropdownRef')
+const listboxRef = useTemplateRef('listboxRef')
+const focusedIndex = ref(-1)
+
+onClickOutside(dropdownRef, () => {
+  isOpen.value = false
+})
+
+/** Maximum number of versions to show in dropdown */
+const MAX_VERSIONS = 10
+
+/** Safe version comparison that falls back to string comparison on error */
+function safeCompareVersions(a: string, b: string): number {
+  try {
+    return compare(a, b)
+  } catch {
+    return a.localeCompare(b)
+  }
+}
+
+/** Get sorted list of recent versions with their tags */
+const recentVersions = computed(() => {
+  const versionList = Object.keys(props.versions)
+    .sort((a, b) => safeCompareVersions(b, a))
+    .slice(0, MAX_VERSIONS)
+
+  // Create a map of version -> tags
+  const versionTags = new Map<string, string[]>()
+  for (const [tag, version] of Object.entries(props.distTags)) {
+    const existing = versionTags.get(version)
+    if (existing) {
+      existing.push(tag)
+    } else {
+      versionTags.set(version, [tag])
+    }
+  }
+
+  return versionList.map(version => ({
+    version,
+    tags: versionTags.get(version) ?? [],
+    isCurrent: version === props.currentVersion,
+  }))
+})
+
+const latestVersion = computed(() => props.distTags.latest)
+
+function getDocsUrl(version: string): string {
+  return `/docs/${props.packageName}/v/${version}`
+}
+
+function handleButtonKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') {
+    isOpen.value = false
+  } else if (event.key === 'ArrowDown' && !isOpen.value) {
+    event.preventDefault()
+    isOpen.value = true
+    focusedIndex.value = 0
+  }
+}
+
+function handleListboxKeydown(event: KeyboardEvent) {
+  const items = recentVersions.value
+
+  switch (event.key) {
+    case 'Escape':
+      isOpen.value = false
+      break
+    case 'ArrowDown':
+      event.preventDefault()
+      focusedIndex.value = Math.min(focusedIndex.value + 1, items.length - 1)
+      scrollToFocused()
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      focusedIndex.value = Math.max(focusedIndex.value - 1, 0)
+      scrollToFocused()
+      break
+    case 'Home':
+      event.preventDefault()
+      focusedIndex.value = 0
+      scrollToFocused()
+      break
+    case 'End':
+      event.preventDefault()
+      focusedIndex.value = items.length - 1
+      scrollToFocused()
+      break
+    case 'Enter':
+    case ' ':
+      event.preventDefault()
+      if (focusedIndex.value >= 0 && focusedIndex.value < items.length) {
+        navigateToVersion(items[focusedIndex.value]!.version)
+      }
+      break
+  }
+}
+
+function scrollToFocused() {
+  nextTick(() => {
+    const focused = listboxRef.value?.querySelector('[data-focused="true"]')
+    focused?.scrollIntoView({ block: 'nearest' })
+  })
+}
+
+function navigateToVersion(version: string) {
+  isOpen.value = false
+  navigateTo(getDocsUrl(version))
+}
+
+// Reset focused index when dropdown opens
+watch(isOpen, open => {
+  if (open) {
+    const currentIdx = recentVersions.value.findIndex(v => v.isCurrent)
+    focusedIndex.value = currentIdx >= 0 ? currentIdx : 0
+  }
+})
+</script>
+
+<template>
+  <div ref="dropdownRef" class="relative">
+    <button
+      type="button"
+      aria-haspopup="listbox"
+      :aria-expanded="isOpen"
+      class="flex items-center gap-1.5 text-fg-subtle font-mono text-sm hover:text-fg transition-[color] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-bg rounded"
+      @click="isOpen = !isOpen"
+      @keydown="handleButtonKeydown"
+    >
+      <span>{{ currentVersion }}</span>
+      <span
+        v-if="currentVersion === latestVersion"
+        class="text-[10px] px-1.5 py-0.5 rounded bg-emerald-500/10 text-emerald-400 font-sans font-medium"
+      >
+        latest
+      </span>
+      <span
+        class="i-carbon-chevron-down w-3.5 h-3.5 transition-[transform] duration-200 motion-reduce:transition-none"
+        :class="{ 'rotate-180': isOpen }"
+        aria-hidden="true"
+      />
+    </button>
+
+    <Transition
+      enter-active-class="transition-[opacity,transform] duration-150 ease-out motion-reduce:transition-none"
+      enter-from-class="opacity-0 scale-95"
+      enter-to-class="opacity-100 scale-100"
+      leave-active-class="transition-[opacity,transform] duration-100 ease-in motion-reduce:transition-none"
+      leave-from-class="opacity-100 scale-100"
+      leave-to-class="opacity-0 scale-95"
+    >
+      <div
+        v-if="isOpen"
+        ref="listboxRef"
+        role="listbox"
+        tabindex="0"
+        :aria-activedescendant="
+          focusedIndex >= 0 ? `version-${recentVersions[focusedIndex]?.version}` : undefined
+        "
+        class="absolute top-full left-0 mt-2 min-w-[180px] bg-bg-elevated border border-border rounded-lg shadow-lg z-50 py-1 max-h-[300px] overflow-y-auto overscroll-contain focus-visible:outline-none"
+        @keydown="handleListboxKeydown"
+      >
+        <NuxtLink
+          v-for="({ version, tags, isCurrent }, index) in recentVersions"
+          :id="`version-${version}`"
+          :key="version"
+          :to="getDocsUrl(version)"
+          role="option"
+          :aria-selected="isCurrent"
+          :data-focused="index === focusedIndex"
+          class="flex items-center justify-between gap-3 px-3 py-2 text-sm font-mono hover:bg-bg-muted transition-[color,background-color] focus-visible:outline-none focus-visible:bg-bg-muted"
+          :class="[
+            isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-muted',
+            index === focusedIndex ? 'bg-bg-muted' : '',
+          ]"
+          @click="isOpen = false"
+        >
+          <span class="truncate">{{ version }}</span>
+          <span v-if="tags.length > 0" class="flex items-center gap-1 shrink-0">
+            <span
+              v-for="tag in tags"
+              :key="tag"
+              class="text-[10px] px-1.5 py-0.5 rounded font-sans font-medium"
+              :class="
+                tag === 'latest'
+                  ? 'bg-emerald-500/10 text-emerald-400'
+                  : 'bg-bg-muted text-fg-subtle'
+              "
+            >
+              {{ tag }}
+            </span>
+          </span>
+        </NuxtLink>
+
+        <div
+          v-if="Object.keys(versions).length > MAX_VERSIONS"
+          class="border-t border-border mt-1 pt-1 px-3 py-2"
+        >
+          <NuxtLink
+            :to="`/${packageName}`"
+            class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
+            @click="isOpen = false"
+          >
+            View all {{ Object.keys(versions).length }} versions
+          </NuxtLink>
+        </div>
+      </div>
+    </Transition>
+  </div>
+</template>

app/pages/[...package].vue

···
   return homepage
 })
 
+// Docs URL: use our generated API docs
+const docsLink = computed(() => {
+  if (!displayVersion.value) return null
+
+  return {
+    name: 'docs' as const,
+    params: { path: [...pkg.value!.name.split('/'), 'v', displayVersion.value.version] },
+  }
+})
+
 function normalizeGitUrl(url: string): string {
   return url
     .replace(/^git\+/, '')
···
                 <span class="i-simple-icons-jsr w-4 h-4" aria-hidden="true" />
                 {{ $t('package.links.jsr') }}
               </a>
+            </li>
+            <li v-if="docsLink">
+              <NuxtLink
+                :to="docsLink"
+                class="link-subtle font-mono text-sm inline-flex items-center gap-1.5"
+              >
+                <span class="i-carbon-document w-4 h-4" aria-hidden="true" />
+                {{ $t('package.links.docs') }}
+              </NuxtLink>
             </li>
             <li v-if="displayVersion" class="sm:ml-auto">
               <NuxtLink

app/pages/docs/[...path].vue

···
+<script setup lang="ts">
+import type { DocsResponse } from '#shared/types'
+import { assertValidPackageName } from '#shared/utils/npm'
+
+definePageMeta({
+  name: 'docs',
+})
+
+const route = useRoute('docs')
+const router = useRouter()
+
+const parsedRoute = computed(() => {
+  const segments = route.params.path || []
+  const vIndex = segments.indexOf('v')
+
+  if (vIndex === -1 || vIndex >= segments.length - 1) {
+    return {
+      packageName: segments.join('/'),
+      version: null as string | null,
+    }
+  }
+
+  return {
+    packageName: segments.slice(0, vIndex).join('/'),
+    version: segments.slice(vIndex + 1).join('/'),
+  }
+})
+
+const packageName = computed(() => parsedRoute.value.packageName)
+const requestedVersion = computed(() => parsedRoute.value.version)
+
+// Validate package name on server-side for early error detection
+if (import.meta.server && packageName.value) {
+  assertValidPackageName(packageName.value)
+}
+
+const { data: pkg } = usePackage(packageName)
+
+const latestVersion = computed(() => pkg.value?.['dist-tags']?.latest ?? null)
+
+watch(
+  [requestedVersion, latestVersion, packageName],
+  ([version, latest, name]) => {
+    if (!version && latest && name) {
+      router.replace(`/docs/${name}/v/${latest}`)
+    }
+  },
+  { immediate: true },
+)
+
+const resolvedVersion = computed(() => requestedVersion.value ?? latestVersion.value)
+
+const docsUrl = computed(() => {
+  if (!packageName.value || !resolvedVersion.value) return null
+  return `/api/registry/docs/${packageName.value}/v/${resolvedVersion.value}`
+})
+
+const shouldFetch = computed(() => !!docsUrl.value)
+
+const { data: docsData, status: docsStatus } = useLazyFetch<DocsResponse>(
+  () => docsUrl.value ?? '',
+  {
+    watch: [docsUrl],
+    immediate: shouldFetch.value,
+    default: () => ({
+      package: packageName.value,
+      version: resolvedVersion.value ?? '',
+      html: '',
+      toc: null,
+      status: 'missing' as const,
+      message: 'Docs are not available for this version.',
+    }),
+  },
+)
+
+const pageTitle = computed(() => {
+  if (!packageName.value) return 'API Docs - npmx'
+  if (!resolvedVersion.value) return `${packageName.value} docs - npmx`
+  return `${packageName.value}@${resolvedVersion.value} docs - npmx`
+})
+
+useSeoMeta({
+  title: () => pageTitle.value,
+})
+
+const showLoading = computed(() => docsStatus.value === 'pending')
+const showEmptyState = computed(() => docsData.value?.status !== 'ok')
+</script>
+
+<template>
+  <div class="docs-page min-h-screen">
+    <!-- Visually hidden h1 for accessibility -->
+    <h1 class="sr-only">{{ packageName }} API Documentation</h1>
+
+    <!-- Sticky header - positioned below AppHeader -->
+    <header
+      aria-label="Package documentation header"
+      class="docs-header sticky z-10 bg-bg/95 backdrop-blur border-b border-border"
+    >
+      <div class="px-4 sm:px-6 lg:px-8 py-4">
+        <div class="flex items-center justify-between gap-4">
+          <div class="flex items-center gap-3 min-w-0">
+            <NuxtLink
+              v-if="packageName"
+              :to="`/${packageName}`"
+              class="font-mono text-lg sm:text-xl font-semibold text-fg hover:text-fg-muted transition-colors truncate"
+            >
+              {{ packageName }}
+            </NuxtLink>
+            <DocsVersionSelector
+              v-if="resolvedVersion && pkg?.versions && pkg?.['dist-tags']"
+              :package-name="packageName"
+              :current-version="resolvedVersion"
+              :versions="pkg.versions"
+              :dist-tags="pkg['dist-tags']"
+            />
+            <span v-else-if="resolvedVersion" class="text-fg-subtle font-mono text-sm shrink-0">
+              {{ resolvedVersion }}
+            </span>
+          </div>
+          <div class="flex items-center gap-3 shrink-0">
+            <span
+              class="text-xs px-2 py-1 rounded bg-emerald-500/10 text-emerald-400 border border-emerald-500/20"
+            >
+              API Docs
+            </span>
+          </div>
+        </div>
+      </div>
+    </header>
+
+    <div class="flex">
+      <!-- Sidebar TOC -->
+      <aside
+        v-if="docsData?.toc && !showEmptyState"
+        class="hidden lg:block w-64 xl:w-72 shrink-0 border-r border-border"
+      >
+        <div class="docs-sidebar sticky overflow-y-auto p-4">
+          <h2 class="text-xs font-semibold text-fg-subtle uppercase tracking-wider mb-4">
+            Contents
+          </h2>
+          <!-- eslint-disable vue/no-v-html -->
+          <div class="toc-content" v-html="docsData.toc" />
+        </div>
+      </aside>
+
+      <!-- Main content -->
+      <main class="flex-1 min-w-0">
+        <div v-if="showLoading" class="p-6 sm:p-8 lg:p-12 space-y-4">
+          <div class="skeleton h-8 w-64 rounded" />
+          <div class="skeleton h-4 w-full max-w-2xl rounded" />
+          <div class="skeleton h-4 w-5/6 max-w-2xl rounded" />
+          <div class="skeleton h-4 w-3/4 max-w-2xl rounded" />
+        </div>
+
+        <div v-else-if="showEmptyState" class="p-6 sm:p-8 lg:p-12">
+          <div class="max-w-xl rounded-lg border border-border bg-bg-muted p-6">
+            <h2 class="font-mono text-lg mb-2">Docs not available</h2>
+            <p class="text-fg-subtle text-sm">
+              {{ docsData?.message ?? 'We could not generate docs for this version.' }}
+            </p>
+            <div class="flex gap-4 mt-4">
+              <NuxtLink
+                v-if="packageName"
+                :to="`/${packageName}`"
+                class="link-subtle font-mono text-sm"
+              >
+                View package
+              </NuxtLink>
+            </div>
+          </div>
+        </div>
+
+        <!-- eslint-disable vue/no-v-html -->
+        <div v-else class="docs-content p-6 sm:p-8 lg:p-12" v-html="docsData?.html" />
+      </main>
+    </div>
+  </div>
+</template>
+
+<style>
+/* Layout constants - must match AppHeader height */
+.docs-page {
+  --app-header-height: 57px;
+  --docs-header-height: 57px;
+  --combined-header-height: calc(var(--app-header-height) + var(--docs-header-height));
+}
+
+.docs-header {
+  top: var(--app-header-height);
+}
+
+.docs-sidebar {
+  top: var(--combined-header-height);
+  height: calc(100vh - var(--combined-header-height));
+}
+
+/* Table of contents styles */
+.toc-content ul {
+  @apply space-y-1;
+}
+
+.toc-content > ul > li {
+  @apply mb-4;
+}
+
+.toc-content > ul > li > a {
+  @apply text-sm font-medium text-fg-muted hover:text-fg;
+}
+
+.toc-content > ul > li > ul {
+  @apply mt-2 pl-3 border-l border-border/50;
+}
+
+.toc-content > ul > li > ul a {
+  @apply text-xs text-fg-subtle hover:text-fg block py-0.5 truncate;
+}
+
+/* Main docs content container - no max-width to use full space */
+.docs-content {
+  @apply max-w-none;
+}
+
+/* Section headings */
+.docs-content .docs-section {
+  @apply mb-16;
+}
+
+.docs-content .docs-section-title {
+  @apply text-lg font-semibold text-fg mb-8 pb-3 pt-4 border-b border-border sticky bg-bg z-[2];
+  top: var(--combined-header-height);
+}
+
+/* Individual symbol articles */
+.docs-content .docs-symbol {
+  @apply mb-10 pb-10 border-b border-border/30 last:border-0;
+}
+
+.docs-content .docs-symbol:target {
+  @apply scroll-mt-32;
+}
+
+.docs-content .docs-symbol:target .docs-symbol-header {
+  @apply bg-amber-500/10 -mx-3 px-3 py-1 rounded-md;
+}
+
+/* Symbol header (name + badges) */
+.docs-content .docs-symbol-header {
+  @apply flex items-center gap-3 mb-4 flex-wrap;
+}
+
+.docs-content .docs-anchor {
+  @apply text-fg-subtle/50 hover:text-fg-subtle transition-colors text-lg no-underline;
+}
+
+.docs-content .docs-symbol-name {
+  @apply font-mono text-lg font-semibold text-fg m-0;
+}
+
+/* Badges */
+.docs-content .docs-badge {
+  @apply text-xs px-2 py-0.5 rounded-full font-medium;
+}
+
+.docs-content .docs-badge--function {
+  @apply bg-blue-500/15 text-blue-400;
+}
+.docs-content .docs-badge--class {
+  @apply bg-amber-500/15 text-amber-400;
+}
+.docs-content .docs-badge--interface {
+  @apply bg-emerald-500/15 text-emerald-400;
+}
+.docs-content .docs-badge--typeAlias {
+  @apply bg-violet-500/15 text-violet-400;
+}
+.docs-content .docs-badge--variable {
+  @apply bg-orange-500/15 text-orange-400;
+}
+.docs-content .docs-badge--enum {
+  @apply bg-pink-500/15 text-pink-400;
+}
+.docs-content .docs-badge--namespace {
+  @apply bg-cyan-500/15 text-cyan-400;
+}
+.docs-content .docs-badge--async {
+  @apply bg-purple-500/15 text-purple-400;
+}
+
+/* Signature code block - now uses Shiki */
+.docs-content .docs-signature {
+  @apply mb-5;
+}
+
+.docs-content .docs-signature .shiki {
+  @apply text-sm bg-bg-muted/50 border border-border/50 p-4 rounded-lg;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docs-content .docs-signature .shiki code {
+  @apply text-sm;
+  white-space: pre-wrap;
+}
+
+/* Overload count badge */
+.docs-content .docs-overload-count {
+  @apply text-xs text-fg-subtle;
+}
+
+/* More overloads indicator */
+.docs-content .docs-more-overloads {
+  @apply text-xs text-fg-subtle italic mt-2 mb-0;
+}
+
+/* Description text */
+.docs-content .docs-description {
+  @apply text-sm text-fg-muted leading-relaxed mb-5;
+}
+
+/* Inline code in descriptions */
+.docs-content .docs-description code {
+  @apply bg-bg-muted px-1.5 py-0.5 rounded text-xs font-mono;
+}
+
+/*
+ * Fenced code blocks in descriptions use a subtle left-border style.
+ *
+ * Design rationale: We use two visual styles for code examples:
+ * 1. Boxed style (bg + border + padding) - for formal @example JSDoc tags
+ *    and function signatures. These are intentional, structured sections.
+ * 2. Left-border style (blockquote-like) - for inline code in descriptions.
+ *    These are illustrative/casual and shouldn't compete with the signature.
+ */
+.docs-content .docs-description .shiki {
+  @apply text-sm pl-4 py-3 my-4 border-l-2 border-border;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docs-content .docs-description .shiki code {
+  @apply text-sm bg-transparent p-0;
+  white-space: pre-wrap;
+}
+
+/* Deprecation warning */
+.docs-content .docs-deprecated {
+  @apply bg-amber-500/10 border border-amber-500/20 rounded-lg p-4 mb-5;
+}
+
+.docs-content .docs-deprecated strong {
+  @apply text-amber-400 text-sm;
+}
+
+.docs-content .docs-deprecated p {
+  @apply text-amber-300/80 text-sm mt-2 mb-0;
+}
+
+/* Parameters, Returns, Examples, See Also sections */
+.docs-content .docs-params,
+.docs-content .docs-returns,
+.docs-content .docs-examples,
+.docs-content .docs-see,
+.docs-content .docs-members {
+  @apply mb-5;
+}
+
+.docs-content .docs-params h4,
+.docs-content .docs-returns h4,
+.docs-content .docs-examples h4,
+.docs-content .docs-see h4,
+.docs-content .docs-members h4 {
+  @apply text-xs font-semibold text-fg-subtle uppercase tracking-wider mb-3;
+}
+
+/* Definition lists for params/members */
+.docs-content dl {
+  @apply space-y-2;
+}
+
+.docs-content dt {
+  @apply font-mono text-sm text-fg-muted;
+}
+
+.docs-content dd {
+  @apply text-sm text-fg-subtle ml-4 mb-3;
+}
+
+/* Returns paragraph */
+.docs-content .docs-returns p {
+  @apply text-sm text-fg-muted m-0;
+}
+
+/* Example code blocks from @example JSDoc tags - boxed style (see design rationale above) */
+.docs-content .docs-examples .shiki {
+  @apply text-sm bg-bg-muted border border-border/50 p-4 rounded-lg overflow-x-auto mb-3;
+}
+
+.docs-content .docs-examples .shiki code {
+  @apply text-sm;
+}
+
+/* See also list */
+.docs-content .docs-see ul {
+  @apply list-disc list-inside text-sm text-fg-muted space-y-1;
+}
+
+.docs-content .docs-link {
+  @apply text-blue-400 hover:text-blue-300 underline underline-offset-2;
+}
+
+/* Symbol cross-reference links */
+.docs-content .docs-symbol-link {
+  @apply text-emerald-400 hover:text-emerald-300 underline underline-offset-2;
+}
+
+/* Unknown symbol references shown as code */
+.docs-content .docs-symbol-ref {
+  @apply bg-bg-muted px-1.5 py-0.5 rounded text-xs font-mono;
+}
+
+/* Inline code in descriptions */
+.docs-content .docs-inline-code {
+  @apply bg-bg-muted px-1.5 py-0.5 rounded text-xs font-mono;
+}
+
+/* Enum members */
+.docs-content .docs-enum-members {
+  @apply flex flex-wrap gap-2 list-none p-0;
+}
+
+.docs-content .docs-enum-members li {
+  @apply m-0;
+}
+
+.docs-content .docs-enum-members code {
+  @apply text-sm font-mono text-fg-muted bg-bg-muted px-2 py-1 rounded;
+}
+
+/* Members section (constructors, properties, methods) */
+.docs-content .docs-members pre {
+  @apply text-sm bg-bg-muted/50 border border-border/50 p-3 rounded-lg overflow-x-auto font-mono;
+}
+
+.docs-content .docs-members pre code {
+  @apply text-fg-muted;
+}
+</style>

i18n/locales/en.json

···
       "issues": "issues",
       "forks": "fork | forks",
       "jsr": "jsr",
-      "code": "code"
+      "code": "code",
+      "docs": "docs"
     },
     "install": {
       "title": "Install",

nuxt.config.ts

···
   compatibilityDate: '2024-04-03',
 
   nitro: {
+    experimental: {
+      wasm: true,
+    },
     externals: {
       inline: [
         'shiki',
···
         '@shikijs/engine-javascript',
         '@shikijs/core',
       ],
+      external: ['@deno/doc'],
+    },
+    rollupConfig: {
+      output: {
+        paths: {
+          '@deno/doc': '@jsr/deno__doc',
+        },
+      },
     },
     // Storage configuration for local development
     // In production (Vercel), this is overridden by modules/cache.ts

package.json

···
     "test:unit": "vite test --project unit"
   },
   "dependencies": {
+    "@deno/doc": "jsr:^0.189.1",
     "@iconify-json/simple-icons": "^1.2.67",
     "@iconify-json/vscode-icons": "^1.2.40",
     "@nuxt/a11y": "1.0.0-alpha.1",
···
     "vite-plus": "latest",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
     "vue-tsc": "3.2.2"
+  },
+  "pnpm": {
+    "patchedDependencies": {
+      "@jsr/deno__doc@0.189.1": "patches/@[e-mail]"
+    }
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"

patches/@[e-mail]

···
+diff --git a/deno_doc_wasm.generated.js b/deno_doc_wasm.generated.js
+index 12add85709ae8a235058c751c397893693f52a6a..da235f2e0ce35b9fc012a51495a15c84d024e434 100755
+--- a/deno_doc_wasm.generated.js
++++ b/deno_doc_wasm.generated.js
+@@ -1012,13 +1012,18 @@ class WasmBuildLoader {
+ 
+     // make file urls work in Node via dnt
+     const isNode = globalThis.process?.versions?.node != null;
+-    if (isFile && typeof Deno !== "object") {
+-      throw new Error(
+-        "Loading local files are not supported in this environment",
++    if (isNode && isFile) {
++      // Use Node.js fs module to read the file (patched for Node.js support)
++      const { readFileSync } = await import("node:fs");
++      const { fileURLToPath } = await import("node:url");
++      const wasmCode = readFileSync(fileURLToPath(url));
++      return WebAssembly.instantiate(
++        decompress ? decompress(wasmCode) : wasmCode,
++        imports,
+       );
+     }
+-    if (isNode && isFile) {
+-      // the deno global will be shimmed by dnt
++    if (isFile && typeof Deno === "object") {
++      // Deno environment
+       const wasmCode = await Deno.readFile(url);
+       return WebAssembly.instantiate(
+         decompress ? decompress(wasmCode) : wasmCode,
+diff --git a/mod.js b/mod.js
+index f9d9de1349c2bb575b29138a5fc54654e92c4a47..025ecdb580b52160f709b32bb5db9ecf481e70ce 100755
+--- a/mod.js
++++ b/mod.js
+@@ -1,8 +1,8 @@
+ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+ import { instantiate } from "./deno_doc_wasm.generated.js";
+ import { createCache } from "@jsr/deno__cache-dir";
+-export * from "./types.d.ts";
+-export * from "./html_types.d.ts";
++// Removed: export * from "./types.d.ts"; (incompatible with Node.js/Rollup)
++// Removed: export * from "./html_types.d.ts"; (incompatible with Node.js/Rollup)
+ const encoder = new TextEncoder();
+ /**
+  * Generate asynchronously an array of documentation nodes for the supplied

pnpm-lock.yaml

···
 
 packageExtensionsChecksum: sha256-MLpDvxkp40Q0pRGkcNzUeHJyjDQFfGfxm/iGkXRnXJg=
 
+patchedDependencies:
+  '@jsr/deno__doc@0.189.1':
+    hash: 24f326e123c822a07976329a5afe91a8713e82d53134b5586625b72431c87832
+    path: patches/@[e-mail]
+
 importers:
 
   .:
     dependencies:
+      '@deno/doc':
+        specifier: jsr:^0.189.1
+        version: '@jsr/deno__doc@0.189.1(patch_hash=24f326e123c822a07976329a5afe91a8713e82d53134b5586625b72431c87832)'
       '@iconify-json/simple-icons':
         specifier: ^1.2.67
         version: 1.2.68
···
 
   '@jsdevtools/ono@7.1.3':
     resolution: {integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==}
+
+  '@jsr/deno__cache-dir@0.25.0':
+    resolution: {integrity: sha512-J5/kPR8sc+dsRyE8rnLPhqay7B4XgBmkv7QaeIV41sGibszQjIb8b599LssN1YWBbqPLakPRMVobg5u6LheWfg==, tarball: https://npm.jsr.io/~/11/@jsr/deno__cache-dir/0.25.0.tgz}
+
+  '@jsr/deno__doc@0.189.1':
+    resolution: {integrity: sha512-GtlJz3nGX1zF+XBG5pEPYdRbo5feyP3eM1+zsEqFqjfvT/nfRdjyGNogEs4yd+DW8cD7tQceRd2vypDhG1X7kA==, tarball: https://npm.jsr.io/~/11/@jsr/deno__doc/0.189.1.tgz}
+
+  '@jsr/deno__graph@0.100.1':
+    resolution: {integrity: sha512-mPemftpdwtz8fo+RNKujjXKpDQRcj5E0nOcxeNiDGLRzqQk/Q69IcGM4ruZGX+0xhTNNSLc8Uu3W4ynIDfTR6g==, tarball: https://npm.jsr.io/~/11/@jsr/deno__graph/0.100.1.tgz}
+
+  '@jsr/deno__graph@0.86.9':
+    resolution: {integrity: sha512-+qrrma5/bL+hcG20mfaEeC8SLopqoyd1RjcKFMRu++3SAXyrTKuvuIjBJCn/NyN7X+kV+QrJG67BCHX38Rzw+g==, tarball: https://npm.jsr.io/~/11/@jsr/deno__graph/0.86.9.tgz}
+
+  '@jsr/std__bytes@1.0.6':
+    resolution: {integrity: sha512-St6yKggjFGhxS52IFLJWvkchRFbAKg2Xh8UxA4S1EGz7GJ2Ui+ssDDldj/w2c8vCxvl6qgR0HaYbKeFJNqujmA==, tarball: https://npm.jsr.io/~/11/@jsr/std__bytes/1.0.6.tgz}
+
+  '@jsr/std__fmt@1.0.9':
+    resolution: {integrity: sha512-YFJJMozmORj2K91c5J9opWeh0VUwrd+Mwb7Pr0FkVCAKVLu2UhT4LyvJqWiyUT+eF+MdfqQ9F7RtQj4bXn9Smw==, tarball: https://npm.jsr.io/~/11/@jsr/std__fmt/1.0.9.tgz}
+
+  '@jsr/std__fs@1.0.22':
+    resolution: {integrity: sha512-PvDtgT25IqhFEX2LjQI0aTz/Wg61jCtJ8l19fE9MUSvSmtw57Kzr6sM7GcCsSrsZEdQ7wjLfXvvhy8irta4Zww==, tarball: https://npm.jsr.io/~/11/@jsr/std__fs/1.0.22.tgz}
+
+  '@jsr/std__internal@1.0.12':
+    resolution: {integrity: sha512-6xReMW9p+paJgqoFRpOE2nogJFvzPfaLHLIlyADYjKMUcwDyjKZxryIbgcU+gxiTygn8yCjld1HoI0ET4/iZeA==, tarball: https://npm.jsr.io/~/11/@jsr/std__internal/1.0.12.tgz}
+
+  '@jsr/std__io@0.225.2':
+    resolution: {integrity: sha512-QNImMbao6pKXvV4xpFkY2zviZi1r+1KpYzgMqaa2gHDPZhXQqlia/Og+VqMxxfAr8Pw6BF3tw/hSw3LrWWTRmA==, tarball: https://npm.jsr.io/~/11/@jsr/std__io/0.225.2.tgz}
+
+  '@jsr/std__path@1.1.4':
+    resolution: {integrity: sha512-SK4u9H6NVTfolhPdlvdYXfNFefy1W04AEHWJydryYbk+xqzNiVmr5o7TLJLJFqwHXuwMRhwrn+mcYeUfS0YFaA==, tarball: https://npm.jsr.io/~/11/@jsr/std__path/1.1.4.tgz}
 
   '@kwsites/file-exists@1.1.1':
     resolution: {integrity: sha512-m9/5YGR18lIwxSFDwfE3oA7bWuq9kdau6ugN4H2rJeyhFQZcG9AgSHkQtSD15a8WvTgfz9aikZMrKPHvbpqFiw==}
···
       '@jridgewell/sourcemap-codec': 1.5.5
 
   '@jsdevtools/ono@7.1.3': {}
+
+  '@jsr/deno__cache-dir@0.25.0':
+    dependencies:
+      '@jsr/deno__graph': 0.86.9
+      '@jsr/std__fmt': 1.0.9
+      '@jsr/std__fs': 1.0.22
+      '@jsr/std__io': 0.225.2
+      '@jsr/std__path': 1.1.4
+
+  '@jsr/deno__doc@0.189.1(patch_hash=24f326e123c822a07976329a5afe91a8713e82d53134b5586625b72431c87832)':
+    dependencies:
+      '@jsr/deno__cache-dir': 0.25.0
+      '@jsr/deno__graph': 0.100.1
+
+  '@jsr/deno__graph@0.100.1': {}
+
+  '@jsr/deno__graph@0.86.9': {}
+
+  '@jsr/std__bytes@1.0.6': {}
+
+  '@jsr/std__fmt@1.0.9': {}
+
+  '@jsr/std__fs@1.0.22':
+    dependencies:
+      '@jsr/std__internal': 1.0.12
+      '@jsr/std__path': 1.1.4
+
+  '@jsr/std__internal@1.0.12': {}
+
+  '@jsr/std__io@0.225.2':
+    dependencies:
+      '@jsr/std__bytes': 1.0.6
+
+  '@jsr/std__path@1.1.4':
+    dependencies:
+      '@jsr/std__internal': 1.0.12
 
   '@kwsites/file-exists@1.1.1':
     dependencies:

server/api/registry/docs/[...pkg].get.ts

···
+import type { DocsResponse } from '#shared/types'
+import { fetchNpmPackage } from '#server/utils/npm'
+import { assertValidPackageName } from '#shared/utils/npm'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
+import { generateDocsWithDeno } from '#server/utils/docs'
+
+export default defineCachedEventHandler(
+  async event => {
+    const pkgParam = getRouterParam(event, 'pkg')
+    if (!pkgParam) {
+      throw createError({ statusCode: 400, message: 'Package name is required' })
+    }
+
+    const { packageName, version: requestedVersion } = parsePackageParam(pkgParam)
+
+    if (!packageName) {
+      throw createError({ statusCode: 400, message: 'Package name is required' })
+    }
+    assertValidPackageName(packageName)
+
+    const packument = await fetchNpmPackage(packageName)
+    const version = requestedVersion ?? packument['dist-tags']?.latest
+
+    if (!version) {
+      throw createError({ statusCode: 404, message: 'No latest version found' })
+    }
+
+    let generated
+    try {
+      generated = await generateDocsWithDeno(packageName, version)
+    } catch (error) {
+      console.error(`Doc generation failed for ${packageName}@${version}:`, error)
+      return {
+        package: packageName,
+        version,
+        html: '',
+        toc: null,
+        status: 'error',
+        message: 'Failed to generate documentation. Please try again later.',
+      } satisfies DocsResponse
+    }
+
+    if (!generated) {
+      return {
+        package: packageName,
+        version,
+        html: '',
+        toc: null,
+        status: 'missing',
+        message: 'Docs are not available for this package. It may not have TypeScript types.',
+      } satisfies DocsResponse
+    }
+
+    return {
+      package: packageName,
+      version,
+      html: generated.html,
+      toc: generated.toc,
+      status: 'ok',
+    } satisfies DocsResponse
+  },
+  {
+    maxAge: 60 * 60, // 1 hour cache
+    swr: true,
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `docs:v1:${pkg}`
+    },
+  },
+)

server/utils/code-highlight.ts

···
         theme: 'github-dark',
       })
 
+      // Shiki doesn't encode > in text content (e.g., arrow functions)
+      html = escapeRawGt(html)
+
       // Make import statements clickable for JS/TS languages
       if (IMPORT_LANGUAGES.has(language)) {
         html = linkifyImports(html, {

server/utils/docs/client.ts

···
+/**
+ * Deno Integration (WASM)
+ *
+ * Uses @deno/doc (WASM build of deno_doc) for documentation generation.
+ * This runs entirely in Node.js without requiring a Deno subprocess.
+ *
+ * @module server/utils/docs/client
+ */
+
+import { doc } from '@deno/doc'
+import type { DenoDocNode, DenoDocResult } from '#shared/types/deno-doc'
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/** Timeout for fetching modules in milliseconds */
+const FETCH_TIMEOUT_MS = 30 * 1000
+
+// =============================================================================
+// Main Export
+// =============================================================================
+
+/**
+ * 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)
+
+  if (!typesUrl) {
+    return { version: 1, nodes: [] }
+  }
+
+  // Generate docs using @deno/doc WASM
+  const result = await doc([typesUrl], {
+    load: createLoader(),
+    resolve: createResolver(),
+  })
+
+  // Collect all nodes from all specifiers
+  const allNodes: DenoDocNode[] = []
+  for (const nodes of Object.values(result)) {
+    allNodes.push(...(nodes as DenoDocNode[]))
+  }
+
+  return { version: 1, nodes: allNodes }
+}
+
+// =============================================================================
+// Module Loading
+// =============================================================================
+
+/** Load response for the doc() function */
+interface LoadResponse {
+  kind: 'module'
+  specifier: string
+  headers?: Record<string, string>
+  content: string
+}
+
+/**
+ * Create a custom module loader for @deno/doc.
+ *
+ * Fetches modules from URLs using fetch(), with proper timeout handling.
+ */
+function createLoader(): (
+  specifier: string,
+  isDynamic?: boolean,
+  cacheSetting?: string,
+  checksum?: string,
+) => Promise<LoadResponse | undefined> {
+  return async (
+    specifier: string,
+    _isDynamic?: boolean,
+    _cacheSetting?: string,
+    _checksum?: string,
+  ) => {
+    let url: URL
+    try {
+      url = new URL(specifier)
+    } catch {
+      return undefined
+    }
+
+    // Only handle http/https URLs
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return undefined
+    }
+
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+
+    try {
+      const response = await fetch(url.toString(), {
+        redirect: 'follow',
+        signal: controller.signal,
+      })
+      clearTimeout(timeoutId)
+
+      if (response.status !== 200) {
+        return undefined
+      }
+
+      const content = await response.text()
+      const headers: Record<string, string> = {}
+      for (const [key, value] of response.headers) {
+        headers[key.toLowerCase()] = value
+      }
+
+      return {
+        kind: 'module',
+        specifier: response.url,
+        headers,
+        content,
+      }
+    } catch {
+      clearTimeout(timeoutId)
+      return undefined
+    }
+  }
+}
+
+/**
+ * Create a module resolver for @deno/doc.
+ *
+ * Handles resolving relative imports and esm.sh redirects.
+ */
+function createResolver(): (specifier: string, referrer: string) => string {
+  return (specifier: string, referrer: string) => {
+    // Handle relative imports
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+      return new URL(specifier, referrer).toString()
+    }
+
+    // Handle bare specifiers - resolve through esm.sh
+    if (!specifier.startsWith('http://') && !specifier.startsWith('https://')) {
+      // Try to resolve bare specifier relative to esm.sh base
+      const baseUrl = new URL(referrer)
+      if (baseUrl.hostname === 'esm.sh') {
+        return `https://esm.sh/${specifier}`
+      }
+    }
+
+    return specifier
+  }
+}
+
+/**
+ * Get the TypeScript types URL from esm.sh's x-typescript-types header.
+ *
+ * esm.sh serves types URL in the `x-typescript-types` header, not at the main URL.
+ * 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}`
+
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+
+  try {
+    const response = await fetch(url, {
+      method: 'HEAD',
+      signal: controller.signal,
+    })
+    clearTimeout(timeoutId)
+    return response.headers.get('x-typescript-types')
+  } catch {
+    clearTimeout(timeoutId)
+    return null
+  }
+}

server/utils/docs/format.ts

···
+/**
+ * Signature Formatting
+ *
+ * Functions for formatting TypeScript signatures, parameters, and types.
+ *
+ * @module server/utils/docs/format
+ */
+
+import type { DenoDocNode, FunctionParam, TsType } from '#shared/types/deno-doc'
+import { cleanSymbolName, stripAnsi } from './text'
+
+/**
+ * Generate a TypeScript signature string for a node.
+ */
+export function getNodeSignature(node: DenoDocNode): string | null {
+  const name = cleanSymbolName(node.name)
+
+  switch (node.kind) {
+    case 'function': {
+      const typeParams = node.functionDef?.typeParams?.map(t => t.name).join(', ')
+      const typeParamsStr = typeParams ? `<${typeParams}>` : ''
+      const params = node.functionDef?.params?.map(p => formatParam(p)).join(', ') || ''
+      const ret = formatType(node.functionDef?.returnType) || 'void'
+      const asyncStr = node.functionDef?.isAsync ? 'async ' : ''
+      return `${asyncStr}function ${name}${typeParamsStr}(${params}): ${ret}`
+    }
+    case 'class': {
+      const ext = node.classDef?.extends ? ` extends ${formatType(node.classDef.extends)}` : ''
+      const impl = node.classDef?.implements?.map(t => formatType(t)).join(', ')
+      const implStr = impl ? ` implements ${impl}` : ''
+      const abstractStr = node.classDef?.isAbstract ? 'abstract ' : ''
+      return `${abstractStr}class ${name}${ext}${implStr}`
+    }
+    case 'interface': {
+      const typeParams = node.interfaceDef?.typeParams?.map(t => t.name).join(', ')
+      const typeParamsStr = typeParams ? `<${typeParams}>` : ''
+      const ext = node.interfaceDef?.extends?.map(t => formatType(t)).join(', ')
+      const extStr = ext ? ` extends ${ext}` : ''
+      return `interface ${name}${typeParamsStr}${extStr}`
+    }
+    case 'typeAlias': {
+      const typeParams = node.typeAliasDef?.typeParams?.map(t => t.name).join(', ')
+      const typeParamsStr = typeParams ? `<${typeParams}>` : ''
+      const type = formatType(node.typeAliasDef?.tsType) || 'unknown'
+      return `type ${name}${typeParamsStr} = ${type}`
+    }
+    case 'variable': {
+      const keyword = node.variableDef?.kind === 'const' ? 'const' : 'let'
+      const type = formatType(node.variableDef?.tsType) || 'unknown'
+      return `${keyword} ${name}: ${type}`
+    }
+    case 'enum': {
+      return `enum ${name}`
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * Format a function parameter.
+ */
+export function formatParam(param: FunctionParam): string {
+  const optional = param.optional ? '?' : ''
+  const type = formatType(param.tsType)
+  return type ? `${param.name}${optional}: ${type}` : `${param.name}${optional}`
+}
+
+/**
+ * Format a TypeScript type.
+ */
+export function formatType(type?: TsType): string {
+  if (!type) return ''
+
+  // Strip ANSI codes from repr (deno doc may include terminal colors since it's built for that)
+  if (type.repr) return stripAnsi(type.repr)
+
+  if (type.kind === 'keyword' && type.keyword) {
+    return type.keyword
+  }
+
+  if (type.kind === 'typeRef' && type.typeRef) {
+    const params = type.typeRef.typeParams?.map(t => formatType(t)).join(', ')
+    return params ? `${type.typeRef.typeName}<${params}>` : type.typeRef.typeName
+  }
+
+  if (type.kind === 'array' && type.array) {
+    return `${formatType(type.array)}[]`
+  }
+
+  if (type.kind === 'union' && type.union) {
+    return type.union.map(t => formatType(t)).join(' | ')
+  }
+
+  return type.repr ? stripAnsi(type.repr) : 'unknown'
+}

server/utils/docs/index.ts

···
+/**
+ * API Documentation Generator
+ *
+ * Generates TypeScript API documentation for npm packages.
+ * Uses esm.sh to resolve package types, which handles @types/* packages automatically.
+ * Uses @deno/doc (WASM build of deno_doc) for documentation generation.
+ *
+ * @module server/utils/docs
+ */
+
+import type { DocsGenerationResult } from '#shared/types/deno-doc'
+import { getDocNodes } from './client'
+import { buildSymbolLookup, flattenNamespaces, mergeOverloads } from './processing'
+import { renderDocNodes, renderToc } from './render'
+
+/**
+ * Generate API documentation for an npm package.
+ *
+ * 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")
+ * @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,
+): Promise<DocsGenerationResult | null> {
+  // Get doc nodes using @deno/doc WASM
+  const result = await getDocNodes(packageName, version)
+
+  if (!result.nodes || result.nodes.length === 0) {
+    return null
+  }
+
+  // Process nodes: flatten namespaces, merge overloads, and build lookup
+  const flattenedNodes = flattenNamespaces(result.nodes)
+  const mergedSymbols = mergeOverloads(flattenedNodes)
+  const symbolLookup = buildSymbolLookup(flattenedNodes)
+
+  // Render HTML and TOC from pre-computed merged symbols
+  const html = await renderDocNodes(mergedSymbols, symbolLookup)
+  const toc = renderToc(mergedSymbols)
+
+  return { html, toc, nodes: flattenedNodes }
+}

server/utils/docs/processing.ts

···
+/**
+ * Node Processing
+ *
+ * Functions for processing deno doc output: flattening namespaces,
+ * merging overloads, and building symbol lookups.
+ *
+ * @module server/utils/docs/processing
+ */
+
+import type { DenoDocNode } from '#shared/types/deno-doc'
+import type { MergedSymbol, SymbolLookup } from './types'
+import { cleanSymbolName, createSymbolId } from './text'
+
+/**
+ * Flatten namespace elements into top-level nodes for easier display.
+ * Also filters out import/reference nodes that aren't useful for docs.
+ */
+export function flattenNamespaces(nodes: DenoDocNode[]): DenoDocNode[] {
+  const result: DenoDocNode[] = []
+
+  for (const node of nodes) {
+    // Skip internal nodes
+    if (node.kind === 'import' || node.kind === 'reference') {
+      continue
+    }
+
+    result.push(node)
+
+    // Inline namespace members with qualified names
+    if (node.kind === 'namespace' && node.namespaceDef?.elements) {
+      for (const element of node.namespaceDef.elements) {
+        result.push({
+          ...element,
+          name: `${node.name}.${element.name}`,
+        })
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Build a lookup table mapping symbol names to their HTML anchor IDs.
+ * Used for {@link} cross-references.
+ */
+export function buildSymbolLookup(nodes: DenoDocNode[]): SymbolLookup {
+  const lookup = new Map<string, string>()
+
+  for (const node of nodes) {
+    const cleanName = cleanSymbolName(node.name)
+    const id = createSymbolId(node.kind, cleanName)
+    lookup.set(cleanName, id)
+  }
+
+  return lookup
+}
+
+/**
+ * Merge function/method overloads into single entries.
+ *
+ * TypeScript packages often export many overloads for the same function
+ * (e.g., React's `h` has 23 overloads). This groups them together.
+ */
+export function mergeOverloads(nodes: DenoDocNode[]): MergedSymbol[] {
+  const byKey = new Map<string, DenoDocNode[]>()
+
+  for (const node of nodes) {
+    const cleanName = cleanSymbolName(node.name)
+    const key = `${node.kind}:${cleanName}`
+    const existing = byKey.get(key)
+    if (existing) {
+      existing.push(node)
+    } else {
+      byKey.set(key, [node])
+    }
+  }
+
+  const result: MergedSymbol[] = []
+
+  for (const [, groupedNodes] of byKey) {
+    const first = groupedNodes[0]
+    if (!first) continue // Should never happen, but defensive programming etc
+
+    // Use JSDoc from the best-documented overload
+    const withDoc = groupedNodes.find(n => n.jsDoc?.doc) ?? first
+
+    result.push({
+      name: cleanSymbolName(first.name),
+      kind: first.kind,
+      nodes: groupedNodes,
+      jsDoc: withDoc.jsDoc,
+    })
+  }
+
+  // Sort alphabetically
+  result.sort((a, b) => a.name.localeCompare(b.name))
+
+  return result
+}
+
+/**
+ * Group merged symbols by their kind (function, class, etc.)
+ */
+export function groupMergedByKind(symbols: MergedSymbol[]): Record<string, MergedSymbol[]> {
+  const grouped: Record<string, MergedSymbol[]> = {}
+
+  for (const sym of symbols) {
+    const kindGroup = (grouped[sym.kind] ??= [])
+    kindGroup.push(sym)
+  }
+
+  return grouped
+}

server/utils/docs/render.ts

···
+/**
+ * HTML Rendering
+ *
+ * Functions for rendering documentation nodes as HTML.
+ *
+ * @module server/utils/docs/render
+ */
+
+import type { DenoDocNode, JsDocTag } from '#shared/types/deno-doc'
+import { highlightCodeBlock } from '../shiki'
+import { formatParam, formatType, getNodeSignature } from './format'
+import { groupMergedByKind } from './processing'
+import { createSymbolId, escapeHtml, parseJsDocLinks, renderMarkdown } from './text'
+import type { MergedSymbol, SymbolLookup } from './types'
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/** Maximum number of overload signatures to display per symbol */
+const MAX_OVERLOAD_SIGNATURES = 5
+
+/** Maximum number of items to show in TOC per category before truncating */
+const MAX_TOC_ITEMS_PER_KIND = 50
+
+/** Order in which symbol kinds are displayed */
+const KIND_DISPLAY_ORDER = [
+  'function',
+  'class',
+  'interface',
+  'typeAlias',
+  'variable',
+  'enum',
+  'namespace',
+] as const
+
+/** Human-readable titles for symbol kinds */
+const KIND_TITLES: Record<string, string> = {
+  function: 'Functions',
+  class: 'Classes',
+  interface: 'Interfaces',
+  typeAlias: 'Type Aliases',
+  variable: 'Variables',
+  enum: 'Enums',
+  namespace: 'Namespaces',
+}
+
+// =============================================================================
+// Main Rendering Functions
+// =============================================================================
+
+/**
+ * Render all documentation nodes as HTML.
+ */
+export async function renderDocNodes(
+  symbols: MergedSymbol[],
+  symbolLookup: SymbolLookup,
+): Promise<string> {
+  const grouped = groupMergedByKind(symbols)
+  const sections: string[] = []
+
+  for (const kind of KIND_DISPLAY_ORDER) {
+    const kindSymbols = grouped[kind]
+    if (!kindSymbols || kindSymbols.length === 0) continue
+
+    sections.push(await renderKindSection(kind, kindSymbols, symbolLookup))
+  }
+
+  return sections.join('\n')
+}
+
+/**
+ * Render a section for a specific symbol kind.
+ */
+async function renderKindSection(
+  kind: string,
+  symbols: MergedSymbol[],
+  symbolLookup: SymbolLookup,
+): Promise<string> {
+  const title = KIND_TITLES[kind] || kind
+  const lines: string[] = []
+
+  lines.push(`<section class="docs-section" id="section-${kind}">`)
+  lines.push(`<h2 class="docs-section-title">${title}</h2>`)
+
+  for (const symbol of symbols) {
+    lines.push(await renderMergedSymbol(symbol, symbolLookup))
+  }
+
+  lines.push(`</section>`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Render a merged symbol (with all its overloads).
+ */
+async function renderMergedSymbol(
+  symbol: MergedSymbol,
+  symbolLookup: SymbolLookup,
+): Promise<string> {
+  const primaryNode = symbol.nodes[0]
+  if (!primaryNode) return '' // Safety check - should never happen
+
+  const lines: string[] = []
+  const id = createSymbolId(symbol.kind, symbol.name)
+  const hasOverloads = symbol.nodes.length > 1
+
+  lines.push(`<article class="docs-symbol" id="${id}">`)
+
+  // Header
+  lines.push(`<header class="docs-symbol-header">`)
+  lines.push(
+    `<a href="#${id}" class="docs-anchor" aria-label="Link to ${escapeHtml(symbol.name)}">#</a>`,
+  )
+  lines.push(`<h3 class="docs-symbol-name">${escapeHtml(symbol.name)}</h3>`)
+  lines.push(`<span class="docs-badge docs-badge--${symbol.kind}">${symbol.kind}</span>`)
+  if (primaryNode.functionDef?.isAsync) {
+    lines.push(`<span class="docs-badge docs-badge--async">async</span>`)
+  }
+  if (hasOverloads) {
+    lines.push(`<span class="docs-overload-count">${symbol.nodes.length} overloads</span>`)
+  }
+  lines.push(`</header>`)
+
+  // Signatures
+  const signatures = symbol.nodes
+    .slice(0, hasOverloads ? MAX_OVERLOAD_SIGNATURES : 1)
+    .map(n => getNodeSignature(n))
+    .filter(Boolean) as string[]
+
+  if (signatures.length > 0) {
+    const signatureCode = signatures.join('\n')
+    const highlightedSignature = await highlightCodeBlock(signatureCode, 'typescript')
+    lines.push(`<div class="docs-signature">${highlightedSignature}</div>`)
+
+    if (symbol.nodes.length > MAX_OVERLOAD_SIGNATURES) {
+      const remaining = symbol.nodes.length - MAX_OVERLOAD_SIGNATURES
+      lines.push(`<p class="docs-more-overloads">+ ${remaining} more overloads</p>`)
+    }
+  }
+
+  // Description
+  if (symbol.jsDoc?.doc) {
+    const description = symbol.jsDoc.doc.trim()
+    lines.push(
+      `<div class="docs-description">${await renderMarkdown(description, symbolLookup)}</div>`,
+    )
+  }
+
+  // JSDoc tags
+  if (symbol.jsDoc?.tags && symbol.jsDoc.tags.length > 0) {
+    lines.push(await renderJsDocTags(symbol.jsDoc.tags, symbolLookup))
+  }
+
+  // Type-specific members
+  if (symbol.kind === 'class' && primaryNode.classDef) {
+    lines.push(renderClassMembers(primaryNode.classDef))
+  } else if (symbol.kind === 'interface' && primaryNode.interfaceDef) {
+    lines.push(renderInterfaceMembers(primaryNode.interfaceDef))
+  } else if (symbol.kind === 'enum' && primaryNode.enumDef) {
+    lines.push(renderEnumMembers(primaryNode.enumDef))
+  }
+
+  lines.push(`</article>`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Render JSDoc tags (params, returns, examples, etc.)
+ */
+async function renderJsDocTags(tags: JsDocTag[], symbolLookup: SymbolLookup): Promise<string> {
+  const lines: string[] = []
+
+  const params = tags.filter(t => t.kind === 'param')
+  const returns = tags.find(t => t.kind === 'return')
+  const examples = tags.filter(t => t.kind === 'example')
+  const deprecated = tags.find(t => t.kind === 'deprecated')
+  const see = tags.filter(t => t.kind === 'see')
+
+  // Deprecated warning
+  if (deprecated) {
+    lines.push(`<div class="docs-deprecated">`)
+    lines.push(`<strong>Deprecated</strong>`)
+    if (deprecated.doc) {
+      lines.push(`<p>${parseJsDocLinks(deprecated.doc, symbolLookup)}</p>`)
+    }
+    lines.push(`</div>`)
+  }
+
+  // Parameters
+  if (params.length > 0) {
+    lines.push(`<div class="docs-params">`)
+    lines.push(`<h4>Parameters</h4>`)
+    lines.push(`<dl>`)
+    for (const param of params) {
+      lines.push(
+        `<dt><code>${escapeHtml(param.name || '')}${param.optional ? '?' : ''}</code></dt>`,
+      )
+      if (param.doc) {
+        lines.push(`<dd>${parseJsDocLinks(param.doc, symbolLookup)}</dd>`)
+      }
+    }
+    lines.push(`</dl>`)
+    lines.push(`</div>`)
+  }
+
+  // Returns
+  if (returns?.doc) {
+    lines.push(`<div class="docs-returns">`)
+    lines.push(`<h4>Returns</h4>`)
+    lines.push(`<p>${parseJsDocLinks(returns.doc, symbolLookup)}</p>`)
+    lines.push(`</div>`)
+  }
+
+  // Examples (with syntax highlighting)
+  if (examples.length > 0) {
+    lines.push(`<div class="docs-examples">`)
+    lines.push(`<h4>Example${examples.length > 1 ? 's' : ''}</h4>`)
+    for (const example of examples) {
+      if (example.doc) {
+        const langMatch = example.doc.match(/```(\w+)?/)
+        const lang = langMatch?.[1] || 'typescript'
+        const code = example.doc.replace(/```\w*\n?/g, '').trim()
+        const highlighted = await highlightCodeBlock(code, lang)
+        lines.push(highlighted)
+      }
+    }
+    lines.push(`</div>`)
+  }
+
+  // See also
+  if (see.length > 0) {
+    lines.push(`<div class="docs-see">`)
+    lines.push(`<h4>See Also</h4>`)
+    lines.push(`<ul>`)
+    for (const s of see) {
+      if (s.doc) {
+        lines.push(`<li>${parseJsDocLinks(s.doc, symbolLookup)}</li>`)
+      }
+    }
+    lines.push(`</ul>`)
+    lines.push(`</div>`)
+  }
+
+  return lines.join('\n')
+}
+
+// =============================================================================
+// Member Rendering
+// =============================================================================
+
+/**
+ * Render class members (constructor, properties, methods).
+ */
+function renderClassMembers(def: NonNullable<DenoDocNode['classDef']>): string {
+  const lines: string[] = []
+  const { constructors, properties, methods } = def
+
+  if (constructors && constructors.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Constructor</h4>`)
+    for (const ctor of constructors) {
+      const params = ctor.params?.map(p => formatParam(p)).join(', ') || ''
+      lines.push(`<pre><code>constructor(${escapeHtml(params)})</code></pre>`)
+    }
+    lines.push(`</div>`)
+  }
+
+  if (properties && properties.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Properties</h4>`)
+    lines.push(`<dl>`)
+    for (const prop of properties) {
+      const modifiers: string[] = []
+      if (prop.isStatic) modifiers.push('static')
+      if (prop.readonly) modifiers.push('readonly')
+      const modStr = modifiers.length > 0 ? `${modifiers.join(' ')} ` : ''
+      const type = formatType(prop.tsType)
+      const opt = prop.optional ? '?' : ''
+      lines.push(
+        `<dt><code>${escapeHtml(modStr)}${escapeHtml(prop.name)}${opt}: ${escapeHtml(type)}</code></dt>`,
+      )
+      if (prop.jsDoc?.doc) {
+        lines.push(`<dd>${escapeHtml(prop.jsDoc.doc.split('\n')[0] ?? '')}</dd>`)
+      }
+    }
+    lines.push(`</dl>`)
+    lines.push(`</div>`)
+  }
+
+  if (methods && methods.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Methods</h4>`)
+    lines.push(`<dl>`)
+    for (const method of methods) {
+      const params = method.functionDef?.params?.map(p => formatParam(p)).join(', ') || ''
+      const ret = formatType(method.functionDef?.returnType) || 'void'
+      const staticStr = method.isStatic ? 'static ' : ''
+      lines.push(
+        `<dt><code>${escapeHtml(staticStr)}${escapeHtml(method.name)}(${escapeHtml(params)}): ${escapeHtml(ret)}</code></dt>`,
+      )
+      if (method.jsDoc?.doc) {
+        lines.push(`<dd>${escapeHtml(method.jsDoc.doc.split('\n')[0] ?? '')}</dd>`)
+      }
+    }
+    lines.push(`</dl>`)
+    lines.push(`</div>`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Render interface members (properties, methods).
+ */
+function renderInterfaceMembers(def: NonNullable<DenoDocNode['interfaceDef']>): string {
+  const lines: string[] = []
+  const { properties, methods } = def
+
+  if (properties && properties.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Properties</h4>`)
+    lines.push(`<dl>`)
+    for (const prop of properties) {
+      const type = formatType(prop.tsType)
+      const opt = prop.optional ? '?' : ''
+      const ro = prop.readonly ? 'readonly ' : ''
+      lines.push(
+        `<dt><code>${escapeHtml(ro)}${escapeHtml(prop.name)}${opt}: ${escapeHtml(type)}</code></dt>`,
+      )
+      if (prop.jsDoc?.doc) {
+        lines.push(`<dd>${escapeHtml(prop.jsDoc.doc.split('\n')[0] ?? '')}</dd>`)
+      }
+    }
+    lines.push(`</dl>`)
+    lines.push(`</div>`)
+  }
+
+  if (methods && methods.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Methods</h4>`)
+    lines.push(`<dl>`)
+    for (const method of methods) {
+      const params = method.params?.map(p => formatParam(p)).join(', ') || ''
+      const ret = formatType(method.returnType) || 'void'
+      lines.push(
+        `<dt><code>${escapeHtml(method.name)}(${escapeHtml(params)}): ${escapeHtml(ret)}</code></dt>`,
+      )
+      if (method.jsDoc?.doc) {
+        lines.push(`<dd>${escapeHtml(method.jsDoc.doc.split('\n')[0] ?? '')}</dd>`)
+      }
+    }
+    lines.push(`</dl>`)
+    lines.push(`</div>`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Render enum members.
+ */
+function renderEnumMembers(def: NonNullable<DenoDocNode['enumDef']>): string {
+  const lines: string[] = []
+  const { members } = def
+
+  if (members && members.length > 0) {
+    lines.push(`<div class="docs-members">`)
+    lines.push(`<h4>Members</h4>`)
+    lines.push(`<ul class="docs-enum-members">`)
+    for (const member of members) {
+      lines.push(`<li><code>${escapeHtml(member.name)}</code></li>`)
+    }
+    lines.push(`</ul>`)
+    lines.push(`</div>`)
+  }
+
+  return lines.join('\n')
+}
+
+// =============================================================================
+// Table of Contents
+// =============================================================================
+
+/**
+ * Render table of contents.
+ */
+export function renderToc(symbols: MergedSymbol[]): string {
+  const grouped = groupMergedByKind(symbols)
+  const lines: string[] = []
+
+  lines.push(`<nav class="toc text-sm" aria-label="Table of contents">`)
+  lines.push(`<ul class="space-y-3">`)
+
+  for (const kind of KIND_DISPLAY_ORDER) {
+    const kindSymbols = grouped[kind]
+    if (!kindSymbols || kindSymbols.length === 0) continue
+
+    const title = KIND_TITLES[kind] || kind
+    lines.push(`<li>`)
+    lines.push(
+      `<a href="#section-${kind}" class="font-semibold text-fg-muted hover:text-fg block mb-1">${title} <span class="text-fg-subtle font-normal">(${kindSymbols.length})</span></a>`,
+    )
+
+    const showSymbols = kindSymbols.slice(0, MAX_TOC_ITEMS_PER_KIND)
+    lines.push(`<ul class="pl-3 space-y-0.5 border-l border-border/50">`)
+    for (const symbol of showSymbols) {
+      const id = createSymbolId(symbol.kind, symbol.name)
+      lines.push(
+        `<li><a href="#${id}" class="text-fg-subtle hover:text-fg font-mono text-xs block py-0.5 truncate">${escapeHtml(symbol.name)}</a></li>`,
+      )
+    }
+    if (kindSymbols.length > MAX_TOC_ITEMS_PER_KIND) {
+      const remaining = kindSymbols.length - MAX_TOC_ITEMS_PER_KIND
+      lines.push(`<li class="text-fg-subtle text-xs py-0.5">... and ${remaining} more</li>`)
+    }
+    lines.push(`</ul>`)
+
+    lines.push(`</li>`)
+  }
+
+  lines.push(`</ul>`)
+  lines.push(`</nav>`)
+
+  return lines.join('\n')
+}

server/utils/docs/text.ts

···
+/**
+ * Text Processing Utilities
+ *
+ * Functions for escaping HTML, parsing JSDoc links, and rendering markdown.
+ *
+ * @module server/utils/docs/text
+ */
+
+import { highlightCodeBlock } from '../shiki'
+import type { SymbolLookup } from './types'
+
+/**
+ * Strip ANSI escape codes from text.
+ * Deno doc output may contain terminal color codes that need to be removed.
+ */
+const ESC = String.fromCharCode(27)
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, 'g')
+
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_PATTERN, '')
+}
+
+/**
+ * Escape HTML special characters.
+ *
+ * @internal Exported for testing
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Clean up symbol names by stripping esm.sh prefixes.
+ *
+ * Packages using @types/* definitions get "default." or "default_" prefixes
+ * from esm.sh that we need to remove for clean display.
+ */
+export function cleanSymbolName(name: string): string {
+  if (name.startsWith('default.')) {
+    return name.slice(8)
+  }
+  if (name.startsWith('default_')) {
+    return name.slice(8)
+  }
+  return name
+}
+
+/**
+ * Create a URL-safe HTML anchor ID for a symbol.
+ */
+export function createSymbolId(kind: string, name: string): string {
+  return `${kind}-${name}`.replace(/[^a-zA-Z0-9-]/g, '_')
+}
+
+/**
+ * Parse JSDoc {@link} tags into HTML links.
+ *
+ * Handles:
+ * - {@link https://example.com} - external URL
+ * - {@link https://example.com Link Text} - external URL with label
+ * - {@link SomeSymbol} - internal cross-reference
+ *
+ * @internal Exported for testing
+ */
+export function parseJsDocLinks(text: string, symbolLookup: SymbolLookup): string {
+  let result = escapeHtml(text)
+
+  result = result.replace(/\{@link\s+([^\s}]+)(?:\s+([^}]+))?\}/g, (_, target, label) => {
+    const displayText = label || target
+
+    // External URL
+    if (target.startsWith('http://') || target.startsWith('https://')) {
+      return `<a href="${target}" target="_blank" rel="noopener" class="docs-link">${displayText}</a>`
+    }
+
+    // Internal symbol reference
+    const symbolId = symbolLookup.get(target)
+    if (symbolId) {
+      return `<a href="#${symbolId}" class="docs-symbol-link">${displayText}</a>`
+    }
+
+    // Unknown symbol
+    return `<code class="docs-symbol-ref">${displayText}</code>`
+  })
+
+  return result
+}
+
+/**
+ * Render simple markdown-like formatting.
+ * Uses <br> for line breaks to avoid nesting issues with inline elements.
+ * Fenced code blocks (```) are syntax-highlighted with Shiki.
+ *
+ * @internal Exported for testing
+ */
+export async function renderMarkdown(text: string, symbolLookup: SymbolLookup): Promise<string> {
+  // Extract fenced code blocks FIRST (before any HTML escaping)
+  // Pattern handles:
+  // - Optional whitespace before/after language identifier
+  // - \r\n, \n, or \r line endings
+  const codeBlockData: Array<{ lang: string; code: string }> = []
+  let result = text.replace(
+    /```[ \t]*(\w*)[ \t]*(?:\r\n|\r|\n)([\s\S]*?)(?:\r\n|\r|\n)?```/g,
+    (_, lang, code) => {
+      const index = codeBlockData.length
+      codeBlockData.push({ lang: lang || 'text', code: code.trim() })
+      return `__CODE_BLOCK_${index}__`
+    },
+  )
+
+  // Now process the rest (JSDoc links, HTML escaping, etc.)
+  result = parseJsDocLinks(result, symbolLookup)
+
+  // Handle inline code (single backticks) - won't interfere with fenced blocks
+  result = result
+    .replace(/`([^`]+)`/g, '<code class="docs-inline-code">$1</code>')
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\n\n+/g, '<br><br>')
+    .replace(/\n/g, '<br>')
+
+  // Highlight and restore code blocks
+  for (let i = 0; i < codeBlockData.length; i++) {
+    const { lang, code } = codeBlockData[i]!
+    const highlighted = await highlightCodeBlock(code, lang)
+    result = result.replace(`__CODE_BLOCK_${i}__`, highlighted)
+  }
+
+  return result
+}

server/utils/docs/types.ts

···
+/**
+ * Internal Types for Docs Module
+ * These are highly coupled to `deno doc`, hence they live here instead of shared types.
+ *
+ * @module server/utils/docs/types
+ */
+
+import type { DenoDocNode } from '#shared/types/deno-doc'
+
+/**
+ * Map of symbol names to anchor IDs for cross-referencing.
+ * @internal Exported for testing
+ */
+export type SymbolLookup = Map<string, string>
+
+/**
+ * Symbol with merged overloads
+ */
+export interface MergedSymbol {
+  name: string
+  kind: string
+  nodes: DenoDocNode[]
+  jsDoc?: DenoDocNode['jsDoc']
+}

server/utils/readme.ts

···
 import { hasProtocol } from 'ufo'
 import type { ReadmeResponse } from '#shared/types/readme'
 import { convertBlobToRawUrl, type RepositoryInfo } from '#shared/utils/git-providers'
+import { highlightCodeSync } from './shiki'
 
 /**
  * Playground provider configuration
···
 
   // Syntax highlighting for code blocks (uses shared highlighter)
   renderer.code = ({ text, lang }: Tokens.Code) => {
-    const language = lang || 'text'
-    const loadedLangs = shiki.getLoadedLanguages()
-
-    // Use Shiki if language is loaded, otherwise fall back to plain
-    if (loadedLangs.includes(language as never)) {
-      try {
-        return shiki.codeToHtml(text, {
-          lang: language,
-          theme: 'github-dark',
-        })
-      } catch {
-        // Fall back to plain code block
-      }
-    }
-
-    // Plain code block for unknown languages
-    const escaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    return `<pre><code class="language-${language}">${escaped}</code></pre>\n`
+    return highlightCodeSync(shiki, text, lang || 'text')
   }
 
   // Resolve image URLs (with GitHub blob → raw conversion)

server/utils/shiki.ts

···
   return highlighter
 }
 
-export async function highlightCodeBlock(code: string, language: string): Promise<string> {
-  const shiki = await getShikiHighlighter()
+/**
+ * Synchronously highlight a code block using an already-initialized highlighter.
+ * Use this when you have already awaited getShikiHighlighter() and need to
+ * highlight multiple blocks without async overhead (e.g., in marked renderers).
+ *
+ * @param shiki - The initialized Shiki highlighter instance
+ * @param code - The code to highlight
+ * @param language - The language identifier (e.g., 'typescript', 'bash')
+ * @returns HTML string with syntax highlighting
+ */
+export function highlightCodeSync(shiki: HighlighterCore, code: string, language: string): string {
   const loadedLangs = shiki.getLoadedLanguages()
 
   if (loadedLangs.includes(language as never)) {
     try {
-      return shiki.codeToHtml(code, {
+      let html = shiki.codeToHtml(code, {
         lang: language,
         theme: 'github-dark',
       })
+      // Remove inline style from <pre> tag so CSS can control appearance
+      html = html.replace(/<pre([^>]*)\s+style="[^"]*"/, '<pre$1')
+      // Shiki doesn't encode > in text content (e.g., arrow functions =>)
+      // We need to encode them for HTML validation
+      return escapeRawGt(html)
     } catch {
       // Fall back to plain
     }
···
   const escaped = code.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
   return `<pre><code class="language-${language}">${escaped}</code></pre>\n`
 }
+
+/**
+ * Highlight a code block with syntax highlighting (async convenience wrapper).
+ * Initializes the highlighter if needed, then delegates to highlightCodeSync.
+ *
+ * @param code - The code to highlight
+ * @param language - The language identifier (e.g., 'typescript', 'bash')
+ * @returns HTML string with syntax highlighting
+ */
+export async function highlightCodeBlock(code: string, language: string): Promise<string> {
+  const shiki = await getShikiHighlighter()
+  return highlightCodeSync(shiki, code, language)
+}
+
+/**
+ * Escape raw > characters in HTML text content.
+ * Shiki outputs > without encoding in constructs like arrow functions (=>).
+ * This replaces > that appear in text content (after >) but not inside tags.
+ *
+ * @internal Exported for testing
+ */
+export function escapeRawGt(html: string): string {
+  // Match > that appears after a closing tag or other > (i.e., in text content)
+  // Pattern: after </...> or after >, match any > that isn't starting a tag
+  return html.replace(/>([^<]*)/g, (match, textContent) => {
+    // Encode any > in the text content portion
+    const escapedText = textContent.replace(/>/g, '&gt;')
+    return `>${escapedText}`
+  })
+}

shared/types/deno-doc.ts

···
+/**
+ * Types for deno doc JSON output.
+ *
+ * These types represent the structure of the JSON output from `deno doc --json`.
+ * In an ideal world, we'd generate these or implement our own AST / parser.
+ * That might be an endgame, but there's a lot of value in using deno's implementation, too.
+ * Well trodden ground and all that.
+ *
+ * @see: https://deno.land/x/deno_doc
+ */
+
+/** JSDoc tag from deno doc output */
+export interface JsDocTag {
+  kind: string
+  name?: string
+  doc?: string
+  optional?: boolean
+  type?: string
+}
+
+/** TypeScript type representation from deno doc */
+export interface TsType {
+  repr: string
+  kind: string
+  keyword?: string
+  typeRef?: {
+    typeName: string
+    typeParams?: TsType[] | null
+  }
+  array?: TsType
+  union?: TsType[]
+  literal?: {
+    kind: string
+    string?: string
+    number?: number
+    boolean?: boolean
+  }
+}
+
+/** Function parameter from deno doc */
+export interface FunctionParam {
+  kind: string
+  name: string
+  optional?: boolean
+  tsType?: TsType
+}
+
+/** A documentation node from deno doc output */
+export interface DenoDocNode {
+  name: string
+  kind: string
+  isDefault?: boolean
+  location?: {
+    filename: string
+    line: number
+    col: number
+  }
+  declarationKind?: string
+  jsDoc?: {
+    doc?: string
+    tags?: JsDocTag[]
+  }
+  functionDef?: {
+    params?: FunctionParam[]
+    returnType?: TsType
+    isAsync?: boolean
+    isGenerator?: boolean
+    typeParams?: Array<{ name: string }>
+  }
+  classDef?: {
+    isAbstract?: boolean
+    properties?: Array<{
+      name: string
+      tsType?: TsType
+      readonly?: boolean
+      optional?: boolean
+      isStatic?: boolean
+      jsDoc?: { doc?: string }
+    }>
+    methods?: Array<{
+      name: string
+      isStatic?: boolean
+      functionDef?: {
+        params?: FunctionParam[]
+        returnType?: TsType
+      }
+      jsDoc?: { doc?: string }
+    }>
+    constructors?: Array<{
+      params?: FunctionParam[]
+    }>
+    extends?: TsType
+    implements?: TsType[]
+  }
+  interfaceDef?: {
+    properties?: Array<{
+      name: string
+      tsType?: TsType
+      readonly?: boolean
+      optional?: boolean
+      jsDoc?: { doc?: string }
+    }>
+    methods?: Array<{
+      name: string
+      params?: FunctionParam[]
+      returnType?: TsType
+      jsDoc?: { doc?: string }
+    }>
+    extends?: TsType[]
+    typeParams?: Array<{ name: string }>
+  }
+  typeAliasDef?: {
+    tsType?: TsType
+    typeParams?: Array<{ name: string }>
+  }
+  variableDef?: {
+    tsType?: TsType
+    kind?: string
+  }
+  enumDef?: {
+    members?: Array<{ name: string; init?: TsType }>
+  }
+  namespaceDef?: {
+    elements?: DenoDocNode[]
+  }
+}
+
+/** Raw output from deno doc --json */
+export interface DenoDocResult {
+  version: number
+  nodes: DenoDocNode[]
+}
+
+/** Result of documentation generation */
+export interface DocsGenerationResult {
+  html: string
+  toc: string | null
+  nodes: DenoDocNode[]
+}

shared/types/docs.ts

···
+export type DocsStatus = 'ok' | 'missing' | 'error'
+
+export interface DocsResponse {
+  package: string
+  version: string
+  html: string
+  toc: string | null
+  breadcrumbs?: string | null
+  status: DocsStatus
+  message?: string
+}
+
+export interface DocsSearchResponse {
+  package: string
+  version: string
+  index: Record<string, unknown>
+}

shared/types/index.ts

···
 export * from './jsr'
 export * from './osv'
 export * from './readme'
+export * from './docs'
+export * from './deno-doc'

shared/utils/parse-package-param.ts

···
+/**
+ * Parsed package parameters from URL path segments.
+ */
+export interface ParsedPackageParams {
+  /** The npm package name (e.g., "vue", "@nuxt/kit") */
+  packageName: string
+  /** The version if specified (e.g., "3.4.0"), undefined otherwise */
+  version: string | undefined
+  /** Remaining path segments after the version (e.g., for file paths) */
+  rest: string[]
+}
+
+/**
+ * Parse package name, optional version, and remaining path from URL segments.
+ *
+ * Supports these URL patterns:
+ * - `/pkg` → { packageName: "pkg", version: undefined, rest: [] }
+ * - `/pkg/v/1.2.3` → { packageName: "pkg", version: "1.2.3", rest: [] }
+ * - `/pkg/v/1.2.3/src/index.ts` → { packageName: "pkg", version: "1.2.3", rest: ["src", "index.ts"] }
+ * - `/@scope/pkg` → { packageName: "@scope/pkg", version: undefined, rest: [] }
+ * - `/@scope/pkg/v/1.2.3` → { packageName: "@scope/pkg", version: "1.2.3", rest: [] }
+ *
+ * @param pkgParam - The raw package parameter from the URL (e.g., "vue/v/3.4.0/src/index.ts")
+ * @returns Parsed package name, optional version, and remaining path segments
+ *
+ * @example
+ * ```ts
+ * parsePackageParam('vue')
+ * // { packageName: 'vue', version: undefined, rest: [] }
+ *
+ * parsePackageParam('vue/v/3.4.0')
+ * // { packageName: 'vue', version: '3.4.0', rest: [] }
+ *
+ * parsePackageParam('@nuxt/kit/v/1.0.0/src/index.ts')
+ * // { packageName: '@nuxt/kit', version: '1.0.0', rest: ['src', 'index.ts'] }
+ * ```
+ */
+export function parsePackageParam(pkgParam: string): ParsedPackageParams {
+  const segments = pkgParam.split('/')
+  const vIndex = segments.indexOf('v')
+
+  if (vIndex !== -1 && vIndex < segments.length - 1) {
+    return {
+      packageName: segments.slice(0, vIndex).join('/'),
+      version: segments[vIndex + 1],
+      rest: segments.slice(vIndex + 2),
+    }
+  }
+
+  return {
+    packageName: segments.join('/'),
+    version: undefined,
+    rest: [],
+  }
+}

test/unit/docs-text.spec.ts

···
+import { describe, expect, it } from 'vitest'
+import {
+  escapeHtml,
+  parseJsDocLinks,
+  renderMarkdown,
+  stripAnsi,
+} from '../../server/utils/docs/text'
+import type { SymbolLookup } from '../../server/utils/docs/types'
+
+describe('stripAnsi', () => {
+  it('should strip basic color codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[0m${ESC}[38;5;12mhello${ESC}[0m`
+    expect(stripAnsi(input)).toBe('hello')
+  })
+
+  it('should strip multiple ANSI codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[31mred${ESC}[0m and ${ESC}[32mgreen${ESC}[0m`
+    expect(stripAnsi(input)).toBe('red and green')
+  })
+
+  it('should handle text without ANSI codes', () => {
+    expect(stripAnsi('plain text')).toBe('plain text')
+  })
+
+  it('should handle empty string', () => {
+    expect(stripAnsi('')).toBe('')
+  })
+
+  it('should strip 256-color codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[38;5;196mtext${ESC}[0m`
+    expect(stripAnsi(input)).toBe('text')
+  })
+
+  it('should handle type predicates from deno_doc', () => {
+    // Real example: "object is ReactElement<P>" with ANSI codes
+    const ESC = String.fromCharCode(27)
+    const input = `object is ReactElement${ESC}[0m${ESC}[38;5;12m<${ESC}[0mP${ESC}[38;5;12m>${ESC}[0m`
+    expect(stripAnsi(input)).toBe('object is ReactElement<P>')
+  })
+})
+
+describe('escapeHtml', () => {
+  it('should escape < and >', () => {
+    expect(escapeHtml('<script>')).toBe('&lt;script&gt;')
+  })
+
+  it('should escape &', () => {
+    expect(escapeHtml('foo & bar')).toBe('foo &amp; bar')
+  })
+
+  it('should escape quotes', () => {
+    expect(escapeHtml('"hello"')).toBe('&quot;hello&quot;')
+    expect(escapeHtml("'hello'")).toBe('&#39;hello&#39;')
+  })
+
+  it('should handle multiple special characters', () => {
+    expect(escapeHtml('<a href="test?a=1&b=2">')).toBe(
+      '&lt;a href=&quot;test?a=1&amp;b=2&quot;&gt;',
+    )
+  })
+
+  it('should return empty string for empty input', () => {
+    expect(escapeHtml('')).toBe('')
+  })
+
+  it('should not modify text without special characters', () => {
+    expect(escapeHtml('hello world')).toBe('hello world')
+  })
+})
+
+describe('parseJsDocLinks', () => {
+  const emptyLookup: SymbolLookup = new Map()
+
+  it('should convert external URLs to links', () => {
+    const result = parseJsDocLinks('{@link https://example.com}', emptyLookup)
+    expect(result).toContain('href="https://example.com"')
+    expect(result).toContain('target="_blank"')
+    expect(result).toContain('rel="noopener"')
+  })
+
+  it('should handle external URLs with labels', () => {
+    const result = parseJsDocLinks('{@link https://example.com Example Site}', emptyLookup)
+    expect(result).toContain('href="https://example.com"')
+    expect(result).toContain('>Example Site</a>')
+  })
+
+  it('should convert internal symbol references to anchor links', () => {
+    const lookup: SymbolLookup = new Map([['MyFunction', 'function-MyFunction']])
+    const result = parseJsDocLinks('{@link MyFunction}', lookup)
+    expect(result).toContain('href="#function-MyFunction"')
+    expect(result).toContain('docs-symbol-link')
+  })
+
+  it('should render unknown symbols as code', () => {
+    const result = parseJsDocLinks('{@link UnknownSymbol}', emptyLookup)
+    expect(result).toContain('<code class="docs-symbol-ref">UnknownSymbol</code>')
+  })
+
+  it('should escape HTML in surrounding text', () => {
+    const result = parseJsDocLinks('Use <T> with {@link https://example.com}', emptyLookup)
+    expect(result).toContain('&lt;T&gt;')
+  })
+
+  it('should handle multiple links', () => {
+    const result = parseJsDocLinks(
+      'See {@link https://a.com} and {@link https://b.com}',
+      emptyLookup,
+    )
+    expect(result).toContain('href="https://a.com"')
+    expect(result).toContain('href="https://b.com"')
+  })
+
+  it('should not convert non-http URLs to links', () => {
+    const result = parseJsDocLinks('{@link javascript:alert(1)}', emptyLookup)
+    // Should be treated as unknown symbol, not a link
+    expect(result).not.toContain('href="javascript:')
+    expect(result).toContain('<code')
+  })
+
+  it('should handle http URLs (not just https)', () => {
+    const result = parseJsDocLinks('{@link http://example.com}', emptyLookup)
+    expect(result).toContain('href="http://example.com"')
+  })
+})
+
+describe('renderMarkdown', () => {
+  const emptyLookup: SymbolLookup = new Map()
+
+  it('should convert inline code', async () => {
+    const result = await renderMarkdown('Use `foo()` here', emptyLookup)
+    expect(result).toContain('<code class="docs-inline-code">foo()</code>')
+  })
+
+  it('should escape HTML inside inline code', async () => {
+    const result = await renderMarkdown('Use `Array<T>` here', emptyLookup)
+    expect(result).toContain('&lt;T&gt;')
+    expect(result).not.toContain('<T>')
+  })
+
+  it('should convert bold text', async () => {
+    const result = await renderMarkdown('This is **important**', emptyLookup)
+    expect(result).toContain('<strong>important</strong>')
+  })
+
+  it('should convert single newlines to <br>', async () => {
+    const result = await renderMarkdown('line 1\nline 2', emptyLookup)
+    expect(result).toBe('line 1<br>line 2')
+  })
+
+  it('should convert double newlines to <br><br>', async () => {
+    const result = await renderMarkdown('paragraph 1\n\nparagraph 2', emptyLookup)
+    expect(result).toBe('paragraph 1<br><br>paragraph 2')
+  })
+
+  it('should handle multiple formatting in same text', async () => {
+    const result = await renderMarkdown('Use `foo()` for **important** tasks', emptyLookup)
+    expect(result).toContain('<code class="docs-inline-code">foo()</code>')
+    expect(result).toContain('<strong>important</strong>')
+  })
+
+  it('should process {@link} tags', async () => {
+    const lookup: SymbolLookup = new Map([['MyFunc', 'function-MyFunc']])
+    const result = await renderMarkdown('See {@link MyFunc} for details', lookup)
+    expect(result).toContain('href="#function-MyFunc"')
+  })
+
+  it('should escape HTML in regular text', async () => {
+    const result = await renderMarkdown('Returns <T> or null', emptyLookup)
+    expect(result).toContain('&lt;T&gt;')
+  })
+
+  it('should handle empty string', async () => {
+    expect(await renderMarkdown('', emptyLookup)).toBe('')
+  })
+
+  it('should handle text with only whitespace', async () => {
+    const result = await renderMarkdown('  \n  ', emptyLookup)
+    expect(result).toBe('  <br>  ')
+  })
+
+  it('should syntax highlight fenced code blocks with Shiki', async () => {
+    const input = '```ts\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Shiki outputs use class="shiki" and have syntax highlighting spans
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks with CRLF line endings', async () => {
+    const input = '```ts\r\nconst x = 1;\r\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks with CR line endings', async () => {
+    const input = '```ts\rconst x = 1;\r```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks without language', async () => {
+    const input = '```\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Falls back to plain code block for unknown language
+    expect(result).toContain('<pre>')
+    expect(result).toContain('const x = 1;')
+  })
+
+  it('should handle fenced code blocks with trailing whitespace after language', async () => {
+    const input = '```ts  \nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+  })
+
+  it('should handle fenced code blocks with space before language', async () => {
+    const input = '``` js\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should escape HTML inside fenced code blocks', async () => {
+    const input = '```ts\nconst arr: Array<string> = [];\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Shiki escapes < as &#x3C; (hex entity)
+    expect(result).toContain('&#x3C;')
+    // The raw < character shouldn't appear outside of HTML tags
+    expect(result).not.toMatch(/<string>/)
+  })
+
+  it('should handle multiple fenced code blocks', async () => {
+    const input = '```ts\nconst a = 1\n```\n\nSome text\n\n```js\nconst b = 2\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('Some text')
+    // Both code blocks should be highlighted
+    expect((result.match(/shiki/g) || []).length).toBe(2)
+  })
+
+  it('should not confuse inline code with fenced code blocks', async () => {
+    const input = 'Use `code` inline and:\n```ts\nblock code\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('<code class="docs-inline-code">code</code>')
+    expect(result).toContain('shiki')
+  })
+})

test/unit/parse-package-param.spec.ts

···
+import { describe, expect, it } from 'vitest'
+import { parsePackageParam } from '../../shared/utils/parse-package-param'
+
+describe('parsePackageParam', () => {
+  describe('unscoped packages', () => {
+    it('parses package name without version', () => {
+      const result = parsePackageParam('vue')
+      expect(result).toEqual({
+        packageName: 'vue',
+        version: undefined,
+        rest: [],
+      })
+    })
+
+    it('parses package name with version', () => {
+      const result = parsePackageParam('vue/v/3.4.0')
+      expect(result).toEqual({
+        packageName: 'vue',
+        version: '3.4.0',
+        rest: [],
+      })
+    })
+
+    it('parses package name with prerelease version', () => {
+      const result = parsePackageParam('nuxt/v/4.0.0-rc.1')
+      expect(result).toEqual({
+        packageName: 'nuxt',
+        version: '4.0.0-rc.1',
+        rest: [],
+      })
+    })
+
+    it('parses package name with version and file path', () => {
+      const result = parsePackageParam('vue/v/3.4.0/src/index.ts')
+      expect(result).toEqual({
+        packageName: 'vue',
+        version: '3.4.0',
+        rest: ['src', 'index.ts'],
+      })
+    })
+
+    it('parses package name with version and nested file path', () => {
+      const result = parsePackageParam('lodash/v/4.17.21/lib/fp/map.js')
+      expect(result).toEqual({
+        packageName: 'lodash',
+        version: '4.17.21',
+        rest: ['lib', 'fp', 'map.js'],
+      })
+    })
+  })
+
+  describe('scoped packages', () => {
+    it('parses scoped package name without version', () => {
+      const result = parsePackageParam('@nuxt/kit')
+      expect(result).toEqual({
+        packageName: '@nuxt/kit',
+        version: undefined,
+        rest: [],
+      })
+    })
+
+    it('parses scoped package name with version', () => {
+      const result = parsePackageParam('@nuxt/kit/v/1.0.0')
+      expect(result).toEqual({
+        packageName: '@nuxt/kit',
+        version: '1.0.0',
+        rest: [],
+      })
+    })
+
+    it('parses scoped package name with version and file path', () => {
+      const result = parsePackageParam('@vue/compiler-sfc/v/3.5.0/dist/index.d.ts')
+      expect(result).toEqual({
+        packageName: '@vue/compiler-sfc',
+        version: '3.5.0',
+        rest: ['dist', 'index.d.ts'],
+      })
+    })
+
+    it('parses deeply nested scoped packages', () => {
+      const result = parsePackageParam('@types/node/v/22.0.0')
+      expect(result).toEqual({
+        packageName: '@types/node',
+        version: '22.0.0',
+        rest: [],
+      })
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles package name that looks like a version marker', () => {
+      // Package named "v" shouldn't be confused with version separator
+      const result = parsePackageParam('v')
+      expect(result).toEqual({
+        packageName: 'v',
+        version: undefined,
+        rest: [],
+      })
+    })
+
+    it('handles version segment without actual version', () => {
+      // "v" at the end without a version after it
+      const result = parsePackageParam('vue/v')
+      expect(result).toEqual({
+        packageName: 'vue/v',
+        version: undefined,
+        rest: [],
+      })
+    })
+
+    it('handles package with "v" in the name followed by version', () => {
+      const result = parsePackageParam('vueuse/v/12.0.0')
+      expect(result).toEqual({
+        packageName: 'vueuse',
+        version: '12.0.0',
+        rest: [],
+      })
+    })
+
+    it('handles empty rest when file path is empty', () => {
+      const result = parsePackageParam('react/v/18.2.0')
+      expect(result.rest).toEqual([])
+      expect(result.rest.length).toBe(0)
+    })
+  })
+})

test/unit/shiki.spec.ts

···
+import { describe, expect, it } from 'vitest'
+import { escapeRawGt, highlightCodeBlock } from '../../server/utils/shiki'
+
+describe('escapeRawGt', () => {
+  it('should encode > in arrow functions', () => {
+    const input = '<span style="color:#F97583">=></span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span style="color:#F97583">=&gt;</span>')
+  })
+
+  it('should encode > in comparison operators', () => {
+    const input = '<span>x > 5</span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span>x &gt; 5</span>')
+  })
+
+  it('should encode multiple > in text content', () => {
+    const input = '<span>a > b > c</span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span>a &gt; b &gt; c</span>')
+  })
+
+  it('should not affect HTML tag structure', () => {
+    const input = '<span class="test"><code>text</code></span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span class="test"><code>text</code></span>')
+  })
+
+  it('should not affect attributes containing >', () => {
+    // Attributes with > are already encoded by Shiki, but test anyway
+    const input = '<span title="a &gt; b">text</span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span title="a &gt; b">text</span>')
+  })
+
+  it('should handle empty text content', () => {
+    const input = '<span></span><code></code>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span></span><code></code>')
+  })
+
+  it('should handle text without special characters', () => {
+    const input = '<span>hello world</span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span>hello world</span>')
+  })
+
+  it('should handle nested spans (Shiki output structure)', () => {
+    const input =
+      '<span class="line"><span style="color:#F97583">const</span><span> x = () =></span><span> 5</span></span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe(
+      '<span class="line"><span style="color:#F97583">const</span><span> x = () =&gt;</span><span> 5</span></span>',
+    )
+  })
+
+  it('should handle >= operator', () => {
+    const input = '<span>x >= 5</span>'
+    const output = escapeRawGt(input)
+    expect(output).toBe('<span>x &gt;= 5</span>')
+  })
+
+  it('should handle generic type syntax', () => {
+    const input = '<span>Array&lt;T></span>'
+    const output = escapeRawGt(input)
+    // The < is already encoded, the > should be encoded
+    expect(output).toBe('<span>Array&lt;T&gt;</span>')
+  })
+})
+
+describe('highlightCodeBlock', () => {
+  it('should highlight TypeScript code', async () => {
+    const code = 'const x = 1'
+    const html = await highlightCodeBlock(code, 'typescript')
+
+    expect(html).toContain('<pre')
+    expect(html).toContain('const')
+    expect(html).toContain('shiki')
+  })
+
+  it('should encode > in arrow functions', async () => {
+    const code = 'const fn = () => 5'
+    const html = await highlightCodeBlock(code, 'typescript')
+
+    // The > in => should be encoded
+    expect(html).toContain('=&gt;')
+    expect(html).not.toMatch(/=>(?!&)/) // no raw => (except in &gt;)
+  })
+
+  it('should encode > in generic types', async () => {
+    const code = 'const x: Array<string> = []'
+    const html = await highlightCodeBlock(code, 'typescript')
+
+    // Should have encoded >
+    expect(html).toContain('&gt;')
+  })
+
+  it('should fall back to plain code for unknown languages', async () => {
+    const code = 'some random code > with special < chars'
+    const html = await highlightCodeBlock(code, 'unknownlang123')
+
+    expect(html).toContain('&gt;')
+    expect(html).toContain('&lt;')
+    expect(html).toContain('language-unknownlang123')
+  })
+
+  it('should escape special characters in fallback', async () => {
+    const code = '<script>alert("xss")</script>'
+    const html = await highlightCodeBlock(code, 'unknownlang123')
+
+    expect(html).toContain('&lt;script&gt;')
+    expect(html).not.toContain('<script>')
+  })
+})

tests/docs.spec.ts

···
+import { expect, test } from '@nuxt/test-utils/playwright'
+
+test.describe('API Documentation Pages', () => {
+  test('docs page loads and shows content for a package', async ({ page, goto }) => {
+    // Use a small, stable package with TypeScript types
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Page title should include package name
+    await expect(page).toHaveTitle(/ufo.*docs/i)
+
+    // Header should show package name and version
+    await expect(page.locator('header').getByText('ufo')).toBeVisible()
+    await expect(page.locator('header').getByText('1.6.3')).toBeVisible()
+
+    // API Docs badge should be visible
+    await expect(page.locator('text=API Docs')).toBeVisible()
+
+    // Should have documentation content
+    const docsContent = page.locator('.docs-content')
+    await expect(docsContent).toBeVisible()
+
+    // Should have at least one function documented
+    await expect(page.locator('.docs-badge--function').first()).toBeVisible()
+  })
+
+  test('docs page shows TOC sidebar on desktop', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // TOC sidebar should be visible (on desktop viewport)
+    const tocSidebar = page.locator('aside')
+    await expect(tocSidebar).toBeVisible()
+
+    // Should have "Contents" heading
+    await expect(tocSidebar.getByText('Contents')).toBeVisible()
+
+    // Should have section links (Functions, etc.)
+    await expect(tocSidebar.locator('a[href="#section-function"]')).toBeVisible()
+  })
+
+  test('TOC links navigate to sections', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Click on Functions in TOC
+    const functionsLink = page.locator('aside a[href="#section-function"]')
+    await functionsLink.click()
+
+    // URL should have the hash
+    await expect(page).toHaveURL(/#section-function/)
+
+    // Section should be scrolled into view
+    const functionSection = page.locator('#section-function')
+    await expect(functionSection).toBeInViewport()
+  })
+
+  test('clicking symbol name scrolls to symbol', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Find a symbol link in the TOC
+    const symbolLink = page.locator('aside a[href^="#function-"]').first()
+    const href = await symbolLink.getAttribute('href')
+
+    // Click the symbol link
+    await symbolLink.click()
+
+    // URL should have the hash
+    await expect(page).toHaveURL(new RegExp(href!.replace('#', '#')))
+  })
+
+  test('docs page without version redirects to latest', async ({ page, goto }) => {
+    await goto('/docs/ufo', { waitUntil: 'networkidle' })
+
+    // Should redirect to include version
+    await expect(page).toHaveURL(/\/docs\/ufo\/v\//)
+  })
+
+  test('package link in header navigates to package page', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Click on package name in header
+    const packageLink = page.locator('header a').filter({ hasText: 'ufo' })
+    await packageLink.click()
+
+    // Should navigate to package page (URL ends with /ufo)
+    await expect(page).toHaveURL(/\/ufo$/)
+  })
+
+  test('docs page handles package gracefully when types unavailable', async ({ page, goto }) => {
+    // Use a simple JS package - the page should load without crashing
+    // regardless of whether it has types or shows an error state
+    await goto('/docs/is-odd/v/3.0.1', { waitUntil: 'networkidle' })
+
+    // Header should always show the package name
+    await expect(page.locator('header').getByText('is-odd')).toBeVisible()
+
+    // Page should be in one of two states:
+    // 1. Shows "not available" / error message
+    // 2. Shows actual docs content (if types were found)
+    const errorState = page.locator('text=/not available|could not generate/i')
+    const docsContent = page.locator('.docs-content')
+
+    // One of these should be visible
+    await expect(errorState.or(docsContent)).toBeVisible()
+  })
+})
+
+test.describe('Version Selector', () => {
+  test('version selector dropdown shows versions', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Find and click the version selector button
+    const versionButton = page.locator('header button').filter({ hasText: '1.6.3' })
+
+    // Skip if version selector not present (data might not be loaded)
+    if (!(await versionButton.isVisible())) {
+      test.skip()
+      return
+    }
+
+    await versionButton.click()
+
+    // Dropdown should appear with version options
+    const dropdown = page.locator('[role="listbox"]')
+    await expect(dropdown).toBeVisible()
+
+    // Should show multiple versions
+    const versionOptions = dropdown.locator('[role="option"]')
+    await expect(versionOptions.first()).toBeVisible()
+  })
+
+  test('selecting a version navigates to that version', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    // Find and click the version selector button
+    const versionButton = page.locator('header button').filter({ hasText: '1.6.3' })
+
+    // Skip if version selector not present
+    if (!(await versionButton.isVisible())) {
+      test.skip()
+      return
+    }
+
+    await versionButton.click()
+
+    // Find a different version and click it
+    const differentVersion = page.locator('[role="option"]').filter({ hasNotText: '1.6.3' }).first()
+
+    // Skip if no other versions available
+    if (!(await differentVersion.isVisible())) {
+      test.skip()
+      return
+    }
+
+    const versionText = await differentVersion.textContent()
+    await differentVersion.click()
+
+    // URL should change to the new version
+    if (versionText) {
+      const versionMatch = versionText.match(/\d+\.\d+\.\d+/)
+      if (versionMatch) {
+        await expect(page).toHaveURL(new RegExp(`/docs/ufo/v/${versionMatch[0]}`))
+      }
+    }
+  })
+
+  test('escape key closes version dropdown', async ({ page, goto }) => {
+    await goto('/docs/ufo/v/1.6.3', { waitUntil: 'networkidle' })
+
+    const versionButton = page.locator('header button').filter({ hasText: '1.6.3' })
+
+    if (!(await versionButton.isVisible())) {
+      test.skip()
+      return
+    }
+
+    await versionButton.click()
+
+    const dropdown = page.locator('[role="listbox"]')
+    await expect(dropdown).toBeVisible()
+
+    // Press escape
+    await page.keyboard.press('Escape')
+
+    // Dropdown should close
+    await expect(dropdown).not.toBeVisible()
+  })
+})