From 06136d9bb51a24726e2338073be60f82888f1930 Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 3 Feb 2026 10:34:27 +0000
Subject: [PATCH 1/4] chore: separate npm composables

Its getting messy and only going to get worse, so let's split them up.

This also moves the non-composables into `utils`.
---
 app/components/Org/MembersPanel.vue           |   2 +-
 app/components/Org/TeamsPanel.vue             |   2 +-
 app/components/Package/AccessControls.vue     |   2 +-
 app/components/Package/Dependencies.vue       |   2 +-
 app/components/Package/InstallScripts.vue     |   2 +
 app/components/Package/Versions.vue           |   2 +-
 app/components/VersionSelector.vue            |   2 +-
 app/composables/npm/useNpmSearch.ts           | 264 ++++++
 app/composables/npm/useOrgPackages.ts         | 163 ++++
 .../npm/useOutdatedDependencies.ts            | 132 +++
 app/composables/npm/usePackage.ts             | 116 +++
 app/composables/npm/usePackageDownloads.ts    |  29 +
 app/composables/npm/useResolvedVersion.ts     |  18 +
 app/composables/useNpmRegistry.ts             | 870 ------------------
 app/utils/npm/api.ts                          |  64 ++
 app/utils/{npm.ts => npm/common.ts}           |   3 +
 app/utils/npm/outdated-dependencies.ts        |  82 ++
 nuxt.config.ts                                |   4 +
 shared/types/npm-registry.ts                  |  13 +
 test/unit/app/utils/npm.spec.ts               |   2 +-
 20 files changed, 897 insertions(+), 877 deletions(-)
 create mode 100644 app/composables/npm/useNpmSearch.ts
 create mode 100644 app/composables/npm/useOrgPackages.ts
 create mode 100644 app/composables/npm/useOutdatedDependencies.ts
 create mode 100644 app/composables/npm/usePackage.ts
 create mode 100644 app/composables/npm/usePackageDownloads.ts
 create mode 100644 app/composables/npm/useResolvedVersion.ts
 delete mode 100644 app/composables/useNpmRegistry.ts
 create mode 100644 app/utils/npm/api.ts
 rename app/utils/{npm.ts => npm/common.ts} (80%)
 create mode 100644 app/utils/npm/outdated-dependencies.ts

diff --git a/app/components/Org/MembersPanel.vue b/app/components/Org/MembersPanel.vue
index 57d2abdf8..d8ca64645 100644
--- a/app/components/Org/MembersPanel.vue
+++ b/app/components/Org/MembersPanel.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { NewOperation } from '~/composables/useConnector'
-import { buildScopeTeam } from '~/utils/npm'
+import { buildScopeTeam } from '~/utils/npm/common'
 
 const props = defineProps<{
   orgName: string
diff --git a/app/components/Org/TeamsPanel.vue b/app/components/Org/TeamsPanel.vue
index 1726b079c..af0bd0bce 100644
--- a/app/components/Org/TeamsPanel.vue
+++ b/app/components/Org/TeamsPanel.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { NewOperation } from '~/composables/useConnector'
-import { buildScopeTeam } from '~/utils/npm'
+import { buildScopeTeam } from '~/utils/npm/common'
 
 const props = defineProps<{
   orgName: string
diff --git a/app/components/Package/AccessControls.vue b/app/components/Package/AccessControls.vue
index 95367af1f..ef23bef77 100644
--- a/app/components/Package/AccessControls.vue
+++ b/app/components/Package/AccessControls.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { NewOperation } from '~/composables/useConnector'
-import { buildScopeTeam } from '~/utils/npm'
+import { buildScopeTeam } from '~/utils/npm/common'
 
 const props = defineProps<{
   packageName: string
diff --git a/app/components/Package/Dependencies.vue b/app/components/Package/Dependencies.vue
index 7014b9570..ad19b9f4b 100644
--- a/app/components/Package/Dependencies.vue
+++ b/app/components/Package/Dependencies.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import { useDependencyAnalysis } from '~/composables/useDependencyAnalysis'
 import { SEVERITY_TEXT_COLORS, getHighestSeverity } from '#shared/utils/severity'
+import { getOutdatedTooltip, getVersionClass } from '~/utils/npm/outdated-dependencies'
 
 const props = defineProps<{
   packageName: string
diff --git a/app/components/Package/InstallScripts.vue b/app/components/Package/InstallScripts.vue
index b020fb9ad..7e70756c1 100644
--- a/app/components/Package/InstallScripts.vue
+++ b/app/components/Package/InstallScripts.vue
@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { getOutdatedTooltip, getVersionClass } from '~/utils/npm/outdated-dependencies'
+
 const props = defineProps<{
   packageName: string
   installScripts: {
diff --git a/app/components/Package/Versions.vue b/app/components/Package/Versions.vue
index 17c58e96f..491346b1b 100644
--- a/app/components/Package/Versions.vue
+++ b/app/components/Package/Versions.vue
@@ -2,7 +2,7 @@
 import type { PackageVersionInfo, SlimVersion } from '#shared/types'
 import { compare } from 'semver'
 import type { RouteLocationRaw } from 'vue-router'
-import { fetchAllPackageVersions } from '~/composables/useNpmRegistry'
+import { fetchAllPackageVersions } from '~/utils/npm/api'
 import {
   buildVersionToTagsMap,
   filterExcludedTags,
diff --git a/app/components/VersionSelector.vue b/app/components/VersionSelector.vue
index 0ea96652f..bc8a11ff2 100644
--- a/app/components/VersionSelector.vue
+++ b/app/components/VersionSelector.vue
@@ -9,7 +9,7 @@ import {
   getVersionGroupLabel,
   isSameVersionGroup,
 } from '~/utils/versions'
-import { fetchAllPackageVersions } from '~/composables/useNpmRegistry'
+import { fetchAllPackageVersions } from '~/utils/npm/api'
 
 const props = defineProps<{
   packageName: string
diff --git a/app/composables/npm/useNpmSearch.ts b/app/composables/npm/useNpmSearch.ts
new file mode 100644
index 000000000..c5ef3c687
--- /dev/null
+++ b/app/composables/npm/useNpmSearch.ts
@@ -0,0 +1,264 @@
+import type {
+  Packument,
+  NpmSearchResponse,
+  NpmSearchResult,
+  NpmDownloadCount,
+  MinimalPackument,
+} from '#shared/types'
+import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
+
+/**
+ * Convert packument to search result format for display
+ */
+export function packumentToSearchResult(
+  pkg: MinimalPackument,
+  weeklyDownloads?: number,
+): NpmSearchResult {
+  let latestVersion = ''
+  if (pkg['dist-tags']) {
+    latestVersion = pkg['dist-tags'].latest || Object.values(pkg['dist-tags'])[0] || ''
+  }
+  const modified = pkg.time.modified || pkg.time[latestVersion] || ''
+
+  return {
+    package: {
+      name: pkg.name,
+      version: latestVersion,
+      description: pkg.description,
+      keywords: pkg.keywords,
+      date: pkg.time[latestVersion] || modified,
+      links: {
+        npm: `https://www.npmjs.com/package/${pkg.name}`,
+      },
+      maintainers: pkg.maintainers,
+    },
+    score: { final: 0, detail: { quality: 0, popularity: 0, maintenance: 0 } },
+    searchScore: 0,
+    downloads: weeklyDownloads !== undefined ? { weekly: weeklyDownloads } : undefined,
+    updated: pkg.time[latestVersion] || modified,
+  }
+}
+
+export interface NpmSearchOptions {
+  /** Number of results to fetch */
+  size?: number
+}
+
+export const emptySearchResponse = {
+  objects: [],
+  total: 0,
+  isStale: false,
+  time: new Date().toISOString(),
+} satisfies NpmSearchResponse
+
+export function useNpmSearch(
+  query: MaybeRefOrGetter<string>,
+  options: MaybeRefOrGetter<NpmSearchOptions> = {},
+) {
+  const cachedFetch = useCachedFetch()
+  // Client-side cache
+  const cache = shallowRef<{
+    query: string
+    objects: NpmSearchResult[]
+    total: number
+  } | null>(null)
+
+  const isLoadingMore = shallowRef(false)
+
+  // Standard (non-incremental) search implementation
+  let lastSearch: NpmSearchResponse | undefined = undefined
+
+  const asyncData = useLazyAsyncData(
+    () => `search:incremental:${toValue(query)}`,
+    async (_nuxtApp, { signal }) => {
+      const q = toValue(query)
+
+      if (!q.trim()) {
+        return emptySearchResponse
+      }
+
+      const opts = toValue(options)
+
+      // This only runs for initial load or query changes
+      // Reset cache for new query
+      cache.value = null
+
+      const params = new URLSearchParams()
+      params.set('text', q)
+      // Use requested size for initial fetch
+      params.set('size', String(opts.size ?? 25))
+
+      if (q.length === 1) {
+        const encodedName = encodePackageName(q)
+        const [{ data: pkg, isStale }, { data: downloads }] = await Promise.all([
+          cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, { signal }),
+          cachedFetch<NpmDownloadCount>(`${NPM_API}/downloads/point/last-week/${encodedName}`, {
+            signal,
+          }),
+        ])
+
+        if (!pkg) {
+          return emptySearchResponse
+        }
+
+        const result = packumentToSearchResult(pkg, downloads?.downloads)
+
+        // If query changed/outdated, return empty search response
+        if (q !== toValue(query)) {
+          return emptySearchResponse
+        }
+
+        cache.value = {
+          query: q,
+          objects: [result],
+          total: 1,
+        }
+
+        return {
+          objects: [result],
+          total: 1,
+          isStale,
+          time: new Date().toISOString(),
+        }
+      }
+
+      const { data: response, isStale } = await cachedFetch<NpmSearchResponse>(
+        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+        { signal },
+        60,
+      )
+
+      // If query changed/outdated, return empty search response
+      if (q !== toValue(query)) {
+        return emptySearchResponse
+      }
+
+      cache.value = {
+        query: q,
+        objects: response.objects,
+        total: response.total,
+      }
+
+      return { ...response, isStale }
+    },
+    { default: () => lastSearch || emptySearchResponse },
+  )
+
+  // Fetch more results incrementally (only used in incremental mode)
+  async function fetchMore(targetSize: number): Promise<void> {
+    const q = toValue(query).trim()
+    if (!q) {
+      cache.value = null
+      return
+    }
+
+    // If query changed, reset cache (shouldn't happen, but safety check)
+    if (cache.value && cache.value.query !== q) {
+      cache.value = null
+      await asyncData.refresh()
+      return
+    }
+
+    const currentCount = cache.value?.objects.length ?? 0
+    const total = cache.value?.total ?? Infinity
+
+    // Already have enough or no more to fetch
+    if (currentCount >= targetSize || currentCount >= total) {
+      return
+    }
+
+    isLoadingMore.value = true
+
+    try {
+      // Fetch from where we left off - calculate size needed
+      const from = currentCount
+      const size = Math.min(targetSize - currentCount, total - currentCount)
+
+      const params = new URLSearchParams()
+      params.set('text', q)
+      params.set('size', String(size))
+      params.set('from', String(from))
+
+      const { data: response } = await cachedFetch<NpmSearchResponse>(
+        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+        {},
+        60,
+      )
+
+      // Update cache
+      if (cache.value && cache.value.query === q) {
+        const existingNames = new Set(cache.value.objects.map(obj => obj.package.name))
+        const newObjects = response.objects.filter(obj => !existingNames.has(obj.package.name))
+        cache.value = {
+          query: q,
+          objects: [...cache.value.objects, ...newObjects],
+          total: response.total,
+        }
+      } else {
+        cache.value = {
+          query: q,
+          objects: response.objects,
+          total: response.total,
+        }
+      }
+
+      // If we still need more, fetch again recursively
+      if (
+        cache.value.objects.length < targetSize &&
+        cache.value.objects.length < cache.value.total
+      ) {
+        await fetchMore(targetSize)
+      }
+    } finally {
+      isLoadingMore.value = false
+    }
+  }
+
+  // Watch for size increases in incremental mode
+  watch(
+    () => toValue(options).size,
+    async (newSize, oldSize) => {
+      if (!newSize) return
+      if (oldSize && newSize > oldSize && toValue(query).trim()) {
+        await fetchMore(newSize)
+      }
+    },
+  )
+
+  // Computed data that uses cache in incremental mode
+  const data = computed<NpmSearchResponse | null>(() => {
+    if (cache.value) {
+      return {
+        isStale: false,
+        objects: cache.value.objects,
+        total: cache.value.total,
+        time: new Date().toISOString(),
+      }
+    }
+    return asyncData.data.value
+  })
+
+  if (import.meta.client && asyncData.data.value?.isStale) {
+    onMounted(() => {
+      asyncData.refresh()
+    })
+  }
+
+  // Whether there are more results available on the server (incremental mode only)
+  const hasMore = computed(() => {
+    if (!cache.value) return true
+    return cache.value.objects.length < cache.value.total
+  })
+
+  return {
+    ...asyncData,
+    /** Reactive search results (uses cache in incremental mode) */
+    data,
+    /** Whether currently loading more results (incremental mode only) */
+    isLoadingMore,
+    /** Whether there are more results available (incremental mode only) */
+    hasMore,
+    /** Manually fetch more results up to target size (incremental mode only) */
+    fetchMore,
+  }
+}
diff --git a/app/composables/npm/useOrgPackages.ts b/app/composables/npm/useOrgPackages.ts
new file mode 100644
index 000000000..0dcb3f463
--- /dev/null
+++ b/app/composables/npm/useOrgPackages.ts
@@ -0,0 +1,163 @@
+import type { NpmSearchResponse, NpmSearchResult, MinimalPackument } from '#shared/types'
+import { emptySearchResponse, packumentToSearchResult } from './useNpmSearch'
+import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
+import { mapWithConcurrency } from '#shared/utils/async'
+
+/**
+ * Fetch downloads for multiple packages.
+ * Returns a map of package name -> weekly downloads.
+ * Uses bulk API for unscoped packages, parallel individual requests for scoped.
+ * Note: npm bulk downloads API does not support scoped packages.
+ */
+async function fetchBulkDownloads(
+  packageNames: string[],
+  options: Parameters<typeof $fetch>[1] = {},
+): Promise<Map<string, number>> {
+  const downloads = new Map<string, number>()
+  if (packageNames.length === 0) return downloads
+
+  // Separate scoped and unscoped packages
+  const scopedPackages = packageNames.filter(n => n.startsWith('@'))
+  const unscopedPackages = packageNames.filter(n => !n.startsWith('@'))
+
+  // Fetch unscoped packages via bulk API (max 128 per request)
+  const bulkPromises: Promise<void>[] = []
+  const chunkSize = 100
+  for (let i = 0; i < unscopedPackages.length; i += chunkSize) {
+    const chunk = unscopedPackages.slice(i, i + chunkSize)
+    bulkPromises.push(
+      (async () => {
+        try {
+          const response = await $fetch<Record<string, { downloads: number } | null>>(
+            `${NPM_API}/downloads/point/last-week/${chunk.join(',')}`,
+            options,
+          )
+          for (const [name, data] of Object.entries(response)) {
+            if (data?.downloads !== undefined) {
+              downloads.set(name, data.downloads)
+            }
+          }
+        } catch {
+          // Ignore errors - downloads are optional
+        }
+      })(),
+    )
+  }
+
+  // Fetch scoped packages in parallel batches (concurrency limit to avoid overwhelming the API)
+  // Use Promise.allSettled to not fail on individual errors
+  const scopedBatchSize = 20 // Concurrent requests per batch
+  for (let i = 0; i < scopedPackages.length; i += scopedBatchSize) {
+    const batch = scopedPackages.slice(i, i + scopedBatchSize)
+    bulkPromises.push(
+      (async () => {
+        const results = await Promise.allSettled(
+          batch.map(async name => {
+            const encoded = encodePackageName(name)
+            const data = await $fetch<{ downloads: number }>(
+              `${NPM_API}/downloads/point/last-week/${encoded}`,
+            )
+            return { name, downloads: data.downloads }
+          }),
+        )
+        for (const result of results) {
+          if (result.status === 'fulfilled' && result.value.downloads !== undefined) {
+            downloads.set(result.value.name, result.value.downloads)
+          }
+        }
+      })(),
+    )
+  }
+
+  // Wait for all fetches to complete
+  await Promise.all(bulkPromises)
+
+  return downloads
+}
+
+/**
+ * Fetch all packages for an npm organization
+ * Returns search-result-like objects for compatibility with PackageList
+ */
+export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
+  const cachedFetch = useCachedFetch()
+
+  const asyncData = useLazyAsyncData(
+    () => `org-packages:${toValue(orgName)}`,
+    async (_nuxtApp, { signal }) => {
+      const org = toValue(orgName)
+      if (!org) {
+        return emptySearchResponse
+      }
+
+      // Get all package names in the org
+      let packageNames: string[]
+      try {
+        const { data } = await cachedFetch<Record<string, string>>(
+          `${NPM_REGISTRY}/-/org/${encodeURIComponent(org)}/package`,
+          { signal },
+        )
+        packageNames = Object.keys(data)
+      } catch (err) {
+        // Check if this is a 404 (org not found)
+        if (err && typeof err === 'object' && 'statusCode' in err && err.statusCode === 404) {
+          throw createError({
+            statusCode: 404,
+            statusMessage: 'Organization not found',
+            message: `The organization "@${org}" does not exist on npm`,
+          })
+        }
+        // For other errors (network, etc.), return empty array to be safe
+        packageNames = []
+      }
+
+      if (packageNames.length === 0) {
+        return emptySearchResponse
+      }
+
+      // Fetch packuments and downloads in parallel
+      const [packuments, downloads] = await Promise.all([
+        // Fetch packuments with concurrency limit
+        (async () => {
+          const results = await mapWithConcurrency(
+            packageNames,
+            async name => {
+              try {
+                const encoded = encodePackageName(name)
+                const { data: pkg } = await cachedFetch<MinimalPackument>(
+                  `${NPM_REGISTRY}/${encoded}`,
+                  { signal },
+                )
+                return pkg
+              } catch {
+                return null
+              }
+            },
+            10,
+          )
+          // Filter out any unpublished packages (missing dist-tags)
+          return results.filter(
+            (pkg): pkg is MinimalPackument => pkg !== null && !!pkg['dist-tags'],
+          )
+        })(),
+        // Fetch downloads in bulk
+        fetchBulkDownloads(packageNames, { signal }),
+      ])
+
+      // Convert to search results with download data
+      const results: NpmSearchResult[] = packuments.map(pkg =>
+        packumentToSearchResult(pkg, downloads.get(pkg.name)),
+      )
+
+      return {
+        isStale: false,
+        objects: results,
+        total: results.length,
+        time: new Date().toISOString(),
+      } satisfies NpmSearchResponse
+    },
+    { default: () => emptySearchResponse },
+  )
+
+  return asyncData
+}
diff --git a/app/composables/npm/useOutdatedDependencies.ts b/app/composables/npm/useOutdatedDependencies.ts
new file mode 100644
index 000000000..8deee1321
--- /dev/null
+++ b/app/composables/npm/useOutdatedDependencies.ts
@@ -0,0 +1,132 @@
+import { maxSatisfying, prerelease, major, minor, diff, gt } from 'semver'
+import type { Packument } from '#shared/types'
+import { mapWithConcurrency } from '#shared/utils/async'
+import type { CachedFetchFunction } from '#shared/utils/fetch-cache-config'
+import {
+  type OutdatedDependencyInfo,
+  isNonSemverConstraint,
+  constraintIncludesPrerelease,
+} from '~/utils/npm/outdated-dependencies'
+
+// Cache for packument fetches to avoid duplicate requests across components
+const packumentCache = new Map<string, Promise<Packument | null>>()
+
+/**
+ * Check if a dependency is outdated.
+ * Returns null if up-to-date or if we can't determine.
+ */
+async function checkDependencyOutdated(
+  cachedFetch: CachedFetchFunction,
+  packageName: string,
+  constraint: string,
+): Promise<OutdatedDependencyInfo | null> {
+  if (isNonSemverConstraint(constraint)) {
+    return null
+  }
+
+  // Check in-memory cache first
+  let packument: Packument | null
+  const cached = packumentCache.get(packageName)
+  if (cached) {
+    packument = await cached
+  } else {
+    const promise = cachedFetch<Packument>(`${NPM_REGISTRY}/${encodePackageName(packageName)}`)
+      .then(({ data }) => data)
+      .catch(() => null)
+    packumentCache.set(packageName, promise)
+    packument = await promise
+  }
+
+  if (!packument) return null
+
+  const latestTag = packument['dist-tags']?.latest
+  if (!latestTag) return null
+
+  // Handle "latest" constraint specially - return info with current version
+  if (constraint === 'latest') {
+    return {
+      resolved: latestTag,
+      latest: latestTag,
+      majorsBehind: 0,
+      minorsBehind: 0,
+      diffType: null,
+    }
+  }
+
+  let versions = Object.keys(packument.versions)
+  const includesPrerelease = constraintIncludesPrerelease(constraint)
+
+  if (!includesPrerelease) {
+    versions = versions.filter(v => !prerelease(v))
+  }
+
+  const resolved = maxSatisfying(versions, constraint)
+  if (!resolved) return null
+
+  if (resolved === latestTag) return null
+
+  // If resolved version is newer than latest, not outdated
+  // (e.g., using ^2.0.0-rc when latest is 1.x)
+  if (gt(resolved, latestTag)) {
+    return null
+  }
+
+  const diffType = diff(resolved, latestTag)
+  const majorsBehind = major(latestTag) - major(resolved)
+  const minorsBehind = majorsBehind === 0 ? minor(latestTag) - minor(resolved) : 0
+
+  return {
+    resolved,
+    latest: latestTag,
+    majorsBehind,
+    minorsBehind,
+    diffType,
+  }
+}
+
+/**
+ * Composable to check for outdated dependencies.
+ * Returns a reactive map of dependency name to outdated info.
+ */
+export function useOutdatedDependencies(
+  dependencies: MaybeRefOrGetter<Record<string, string> | undefined>,
+) {
+  const cachedFetch = useCachedFetch()
+  const outdated = shallowRef<Record<string, OutdatedDependencyInfo>>({})
+
+  async function fetchOutdatedInfo(deps: Record<string, string> | undefined) {
+    if (!deps || Object.keys(deps).length === 0) {
+      outdated.value = {}
+      return
+    }
+
+    const entries = Object.entries(deps)
+    const batchResults = await mapWithConcurrency(
+      entries,
+      async ([name, constraint]) => {
+        const info = await checkDependencyOutdated(cachedFetch, name, constraint)
+        return [name, info] as const
+      },
+      5,
+    )
+
+    const results: Record<string, OutdatedDependencyInfo> = {}
+    for (const [name, info] of batchResults) {
+      if (info) {
+        results[name] = info
+      }
+    }
+
+    outdated.value = results
+  }
+
+  watch(
+    () => toValue(dependencies),
+    deps => {
+      fetchOutdatedInfo(deps)
+    },
+    { immediate: true },
+  )
+
+  return outdated
+}
diff --git a/app/composables/npm/usePackage.ts b/app/composables/npm/usePackage.ts
new file mode 100644
index 000000000..a6d848d79
--- /dev/null
+++ b/app/composables/npm/usePackage.ts
@@ -0,0 +1,116 @@
+import type { Packument, SlimPackument } from '#shared/types'
+import { extractInstallScriptsInfo } from '~/utils/install-scripts'
+
+/** Number of recent versions to include in initial payload */
+const RECENT_VERSIONS_COUNT = 5
+
+/**
+ * Transform a full Packument into a slimmed version for client-side use.
+ * Reduces payload size by:
+ * - Removing readme (fetched separately)
+ * - Including only: 5 most recent versions + one version per dist-tag + requested version
+ * - Stripping unnecessary fields from version objects
+ */
+function transformPackument(pkg: Packument, requestedVersion?: string | null): SlimPackument {
+  // Get versions pointed to by dist-tags
+  const distTagVersions = new Set(Object.values(pkg['dist-tags'] ?? {}))
+
+  // Get 5 most recent versions by publish time
+  const recentVersions = Object.keys(pkg.versions)
+    .filter(v => pkg.time[v])
+    .sort((a, b) => {
+      const timeA = pkg.time[a]
+      const timeB = pkg.time[b]
+      if (!timeA || !timeB) return 0
+      return new Date(timeB).getTime() - new Date(timeA).getTime()
+    })
+    .slice(0, RECENT_VERSIONS_COUNT)
+
+  // Combine: recent versions + dist-tag versions + requested version (deduplicated)
+  const includedVersions = new Set([...recentVersions, ...distTagVersions])
+
+  // Add the requested version if it exists in the package
+  if (requestedVersion && pkg.versions[requestedVersion]) {
+    includedVersions.add(requestedVersion)
+  }
+
+  // Build filtered versions object with install scripts info per version
+  const filteredVersions: Record<string, SlimVersion> = {}
+  let versionData: SlimPackumentVersion | null = null
+  for (const v of includedVersions) {
+    const version = pkg.versions[v]
+    if (version) {
+      if (version.version === requestedVersion) {
+        // Strip readme from each version, extract install scripts info
+        const { readme: _readme, scripts, ...slimVersion } = version
+
+        // Extract install scripts info (which scripts exist + npx deps)
+        const installScripts = scripts ? extractInstallScriptsInfo(scripts) : null
+        versionData = {
+          ...slimVersion,
+          installScripts: installScripts ?? undefined,
+        }
+      }
+      filteredVersions[v] = {
+        ...((version?.dist as { attestations?: unknown }) ? { hasProvenance: true } : {}),
+        version: version.version,
+        deprecated: version.deprecated,
+        tags: version.tags as string[],
+      }
+    }
+  }
+
+  // Build filtered time object (only for included versions + metadata)
+  const filteredTime: Record<string, string> = {}
+  if (pkg.time.modified) filteredTime.modified = pkg.time.modified
+  if (pkg.time.created) filteredTime.created = pkg.time.created
+  for (const v of includedVersions) {
+    if (pkg.time[v]) filteredTime[v] = pkg.time[v]
+  }
+
+  return {
+    '_id': pkg._id,
+    '_rev': pkg._rev,
+    'name': pkg.name,
+    'description': pkg.description,
+    'dist-tags': pkg['dist-tags'],
+    'time': filteredTime,
+    'maintainers': pkg.maintainers,
+    'author': pkg.author,
+    'license': pkg.license,
+    'homepage': pkg.homepage,
+    'keywords': pkg.keywords,
+    'repository': pkg.repository,
+    'bugs': pkg.bugs,
+    'requestedVersion': versionData,
+    'versions': filteredVersions,
+  }
+}
+
+export function usePackage(
+  name: MaybeRefOrGetter<string>,
+  requestedVersion?: MaybeRefOrGetter<string | null>,
+) {
+  const cachedFetch = useCachedFetch()
+
+  const asyncData = useLazyAsyncData(
+    () => `package:${toValue(name)}:${toValue(requestedVersion) ?? ''}`,
+    async (_nuxtApp, { signal }) => {
+      const encodedName = encodePackageName(toValue(name))
+      const { data: r, isStale } = await cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, {
+        signal,
+      })
+      const reqVer = toValue(requestedVersion)
+      const pkg = transformPackument(r, reqVer)
+      return { ...pkg, isStale }
+    },
+  )
+
+  if (import.meta.client && asyncData.data.value?.isStale) {
+    onMounted(() => {
+      asyncData.refresh()
+    })
+  }
+
+  return asyncData
+}
diff --git a/app/composables/npm/usePackageDownloads.ts b/app/composables/npm/usePackageDownloads.ts
new file mode 100644
index 000000000..591a7d2d7
--- /dev/null
+++ b/app/composables/npm/usePackageDownloads.ts
@@ -0,0 +1,29 @@
+import type { NpmDownloadCount } from '#shared/types'
+import { NPM_API } from '~/utils/npm/common'
+
+export function usePackageDownloads(
+  name: MaybeRefOrGetter<string>,
+  period: MaybeRefOrGetter<'last-day' | 'last-week' | 'last-month' | 'last-year'> = 'last-week',
+) {
+  const cachedFetch = useCachedFetch()
+
+  const asyncData = useLazyAsyncData(
+    () => `downloads:${toValue(name)}:${toValue(period)}`,
+    async (_nuxtApp, { signal }) => {
+      const encodedName = encodePackageName(toValue(name))
+      const { data, isStale } = await cachedFetch<NpmDownloadCount>(
+        `${NPM_API}/downloads/point/${toValue(period)}/${encodedName}`,
+        { signal },
+      )
+      return { ...data, isStale }
+    },
+  )
+
+  if (import.meta.client && asyncData.data.value?.isStale) {
+    onMounted(() => {
+      asyncData.refresh()
+    })
+  }
+
+  return asyncData
+}
diff --git a/app/composables/npm/useResolvedVersion.ts b/app/composables/npm/useResolvedVersion.ts
new file mode 100644
index 000000000..992ce62b7
--- /dev/null
+++ b/app/composables/npm/useResolvedVersion.ts
@@ -0,0 +1,18 @@
+import type { ResolvedPackageVersion } from 'fast-npm-meta'
+
+export function useResolvedVersion(
+  packageName: MaybeRefOrGetter<string>,
+  requestedVersion: MaybeRefOrGetter<string | null>,
+) {
+  return useFetch(
+    () => {
+      const version = toValue(requestedVersion)
+      return version
+        ? `https://npm.antfu.dev/${toValue(packageName)}@${version}`
+        : `https://npm.antfu.dev/${toValue(packageName)}`
+    },
+    {
+      transform: (data: ResolvedPackageVersion) => data.version,
+    },
+  )
+}
diff --git a/app/composables/useNpmRegistry.ts b/app/composables/useNpmRegistry.ts
deleted file mode 100644
index ba1cb3d8f..000000000
--- a/app/composables/useNpmRegistry.ts
+++ /dev/null
@@ -1,870 +0,0 @@
-import type {
-  Packument,
-  SlimPackument,
-  NpmSearchResponse,
-  NpmSearchResult,
-  NpmDownloadCount,
-  NpmPerson,
-  PackageVersionInfo,
-} from '#shared/types'
-import { getVersions } from 'fast-npm-meta'
-import type { ResolvedPackageVersion } from 'fast-npm-meta'
-import type { ReleaseType } from 'semver'
-import { mapWithConcurrency } from '#shared/utils/async'
-import { maxSatisfying, prerelease, major, minor, diff, gt, compare } from 'semver'
-import { extractInstallScriptsInfo } from '~/utils/install-scripts'
-import type { CachedFetchFunction } from '#shared/utils/fetch-cache-config'
-
-const NPM_REGISTRY = 'https://registry.npmjs.org'
-const NPM_API = 'https://api.npmjs.org'
-
-// Cache for packument fetches to avoid duplicate requests across components
-const packumentCache = new Map<string, Promise<Packument | null>>()
-
-/**
- * Fetch downloads for multiple packages.
- * Returns a map of package name -> weekly downloads.
- * Uses bulk API for unscoped packages, parallel individual requests for scoped.
- * Note: npm bulk downloads API does not support scoped packages.
- */
-async function fetchBulkDownloads(
-  packageNames: string[],
-  options: Parameters<typeof $fetch>[1] = {},
-): Promise<Map<string, number>> {
-  const downloads = new Map<string, number>()
-  if (packageNames.length === 0) return downloads
-
-  // Separate scoped and unscoped packages
-  const scopedPackages = packageNames.filter(n => n.startsWith('@'))
-  const unscopedPackages = packageNames.filter(n => !n.startsWith('@'))
-
-  // Fetch unscoped packages via bulk API (max 128 per request)
-  const bulkPromises: Promise<void>[] = []
-  const chunkSize = 100
-  for (let i = 0; i < unscopedPackages.length; i += chunkSize) {
-    const chunk = unscopedPackages.slice(i, i + chunkSize)
-    bulkPromises.push(
-      (async () => {
-        try {
-          const response = await $fetch<Record<string, { downloads: number } | null>>(
-            `${NPM_API}/downloads/point/last-week/${chunk.join(',')}`,
-            options,
-          )
-          for (const [name, data] of Object.entries(response)) {
-            if (data?.downloads !== undefined) {
-              downloads.set(name, data.downloads)
-            }
-          }
-        } catch {
-          // Ignore errors - downloads are optional
-        }
-      })(),
-    )
-  }
-
-  // Fetch scoped packages in parallel batches (concurrency limit to avoid overwhelming the API)
-  // Use Promise.allSettled to not fail on individual errors
-  const scopedBatchSize = 20 // Concurrent requests per batch
-  for (let i = 0; i < scopedPackages.length; i += scopedBatchSize) {
-    const batch = scopedPackages.slice(i, i + scopedBatchSize)
-    bulkPromises.push(
-      (async () => {
-        const results = await Promise.allSettled(
-          batch.map(async name => {
-            const encoded = encodePackageName(name)
-            const data = await $fetch<{ downloads: number }>(
-              `${NPM_API}/downloads/point/last-week/${encoded}`,
-            )
-            return { name, downloads: data.downloads }
-          }),
-        )
-        for (const result of results) {
-          if (result.status === 'fulfilled' && result.value.downloads !== undefined) {
-            downloads.set(result.value.name, result.value.downloads)
-          }
-        }
-      })(),
-    )
-  }
-
-  // Wait for all fetches to complete
-  await Promise.all(bulkPromises)
-
-  return downloads
-}
-
-/** Number of recent versions to include in initial payload */
-const RECENT_VERSIONS_COUNT = 5
-
-/**
- * Transform a full Packument into a slimmed version for client-side use.
- * Reduces payload size by:
- * - Removing readme (fetched separately)
- * - Including only: 5 most recent versions + one version per dist-tag + requested version
- * - Stripping unnecessary fields from version objects
- */
-function transformPackument(pkg: Packument, requestedVersion?: string | null): SlimPackument {
-  // Get versions pointed to by dist-tags
-  const distTagVersions = new Set(Object.values(pkg['dist-tags'] ?? {}))
-
-  // Get 5 most recent versions by publish time
-  const recentVersions = Object.keys(pkg.versions)
-    .filter(v => pkg.time[v])
-    .sort((a, b) => {
-      const timeA = pkg.time[a]
-      const timeB = pkg.time[b]
-      if (!timeA || !timeB) return 0
-      return new Date(timeB).getTime() - new Date(timeA).getTime()
-    })
-    .slice(0, RECENT_VERSIONS_COUNT)
-
-  // Combine: recent versions + dist-tag versions + requested version (deduplicated)
-  const includedVersions = new Set([...recentVersions, ...distTagVersions])
-
-  // Add the requested version if it exists in the package
-  if (requestedVersion && pkg.versions[requestedVersion]) {
-    includedVersions.add(requestedVersion)
-  }
-
-  // Build filtered versions object with install scripts info per version
-  const filteredVersions: Record<string, SlimVersion> = {}
-  let versionData: SlimPackumentVersion | null = null
-  for (const v of includedVersions) {
-    const version = pkg.versions[v]
-    if (version) {
-      if (version.version === requestedVersion) {
-        // Strip readme from each version, extract install scripts info
-        const { readme: _readme, scripts, ...slimVersion } = version
-
-        // Extract install scripts info (which scripts exist + npx deps)
-        const installScripts = scripts ? extractInstallScriptsInfo(scripts) : null
-        versionData = {
-          ...slimVersion,
-          installScripts: installScripts ?? undefined,
-        }
-      }
-      filteredVersions[v] = {
-        ...((version?.dist as { attestations?: unknown }) ? { hasProvenance: true } : {}),
-        version: version.version,
-        deprecated: version.deprecated,
-        tags: version.tags as string[],
-      }
-    }
-  }
-
-  // Build filtered time object (only for included versions + metadata)
-  const filteredTime: Record<string, string> = {}
-  if (pkg.time.modified) filteredTime.modified = pkg.time.modified
-  if (pkg.time.created) filteredTime.created = pkg.time.created
-  for (const v of includedVersions) {
-    if (pkg.time[v]) filteredTime[v] = pkg.time[v]
-  }
-
-  return {
-    '_id': pkg._id,
-    '_rev': pkg._rev,
-    'name': pkg.name,
-    'description': pkg.description,
-    'dist-tags': pkg['dist-tags'],
-    'time': filteredTime,
-    'maintainers': pkg.maintainers,
-    'author': pkg.author,
-    'license': pkg.license,
-    'homepage': pkg.homepage,
-    'keywords': pkg.keywords,
-    'repository': pkg.repository,
-    'bugs': pkg.bugs,
-    'requestedVersion': versionData,
-    'versions': filteredVersions,
-  }
-}
-
-export function useResolvedVersion(
-  packageName: MaybeRefOrGetter<string>,
-  requestedVersion: MaybeRefOrGetter<string | null>,
-) {
-  return useFetch(
-    () => {
-      const version = toValue(requestedVersion)
-      return version
-        ? `https://npm.antfu.dev/${toValue(packageName)}@${version}`
-        : `https://npm.antfu.dev/${toValue(packageName)}`
-    },
-    {
-      transform: (data: ResolvedPackageVersion) => data.version,
-    },
-  )
-}
-
-export function usePackage(
-  name: MaybeRefOrGetter<string>,
-  requestedVersion?: MaybeRefOrGetter<string | null>,
-) {
-  const cachedFetch = useCachedFetch()
-
-  const asyncData = useLazyAsyncData(
-    () => `package:${toValue(name)}:${toValue(requestedVersion) ?? ''}`,
-    async (_nuxtApp, { signal }) => {
-      const encodedName = encodePackageName(toValue(name))
-      const { data: r, isStale } = await cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, {
-        signal,
-      })
-      const reqVer = toValue(requestedVersion)
-      const pkg = transformPackument(r, reqVer)
-      return { ...pkg, isStale }
-    },
-  )
-
-  if (import.meta.client && asyncData.data.value?.isStale) {
-    onMounted(() => {
-      asyncData.refresh()
-    })
-  }
-
-  return asyncData
-}
-
-export function usePackageDownloads(
-  name: MaybeRefOrGetter<string>,
-  period: MaybeRefOrGetter<'last-day' | 'last-week' | 'last-month' | 'last-year'> = 'last-week',
-) {
-  const cachedFetch = useCachedFetch()
-
-  const asyncData = useLazyAsyncData(
-    () => `downloads:${toValue(name)}:${toValue(period)}`,
-    async (_nuxtApp, { signal }) => {
-      const encodedName = encodePackageName(toValue(name))
-      const { data, isStale } = await cachedFetch<NpmDownloadCount>(
-        `${NPM_API}/downloads/point/${toValue(period)}/${encodedName}`,
-        { signal },
-      )
-      return { ...data, isStale }
-    },
-  )
-
-  if (import.meta.client && asyncData.data.value?.isStale) {
-    onMounted(() => {
-      asyncData.refresh()
-    })
-  }
-
-  return asyncData
-}
-
-type NpmDownloadsRangeResponse = {
-  start: string
-  end: string
-  package: string
-  downloads: Array<{ day: string; downloads: number }>
-}
-
-/**
- * Fetch download range data from npm API.
- * Exported for external use (e.g., in components).
- */
-export async function fetchNpmDownloadsRange(
-  packageName: string,
-  start: string,
-  end: string,
-): Promise<NpmDownloadsRangeResponse> {
-  const encodedName = encodePackageName(packageName)
-  return await $fetch<NpmDownloadsRangeResponse>(
-    `${NPM_API}/downloads/range/${start}:${end}/${encodedName}`,
-  )
-}
-
-const emptySearchResponse = {
-  objects: [],
-  total: 0,
-  isStale: false,
-  time: new Date().toISOString(),
-} satisfies NpmSearchResponse
-
-export interface NpmSearchOptions {
-  /** Number of results to fetch */
-  size?: number
-}
-
-export function useNpmSearch(
-  query: MaybeRefOrGetter<string>,
-  options: MaybeRefOrGetter<NpmSearchOptions> = {},
-) {
-  const cachedFetch = useCachedFetch()
-  // Client-side cache
-  const cache = shallowRef<{
-    query: string
-    objects: NpmSearchResult[]
-    total: number
-  } | null>(null)
-
-  const isLoadingMore = shallowRef(false)
-
-  // Standard (non-incremental) search implementation
-  let lastSearch: NpmSearchResponse | undefined = undefined
-
-  const asyncData = useLazyAsyncData(
-    () => `search:incremental:${toValue(query)}`,
-    async (_nuxtApp, { signal }) => {
-      const q = toValue(query)
-
-      if (!q.trim()) {
-        return emptySearchResponse
-      }
-
-      const opts = toValue(options)
-
-      // This only runs for initial load or query changes
-      // Reset cache for new query
-      cache.value = null
-
-      const params = new URLSearchParams()
-      params.set('text', q)
-      // Use requested size for initial fetch
-      params.set('size', String(opts.size ?? 25))
-
-      if (q.length === 1) {
-        const encodedName = encodePackageName(q)
-        const [{ data: pkg, isStale }, { data: downloads }] = await Promise.all([
-          cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, { signal }),
-          cachedFetch<NpmDownloadCount>(`${NPM_API}/downloads/point/last-week/${encodedName}`, {
-            signal,
-          }),
-        ])
-
-        if (!pkg) {
-          return emptySearchResponse
-        }
-
-        const result = packumentToSearchResult(pkg, downloads?.downloads)
-
-        // If query changed/outdated, return empty search response
-        if (q !== toValue(query)) {
-          return emptySearchResponse
-        }
-
-        cache.value = {
-          query: q,
-          objects: [result],
-          total: 1,
-        }
-
-        return {
-          objects: [result],
-          total: 1,
-          isStale,
-          time: new Date().toISOString(),
-        }
-      }
-
-      const { data: response, isStale } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
-        { signal },
-        60,
-      )
-
-      // If query changed/outdated, return empty search response
-      if (q !== toValue(query)) {
-        return emptySearchResponse
-      }
-
-      cache.value = {
-        query: q,
-        objects: response.objects,
-        total: response.total,
-      }
-
-      return { ...response, isStale }
-    },
-    { default: () => lastSearch || emptySearchResponse },
-  )
-
-  // Fetch more results incrementally (only used in incremental mode)
-  async function fetchMore(targetSize: number): Promise<void> {
-    const q = toValue(query).trim()
-    if (!q) {
-      cache.value = null
-      return
-    }
-
-    // If query changed, reset cache (shouldn't happen, but safety check)
-    if (cache.value && cache.value.query !== q) {
-      cache.value = null
-      await asyncData.refresh()
-      return
-    }
-
-    const currentCount = cache.value?.objects.length ?? 0
-    const total = cache.value?.total ?? Infinity
-
-    // Already have enough or no more to fetch
-    if (currentCount >= targetSize || currentCount >= total) {
-      return
-    }
-
-    isLoadingMore.value = true
-
-    try {
-      // Fetch from where we left off - calculate size needed
-      const from = currentCount
-      const size = Math.min(targetSize - currentCount, total - currentCount)
-
-      const params = new URLSearchParams()
-      params.set('text', q)
-      params.set('size', String(size))
-      params.set('from', String(from))
-
-      const { data: response } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
-        {},
-        60,
-      )
-
-      // Update cache
-      if (cache.value && cache.value.query === q) {
-        const existingNames = new Set(cache.value.objects.map(obj => obj.package.name))
-        const newObjects = response.objects.filter(obj => !existingNames.has(obj.package.name))
-        cache.value = {
-          query: q,
-          objects: [...cache.value.objects, ...newObjects],
-          total: response.total,
-        }
-      } else {
-        cache.value = {
-          query: q,
-          objects: response.objects,
-          total: response.total,
-        }
-      }
-
-      // If we still need more, fetch again recursively
-      if (
-        cache.value.objects.length < targetSize &&
-        cache.value.objects.length < cache.value.total
-      ) {
-        await fetchMore(targetSize)
-      }
-    } finally {
-      isLoadingMore.value = false
-    }
-  }
-
-  // Watch for size increases in incremental mode
-  watch(
-    () => toValue(options).size,
-    async (newSize, oldSize) => {
-      if (!newSize) return
-      if (oldSize && newSize > oldSize && toValue(query).trim()) {
-        await fetchMore(newSize)
-      }
-    },
-  )
-
-  // Computed data that uses cache in incremental mode
-  const data = computed<NpmSearchResponse | null>(() => {
-    if (cache.value) {
-      return {
-        isStale: false,
-        objects: cache.value.objects,
-        total: cache.value.total,
-        time: new Date().toISOString(),
-      }
-    }
-    return asyncData.data.value
-  })
-
-  if (import.meta.client && asyncData.data.value?.isStale) {
-    onMounted(() => {
-      asyncData.refresh()
-    })
-  }
-
-  // Whether there are more results available on the server (incremental mode only)
-  const hasMore = computed(() => {
-    if (!cache.value) return true
-    return cache.value.objects.length < cache.value.total
-  })
-
-  return {
-    ...asyncData,
-    /** Reactive search results (uses cache in incremental mode) */
-    data,
-    /** Whether currently loading more results (incremental mode only) */
-    isLoadingMore,
-    /** Whether there are more results available (incremental mode only) */
-    hasMore,
-    /** Manually fetch more results up to target size (incremental mode only) */
-    fetchMore,
-  }
-}
-
-/**
- * Minimal packument data needed for package cards
- */
-interface MinimalPackument {
-  'name': string
-  'description'?: string
-  'keywords'?: string[]
-  // `dist-tags` can be missing in some later unpublished packages
-  'dist-tags'?: Record<string, string>
-  'time': Record<string, string>
-  'maintainers'?: NpmPerson[]
-}
-
-/**
- * Convert packument to search result format for display
- */
-function packumentToSearchResult(pkg: MinimalPackument, weeklyDownloads?: number): NpmSearchResult {
-  let latestVersion = ''
-  if (pkg['dist-tags']) {
-    latestVersion = pkg['dist-tags'].latest || Object.values(pkg['dist-tags'])[0] || ''
-  }
-  const modified = pkg.time.modified || pkg.time[latestVersion] || ''
-
-  return {
-    package: {
-      name: pkg.name,
-      version: latestVersion,
-      description: pkg.description,
-      keywords: pkg.keywords,
-      date: pkg.time[latestVersion] || modified,
-      links: {
-        npm: `https://www.npmjs.com/package/${pkg.name}`,
-      },
-      maintainers: pkg.maintainers,
-    },
-    score: { final: 0, detail: { quality: 0, popularity: 0, maintenance: 0 } },
-    searchScore: 0,
-    downloads: weeklyDownloads !== undefined ? { weekly: weeklyDownloads } : undefined,
-    updated: pkg.time[latestVersion] || modified,
-  }
-}
-
-/**
- * Fetch all packages for an npm organization
- * Returns search-result-like objects for compatibility with PackageList
- */
-export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
-  const cachedFetch = useCachedFetch()
-
-  const asyncData = useLazyAsyncData(
-    () => `org-packages:${toValue(orgName)}`,
-    async (_nuxtApp, { signal }) => {
-      const org = toValue(orgName)
-      if (!org) {
-        return emptySearchResponse
-      }
-
-      // Get all package names in the org
-      let packageNames: string[]
-      try {
-        const { data } = await cachedFetch<Record<string, string>>(
-          `${NPM_REGISTRY}/-/org/${encodeURIComponent(org)}/package`,
-          { signal },
-        )
-        packageNames = Object.keys(data)
-      } catch (err) {
-        // Check if this is a 404 (org not found)
-        if (err && typeof err === 'object' && 'statusCode' in err && err.statusCode === 404) {
-          throw createError({
-            statusCode: 404,
-            statusMessage: 'Organization not found',
-            message: `The organization "@${org}" does not exist on npm`,
-          })
-        }
-        // For other errors (network, etc.), return empty array to be safe
-        packageNames = []
-      }
-
-      if (packageNames.length === 0) {
-        return emptySearchResponse
-      }
-
-      // Fetch packuments and downloads in parallel
-      const [packuments, downloads] = await Promise.all([
-        // Fetch packuments with concurrency limit
-        (async () => {
-          const results = await mapWithConcurrency(
-            packageNames,
-            async name => {
-              try {
-                const encoded = encodePackageName(name)
-                const { data: pkg } = await cachedFetch<MinimalPackument>(
-                  `${NPM_REGISTRY}/${encoded}`,
-                  { signal },
-                )
-                return pkg
-              } catch {
-                return null
-              }
-            },
-            10,
-          )
-          // Filter out any unpublished packages (missing dist-tags)
-          return results.filter(
-            (pkg): pkg is MinimalPackument => pkg !== null && !!pkg['dist-tags'],
-          )
-        })(),
-        // Fetch downloads in bulk
-        fetchBulkDownloads(packageNames, { signal }),
-      ])
-
-      // Convert to search results with download data
-      const results: NpmSearchResult[] = packuments.map(pkg =>
-        packumentToSearchResult(pkg, downloads.get(pkg.name)),
-      )
-
-      return {
-        isStale: false,
-        objects: results,
-        total: results.length,
-        time: new Date().toISOString(),
-      } satisfies NpmSearchResponse
-    },
-    { default: () => emptySearchResponse },
-  )
-
-  return asyncData
-}
-
-// ============================================================================
-// Package Versions
-// ============================================================================
-
-// Cache for full version lists (client-side only, for non-composable usage)
-const allVersionsCache = new Map<string, Promise<PackageVersionInfo[]>>()
-
-/**
- * Fetch all versions of a package using fast-npm-meta API.
- * Returns version info sorted by version (newest first).
- * Results are cached to avoid duplicate requests.
- *
- * Note: This is a standalone async function for use in event handlers.
- * For composable usage, use useAllPackageVersions instead.
- *
- * @see https://github.com/antfu/fast-npm-meta
- */
-export async function fetchAllPackageVersions(packageName: string): Promise<PackageVersionInfo[]> {
-  const cached = allVersionsCache.get(packageName)
-  if (cached) return cached
-
-  const promise = (async () => {
-    const data = await getVersions(packageName, { metadata: true })
-
-    return Object.entries(data.versionsMeta)
-      .map(([version, meta]) => ({
-        version,
-        time: meta.time,
-        hasProvenance: meta.provenance === 'trustedPublisher' || meta.provenance === true,
-        deprecated: meta.deprecated,
-      }))
-      .sort((a, b) => compare(b.version, a.version))
-  })()
-
-  allVersionsCache.set(packageName, promise)
-  return promise
-}
-
-// ============================================================================
-// Outdated Dependencies
-// ============================================================================
-
-/** Information about an outdated dependency */
-export interface OutdatedDependencyInfo {
-  /** The resolved version that satisfies the constraint */
-  resolved: string
-  /** The latest available version */
-  latest: string
-  /** How many major versions behind */
-  majorsBehind: number
-  /** How many minor versions behind (when same major) */
-  minorsBehind: number
-  /** The type of version difference */
-  diffType: ReleaseType | null
-}
-
-/**
- * Check if a version constraint explicitly includes a prerelease tag.
- * e.g., "^1.0.0-alpha" or ">=2.0.0-beta.1" include prereleases
- */
-export function constraintIncludesPrerelease(constraint: string): boolean {
-  return (
-    /-(alpha|beta|rc|next|canary|dev|preview|pre|experimental)/i.test(constraint) ||
-    /-\d/.test(constraint)
-  )
-}
-
-/**
- * Check if a constraint is a non-semver value (git URL, file path, etc.)
- */
-export function isNonSemverConstraint(constraint: string): boolean {
-  return (
-    constraint.startsWith('git') ||
-    constraint.startsWith('http') ||
-    constraint.startsWith('file:') ||
-    constraint.startsWith('npm:') ||
-    constraint.startsWith('link:') ||
-    constraint.startsWith('workspace:') ||
-    constraint.includes('/')
-  )
-}
-
-/**
- * Check if a dependency is outdated.
- * Returns null if up-to-date or if we can't determine.
- */
-async function checkDependencyOutdated(
-  cachedFetch: CachedFetchFunction,
-  packageName: string,
-  constraint: string,
-): Promise<OutdatedDependencyInfo | null> {
-  if (isNonSemverConstraint(constraint)) {
-    return null
-  }
-
-  // Check in-memory cache first
-  let packument: Packument | null
-  const cached = packumentCache.get(packageName)
-  if (cached) {
-    packument = await cached
-  } else {
-    const promise = cachedFetch<Packument>(`${NPM_REGISTRY}/${encodePackageName(packageName)}`)
-      .then(({ data }) => data)
-      .catch(() => null)
-    packumentCache.set(packageName, promise)
-    packument = await promise
-  }
-
-  if (!packument) return null
-
-  const latestTag = packument['dist-tags']?.latest
-  if (!latestTag) return null
-
-  // Handle "latest" constraint specially - return info with current version
-  if (constraint === 'latest') {
-    return {
-      resolved: latestTag,
-      latest: latestTag,
-      majorsBehind: 0,
-      minorsBehind: 0,
-      diffType: null,
-    }
-  }
-
-  let versions = Object.keys(packument.versions)
-  const includesPrerelease = constraintIncludesPrerelease(constraint)
-
-  if (!includesPrerelease) {
-    versions = versions.filter(v => !prerelease(v))
-  }
-
-  const resolved = maxSatisfying(versions, constraint)
-  if (!resolved) return null
-
-  if (resolved === latestTag) return null
-
-  // If resolved version is newer than latest, not outdated
-  // (e.g., using ^2.0.0-rc when latest is 1.x)
-  if (gt(resolved, latestTag)) {
-    return null
-  }
-
-  const diffType = diff(resolved, latestTag)
-  const majorsBehind = major(latestTag) - major(resolved)
-  const minorsBehind = majorsBehind === 0 ? minor(latestTag) - minor(resolved) : 0
-
-  return {
-    resolved,
-    latest: latestTag,
-    majorsBehind,
-    minorsBehind,
-    diffType,
-  }
-}
-
-/**
- * Composable to check for outdated dependencies.
- * Returns a reactive map of dependency name to outdated info.
- */
-export function useOutdatedDependencies(
-  dependencies: MaybeRefOrGetter<Record<string, string> | undefined>,
-) {
-  const cachedFetch = useCachedFetch()
-  const outdated = shallowRef<Record<string, OutdatedDependencyInfo>>({})
-
-  async function fetchOutdatedInfo(deps: Record<string, string> | undefined) {
-    if (!deps || Object.keys(deps).length === 0) {
-      outdated.value = {}
-      return
-    }
-
-    const entries = Object.entries(deps)
-    const batchResults = await mapWithConcurrency(
-      entries,
-      async ([name, constraint]) => {
-        const info = await checkDependencyOutdated(cachedFetch, name, constraint)
-        return [name, info] as const
-      },
-      5,
-    )
-
-    const results: Record<string, OutdatedDependencyInfo> = {}
-    for (const [name, info] of batchResults) {
-      if (info) {
-        results[name] = info
-      }
-    }
-
-    outdated.value = results
-  }
-
-  watch(
-    () => toValue(dependencies),
-    deps => {
-      fetchOutdatedInfo(deps)
-    },
-    { immediate: true },
-  )
-
-  return outdated
-}
-
-/**
- * Get tooltip text for an outdated dependency
- */
-export function getOutdatedTooltip(
-  info: OutdatedDependencyInfo,
-  t: (key: string, params?: Record<string, unknown>, plural?: number) => string,
-): string {
-  if (info.majorsBehind > 0) {
-    return t(
-      'package.dependencies.outdated_major',
-      { count: info.majorsBehind, latest: info.latest },
-      info.majorsBehind,
-    )
-  }
-  if (info.minorsBehind > 0) {
-    return t(
-      'package.dependencies.outdated_minor',
-      { count: info.minorsBehind, latest: info.latest },
-      info.minorsBehind,
-    )
-  }
-  return t('package.dependencies.outdated_patch', { latest: info.latest })
-}
-
-/**
- * Get CSS class for a dependency version based on outdated status
- */
-export function getVersionClass(info: OutdatedDependencyInfo | undefined): string {
-  if (!info) return 'text-fg-subtle'
-  // Green for up-to-date (e.g. "latest" constraint)
-  if (info.majorsBehind === 0 && info.minorsBehind === 0 && info.resolved === info.latest) {
-    return 'text-green-500 cursor-help'
-  }
-  // Red for major versions behind
-  if (info.majorsBehind > 0) return 'text-red-500 cursor-help'
-  // Orange for minor versions behind
-  if (info.minorsBehind > 0) return 'text-orange-500 cursor-help'
-  // Yellow for patch versions behind
-  return 'text-yellow-500 cursor-help'
-}
diff --git a/app/utils/npm/api.ts b/app/utils/npm/api.ts
new file mode 100644
index 000000000..063e4396c
--- /dev/null
+++ b/app/utils/npm/api.ts
@@ -0,0 +1,64 @@
+import type { PackageVersionInfo } from '#shared/types'
+import { getVersions } from 'fast-npm-meta'
+import { compare } from 'semver'
+import { NPM_API } from './common'
+
+type NpmDownloadsRangeResponse = {
+  start: string
+  end: string
+  package: string
+  downloads: Array<{ day: string; downloads: number }>
+}
+
+/**
+ * Fetch download range data from npm API.
+ * Exported for external use (e.g., in components).
+ */
+export async function fetchNpmDownloadsRange(
+  packageName: string,
+  start: string,
+  end: string,
+): Promise<NpmDownloadsRangeResponse> {
+  const encodedName = encodePackageName(packageName)
+  return await $fetch<NpmDownloadsRangeResponse>(
+    `${NPM_API}/downloads/range/${start}:${end}/${encodedName}`,
+  )
+}
+
+// ============================================================================
+// Package Versions
+// ============================================================================
+
+// Cache for full version lists (client-side only, for non-composable usage)
+const allVersionsCache = new Map<string, Promise<PackageVersionInfo[]>>()
+
+/**
+ * Fetch all versions of a package using fast-npm-meta API.
+ * Returns version info sorted by version (newest first).
+ * Results are cached to avoid duplicate requests.
+ *
+ * Note: This is a standalone async function for use in event handlers.
+ * For composable usage, use useAllPackageVersions instead.
+ *
+ * @see https://github.com/antfu/fast-npm-meta
+ */
+export async function fetchAllPackageVersions(packageName: string): Promise<PackageVersionInfo[]> {
+  const cached = allVersionsCache.get(packageName)
+  if (cached) return cached
+
+  const promise = (async () => {
+    const data = await getVersions(packageName, { metadata: true })
+
+    return Object.entries(data.versionsMeta)
+      .map(([version, meta]) => ({
+        version,
+        time: meta.time,
+        hasProvenance: meta.provenance === 'trustedPublisher' || meta.provenance === true,
+        deprecated: meta.deprecated,
+      }))
+      .sort((a, b) => compare(b.version, a.version))
+  })()
+
+  allVersionsCache.set(packageName, promise)
+  return promise
+}
diff --git a/app/utils/npm.ts b/app/utils/npm/common.ts
similarity index 80%
rename from app/utils/npm.ts
rename to app/utils/npm/common.ts
index b75432ad2..23b96fe1a 100644
--- a/app/utils/npm.ts
+++ b/app/utils/npm/common.ts
@@ -1,3 +1,6 @@
+export const NPM_REGISTRY = 'https://registry.npmjs.org'
+export const NPM_API = 'https://api.npmjs.org'
+
 /**
  * Constructs a scope:team string in the format expected by npm.
  * npm operations require the format @scope:team (with @ prefix).
diff --git a/app/utils/npm/outdated-dependencies.ts b/app/utils/npm/outdated-dependencies.ts
new file mode 100644
index 000000000..95b672b77
--- /dev/null
+++ b/app/utils/npm/outdated-dependencies.ts
@@ -0,0 +1,82 @@
+import type { ReleaseType } from 'semver'
+
+/** Information about an outdated dependency */
+export interface OutdatedDependencyInfo {
+  /** The resolved version that satisfies the constraint */
+  resolved: string
+  /** The latest available version */
+  latest: string
+  /** How many major versions behind */
+  majorsBehind: number
+  /** How many minor versions behind (when same major) */
+  minorsBehind: number
+  /** The type of version difference */
+  diffType: ReleaseType | null
+}
+
+/**
+ * Check if a version constraint explicitly includes a prerelease tag.
+ * e.g., "^1.0.0-alpha" or ">=2.0.0-beta.1" include prereleases
+ */
+export function constraintIncludesPrerelease(constraint: string): boolean {
+  return (
+    /-(alpha|beta|rc|next|canary|dev|preview|pre|experimental)/i.test(constraint) ||
+    /-\d/.test(constraint)
+  )
+}
+
+/**
+ * Check if a constraint is a non-semver value (git URL, file path, etc.)
+ */
+export function isNonSemverConstraint(constraint: string): boolean {
+  return (
+    constraint.startsWith('git') ||
+    constraint.startsWith('http') ||
+    constraint.startsWith('file:') ||
+    constraint.startsWith('npm:') ||
+    constraint.startsWith('link:') ||
+    constraint.startsWith('workspace:') ||
+    constraint.includes('/')
+  )
+}
+
+/**
+ * Get tooltip text for an outdated dependency
+ */
+export function getOutdatedTooltip(
+  info: OutdatedDependencyInfo,
+  t: (key: string, params?: Record<string, unknown>, plural?: number) => string,
+): string {
+  if (info.majorsBehind > 0) {
+    return t(
+      'package.dependencies.outdated_major',
+      { count: info.majorsBehind, latest: info.latest },
+      info.majorsBehind,
+    )
+  }
+  if (info.minorsBehind > 0) {
+    return t(
+      'package.dependencies.outdated_minor',
+      { count: info.minorsBehind, latest: info.latest },
+      info.minorsBehind,
+    )
+  }
+  return t('package.dependencies.outdated_patch', { latest: info.latest })
+}
+
+/**
+ * Get CSS class for a dependency version based on outdated status
+ */
+export function getVersionClass(info: OutdatedDependencyInfo | undefined): string {
+  if (!info) return 'text-fg-subtle'
+  // Green for up-to-date (e.g. "latest" constraint)
+  if (info.majorsBehind === 0 && info.minorsBehind === 0 && info.resolved === info.latest) {
+    return 'text-green-500 cursor-help'
+  }
+  // Red for major versions behind
+  if (info.majorsBehind > 0) return 'text-red-500 cursor-help'
+  // Orange for minor versions behind
+  if (info.minorsBehind > 0) return 'text-orange-500 cursor-help'
+  // Yellow for patch versions behind
+  return 'text-yellow-500 cursor-help'
+}
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 379eeb568..eeb476baf 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -275,4 +275,8 @@ export default defineNuxtConfig({
     detectBrowserLanguage: false,
     langDir: 'locales',
   },
+
+  imports: {
+    dirs: ['~/composables', '~/composables/*/*.ts'],
+  },
 })
diff --git a/shared/types/npm-registry.ts b/shared/types/npm-registry.ts
index 4bdd41dd9..12638907a 100644
--- a/shared/types/npm-registry.ts
+++ b/shared/types/npm-registry.ts
@@ -342,3 +342,16 @@ export interface PackageFileContentResponse {
   lines: number
   markdownHtml?: ReadmeResponse
 }
+
+/**
+ * Minimal packument data needed for package cards
+ */
+export interface MinimalPackument {
+  'name': string
+  'description'?: string
+  'keywords'?: string[]
+  // `dist-tags` can be missing in some later unpublished packages
+  'dist-tags'?: Record<string, string>
+  'time': Record<string, string>
+  'maintainers'?: NpmPerson[]
+}
diff --git a/test/unit/app/utils/npm.spec.ts b/test/unit/app/utils/npm.spec.ts
index 56bebfb1a..f6bc417b0 100644
--- a/test/unit/app/utils/npm.spec.ts
+++ b/test/unit/app/utils/npm.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { buildScopeTeam } from '../../../../app/utils/npm'
+import { buildScopeTeam } from '../../../../app/utils/npm/common'
 import { validateScopeTeam } from '../../../../cli/src/npm-client'
 import { getSpdxLicenseUrl } from '../../../../shared/utils/spdx'
 

From a924b2a608c8e1e1bcd3a8e6189ac38f7d58f4cc Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 3 Feb 2026 10:40:24 +0000
Subject: [PATCH 2/4] test: fix mock

---
 test/nuxt/components/PackageVersions.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/nuxt/components/PackageVersions.spec.ts b/test/nuxt/components/PackageVersions.spec.ts
index 6a7f95281..ef2f3e7da 100644
--- a/test/nuxt/components/PackageVersions.spec.ts
+++ b/test/nuxt/components/PackageVersions.spec.ts
@@ -5,7 +5,7 @@ import type { SlimVersion } from '#shared/types'
 
 // Mock the fetchAllPackageVersions function
 const mockFetchAllPackageVersions = vi.fn()
-vi.mock('~/composables/useNpmRegistry', () => ({
+vi.mock('~/utils/npm/api', () => ({
   fetchAllPackageVersions: (...args: unknown[]) => mockFetchAllPackageVersions(...args),
 }))
 

From a2930fb76dde3f2cd4f3d9ac3d628aa64152cf5a Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 3 Feb 2026 10:42:54 +0000
Subject: [PATCH 3/4] chore: add missing imports

---
 app/composables/npm/useOutdatedDependencies.ts | 1 +
 app/composables/npm/usePackage.ts              | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/app/composables/npm/useOutdatedDependencies.ts b/app/composables/npm/useOutdatedDependencies.ts
index 8deee1321..dc372ecf5 100644
--- a/app/composables/npm/useOutdatedDependencies.ts
+++ b/app/composables/npm/useOutdatedDependencies.ts
@@ -7,6 +7,7 @@ import {
   isNonSemverConstraint,
   constraintIncludesPrerelease,
 } from '~/utils/npm/outdated-dependencies'
+import { NPM_REGISTRY } from '~/utils/npm/common'
 
 // Cache for packument fetches to avoid duplicate requests across components
 const packumentCache = new Map<string, Promise<Packument | null>>()
diff --git a/app/composables/npm/usePackage.ts b/app/composables/npm/usePackage.ts
index a6d848d79..b8bcc2329 100644
--- a/app/composables/npm/usePackage.ts
+++ b/app/composables/npm/usePackage.ts
@@ -1,4 +1,5 @@
-import type { Packument, SlimPackument } from '#shared/types'
+import type { Packument, SlimPackument, SlimVersion, SlimPackumentVersion } from '#shared/types'
+import { NPM_REGISTRY } from '~/utils/npm/common'
 import { extractInstallScriptsInfo } from '~/utils/install-scripts'
 
 /** Number of recent versions to include in initial payload */

From 335608137ca18bb456abf157ab2657f5ed2f7eda Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 3 Feb 2026 10:48:06 +0000
Subject: [PATCH 4/4] test: use correct api path

---
 test/nuxt/components/VersionSelector.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index e5391738c..f55b4d119 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -4,7 +4,7 @@ import VersionSelector from '~/components/VersionSelector.vue'
 
 // Mock the fetchAllPackageVersions function
 const mockFetchAllPackageVersions = vi.fn()
-vi.mock('~/composables/useNpmRegistry', () => ({
+vi.mock('~/utils/npm/api', () => ({
   fetchAllPackageVersions: (...args: unknown[]) => mockFetchAllPackageVersions(...args),
 }))