From e6c0d1d49c54059a3fd5c18ed3ce620e64c43240 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@netlify.com>
Date: Wed, 11 Feb 2026 20:59:35 -0500
Subject: [PATCH] feat: add input to filter package versions by semver

Add a text input to the versions section that filters displayed versions by any valid npm semver
range (e.g. `^3.0.0`, `>=2.0.0 <3.0.0`, `~1.5.0`). It filters tag rows, expanded child versions, and
"other versions" groups as-you-type. It shows an indication when the input is not a valid range, and
a "no matches" message when nothing matches. It has a tooltip linking to a new docs page explaining
npm semver ranges
---
 app/components/AppFooter.vue                 |   8 +-
 app/components/AppHeader.vue                 |   3 +-
 app/components/Package/Versions.vue          | 155 +++++++++++++--
 app/utils/versions.ts                        |  30 ++-
 docs/content/2.guide/5.semver-ranges.md      |  58 ++++++
 i18n/locales/en.json                         |   8 +-
 i18n/locales/fr-FR.json                      |   8 +-
 i18n/schema.json                             |  18 ++
 lunaria/files/en-GB.json                     |   8 +-
 lunaria/files/en-US.json                     |   8 +-
 lunaria/files/fr-FR.json                     |   8 +-
 shared/utils/constants.ts                    |   1 +
 test/nuxt/components/PackageVersions.spec.ts | 187 +++++++++++++++++++
 test/unit/app/utils/versions.spec.ts         |  45 +++++
 14 files changed, 523 insertions(+), 22 deletions(-)
 create mode 100644 docs/content/2.guide/5.semver-ranges.md

diff --git a/app/components/AppFooter.vue b/app/components/AppFooter.vue
index b7e745377..ad0c82daf 100644
--- a/app/components/AppFooter.vue
+++ b/app/components/AppFooter.vue
@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { NPMX_DOCS_SITE } from '#shared/utils/constants'
+
 const route = useRoute()
 const isHome = computed(() => route.name === 'index')
 
@@ -13,7 +15,9 @@ const showModal = () => modalRef.value?.showModal?.()
         class="flex flex-col sm:flex-row sm:flex-wrap items-center sm:items-baseline justify-between gap-2 sm:gap-4"
       >
         <div>
-          <p class="font-mono text-balance m-0 hidden sm:block">{{ $t('tagline') }}</p>
+          <p class="font-mono text-balance m-0 hidden sm:block">
+            {{ $t('tagline') }}
+          </p>
         </div>
         <!-- Desktop: Show all links. Mobile: Links are in MobileMenu -->
         <div class="hidden sm:flex items-center gap-6 min-h-11 text-xs">
@@ -92,7 +96,7 @@ const showModal = () => modalRef.value?.showModal?.()
               </li>
             </ul>
           </Modal>
-          <LinkBase to="https://docs.npmx.dev">
+          <LinkBase :to="NPMX_DOCS_SITE">
             {{ $t('footer.docs') }}
           </LinkBase>
           <LinkBase to="https://repo.npmx.dev">
diff --git a/app/components/AppHeader.vue b/app/components/AppHeader.vue
index 17112d530..f05dbb014 100644
--- a/app/components/AppHeader.vue
+++ b/app/components/AppHeader.vue
@@ -2,6 +2,7 @@
 import { LinkBase } from '#components'
 import type { NavigationConfig, NavigationConfigWithGroups } from '~/types'
 import { isEditableElement } from '~/utils/input'
+import { NPMX_DOCS_SITE } from '#shared/utils/constants'
 
 withDefaults(
   defineProps<{
@@ -85,7 +86,7 @@ const mobileLinks = computed<NavigationConfigWithGroups>(() => [
       {
         name: 'Docs',
         label: $t('footer.docs'),
-        href: 'https://docs.npmx.dev',
+        href: NPMX_DOCS_SITE,
         target: '_blank',
         type: 'link',
         external: true,
diff --git a/app/components/Package/Versions.vue b/app/components/Package/Versions.vue
index a6d71461a..2a9b2b7d6 100644
--- a/app/components/Package/Versions.vue
+++ b/app/components/Package/Versions.vue
@@ -1,11 +1,13 @@
 <script setup lang="ts">
 import type { PackageVersionInfo, SlimVersion } from '#shared/types'
-import { compare } from 'semver'
+import { compare, validRange } from 'semver'
 import type { RouteLocationRaw } from 'vue-router'
 import { fetchAllPackageVersions } from '~/utils/npm/api'
+import { NPMX_DOCS_SITE } from '#shared/utils/constants'
 import {
   buildVersionToTagsMap,
   filterExcludedTags,
+  filterVersions,
   getPrereleaseChannel,
   getVersionGroupKey,
   getVersionGroupLabel,
@@ -83,6 +85,31 @@ const effectiveCurrentVersion = computed(
   () => props.selectedVersion ?? props.distTags.latest ?? undefined,
 )
 
+// Semver range filter
+const semverFilter = ref('')
+// Collect all known versions: initial props + dynamically loaded ones
+const allKnownVersions = computed(() => {
+  const versions = new Set(Object.keys(props.versions))
+  for (const versionList of tagVersions.value.values()) {
+    for (const v of versionList) {
+      versions.add(v.version)
+    }
+  }
+  for (const group of otherMajorGroups.value) {
+    for (const v of group.versions) {
+      versions.add(v.version)
+    }
+  }
+  return [...versions]
+})
+const filteredVersionSet = computed(() =>
+  filterVersions(allKnownVersions.value, semverFilter.value),
+)
+const isFilterActive = computed(() => semverFilter.value.trim() !== '')
+const isInvalidRange = computed(
+  () => isFilterActive.value && validRange(semverFilter.value.trim()) === null,
+)
+
 // All tag rows derived from props (SSR-safe)
 // Deduplicates so each version appears only once, with all its tags
 const allTagRows = computed(() => {
@@ -135,10 +162,16 @@ const isPackageDeprecated = computed(() => {
 
 // Visible tag rows: limited to MAX_VISIBLE_TAGS
 // If package is NOT deprecated, filter out deprecated tags from visible list
+// When semver filter is active, also filter by matching version
 const visibleTagRows = computed(() => {
-  const rows = isPackageDeprecated.value
+  const rowsMaybeFilteredForDeprecation = isPackageDeprecated.value
     ? allTagRows.value
     : allTagRows.value.filter(row => !row.primaryVersion.deprecated)
+  const rows = isFilterActive.value
+    ? rowsMaybeFilteredForDeprecation.filter(row =>
+        filteredVersionSet.value.has(row.primaryVersion.version),
+      )
+    : rowsMaybeFilteredForDeprecation
   const first = rows.slice(0, MAX_VISIBLE_TAGS)
   const latestTagRow = rows.find(row => row.tag === 'latest')
   // Ensure 'latest' tag is always included (at the end) if not already present
@@ -150,9 +183,14 @@ const visibleTagRows = computed(() => {
 })
 
 // Hidden tag rows (all other tags) - shown in "Other versions"
-const hiddenTagRows = computed(() =>
-  allTagRows.value.filter(row => !visibleTagRows.value.includes(row)),
-)
+// When semver filter is active, also filter by matching version
+const hiddenTagRows = computed(() => {
+  const hiddenRows = allTagRows.value.filter(row => !visibleTagRows.value.includes(row))
+  const rows = isFilterActive.value
+    ? hiddenRows.filter(row => filteredVersionSet.value.has(row.primaryVersion.version))
+    : hiddenRows
+  return rows
+})
 
 // Client-side state for expansion and loaded versions
 const expandedTags = ref<Set<string>>(new Set())
@@ -166,6 +204,27 @@ const otherMajorGroups = shallowRef<
 >([])
 const otherVersionsLoading = shallowRef(false)
 
+// Filtered major groups (applies semver filter when active)
+const filteredOtherMajorGroups = computed(() => {
+  if (!isFilterActive.value) return otherMajorGroups.value
+  return otherMajorGroups.value
+    .map(group => ({
+      ...group,
+      versions: group.versions.filter(v => filteredVersionSet.value.has(v.version)),
+    }))
+    .filter(group => group.versions.length > 0)
+})
+
+// Whether the filter is active but nothing matches anywhere
+const hasNoFilterMatches = computed(() => {
+  if (!isFilterActive.value) return false
+  return (
+    visibleTagRows.value.length === 0 &&
+    hiddenTagRows.value.length === 0 &&
+    filteredOtherMajorGroups.value.length === 0
+  )
+})
+
 // Cached full version list (local to component instance)
 const allVersionsCache = shallowRef<PackageVersionInfo[] | null>(null)
 const loadingVersions = shallowRef(false)
@@ -340,6 +399,13 @@ function getTagVersions(tag: string): VersionDisplay[] {
   return tagVersions.value.get(tag) ?? []
 }
 
+// Get filtered versions for a tag (applies semver filter when active)
+function getFilteredTagVersions(tag: string): VersionDisplay[] {
+  const versions = getTagVersions(tag)
+  if (!isFilterActive.value) return versions
+  return versions.filter(v => filteredVersionSet.value.has(v.version))
+}
+
 function findClaimingTag(version: string): string | null {
   const versionChannel = getPrereleaseChannel(version)
 
@@ -418,6 +484,61 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
       </ButtonBase>
     </template>
     <div class="space-y-0.5 min-w-0">
+      <!-- Semver range filter -->
+      <div class="px-1 pb-1">
+        <div class="flex items-center gap-1.5">
+          <InputBase
+            v-model="semverFilter"
+            type="text"
+            :placeholder="$t('package.versions.filter_placeholder')"
+            :aria-label="$t('package.versions.filter_placeholder')"
+            :aria-invalid="isInvalidRange ? 'true' : undefined"
+            :aria-describedby="isInvalidRange ? 'semver-filter-error' : undefined"
+            autocomplete="off"
+            class="flex-1 min-w-0"
+            :class="isInvalidRange ? '!border-red-500' : ''"
+            size="small"
+          />
+          <TooltipApp interactive position="top">
+            <span
+              tabindex="0"
+              class="i-carbon:information w-3.5 h-3.5 text-fg-subtle cursor-help shrink-0 rounded-sm"
+              role="img"
+              :aria-label="$t('package.versions.filter_help')"
+            />
+            <template #content>
+              <p class="text-xs text-fg-muted">
+                <i18n-t keypath="package.versions.filter_tooltip" tag="span">
+                  <template #link>
+                    <LinkBase :to="`${NPMX_DOCS_SITE}/guide/semver-ranges`">{{
+                      $t('package.versions.filter_tooltip_link')
+                    }}</LinkBase>
+                  </template>
+                </i18n-t>
+              </p>
+            </template>
+          </TooltipApp>
+        </div>
+        <p
+          v-if="isInvalidRange"
+          id="semver-filter-error"
+          class="text-red-500 text-3xs mt-1"
+          role="alert"
+        >
+          {{ $t('package.versions.filter_invalid') }}
+        </p>
+      </div>
+
+      <!-- No matches message -->
+      <div
+        v-if="hasNoFilterMatches"
+        class="px-1 py-2 text-xs text-fg-subtle"
+        role="status"
+        aria-live="polite"
+      >
+        {{ $t('package.versions.no_matches') }}
+      </div>
+
       <!-- Dist-tag rows (limited to MAX_VISIBLE_TAGS) -->
       <div v-for="row in visibleTagRows" :key="row.id">
         <div
@@ -512,11 +633,11 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
 
         <!-- Expanded versions -->
         <div
-          v-if="expandedTags.has(row.tag) && getTagVersions(row.tag).length > 1"
+          v-if="expandedTags.has(row.tag) && getFilteredTagVersions(row.tag).length > 1"
           class="ms-4 ps-2 border-is border-border space-y-0.5 pe-2"
         >
           <div
-            v-for="v in getTagVersions(row.tag).slice(1)"
+            v-for="v in getFilteredTagVersions(row.tag).slice(1)"
             :key="v.version"
             class="py-1"
             :class="v.version === effectiveCurrentVersion ? 'rounded bg-bg-subtle px-2 -mx-2' : ''"
@@ -533,7 +654,9 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
                 "
                 :title="
                   v.deprecated
-                    ? $t('package.versions.deprecated_title', { version: v.version })
+                    ? $t('package.versions.deprecated_title', {
+                        version: v.version,
+                      })
                     : v.version
                 "
                 :classicon="v.deprecated ? 'i-carbon-warning-hex' : undefined"
@@ -676,8 +799,8 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
           </div>
 
           <!-- Version groups (untagged versions) -->
-          <template v-if="otherMajorGroups.length > 0">
-            <div v-for="group in otherMajorGroups" :key="group.groupKey">
+          <template v-if="filteredOtherMajorGroups.length > 0">
+            <div v-for="group in filteredOtherMajorGroups" :key="group.groupKey">
               <!-- Version group header -->
               <div
                 v-if="group.versions.length > 1"
@@ -692,8 +815,12 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
                       :aria-expanded="expandedMajorGroups.has(group.groupKey)"
                       :aria-label="
                         expandedMajorGroups.has(group.groupKey)
-                          ? $t('package.versions.collapse_major', { major: group.label })
-                          : $t('package.versions.expand_major', { major: group.label })
+                          ? $t('package.versions.collapse_major', {
+                              major: group.label,
+                            })
+                          : $t('package.versions.expand_major', {
+                              major: group.label,
+                            })
                       "
                       data-testid="major-group-expand-button"
                       @click="toggleMajorGroup(group.groupKey)"
@@ -852,7 +979,9 @@ function majorGroupContainsCurrent(group: (typeof otherMajorGroups.value)[0]): b
                       "
                       :title="
                         v.deprecated
-                          ? $t('package.versions.deprecated_title', { version: v.version })
+                          ? $t('package.versions.deprecated_title', {
+                              version: v.version,
+                            })
                           : v.version
                       "
                       :classicon="v.deprecated ? 'i-carbon-warning-hex' : undefined"
diff --git a/app/utils/versions.ts b/app/utils/versions.ts
index bdc39ca59..88f3c4bc3 100644
--- a/app/utils/versions.ts
+++ b/app/utils/versions.ts
@@ -1,4 +1,4 @@
-import { compare, valid } from 'semver'
+import { compare, satisfies, validRange, valid } from 'semver'
 
 /**
  * Utilities for handling npm package versions and dist-tags
@@ -179,3 +179,31 @@ export function getVersionGroupLabel(groupKey: string): string {
 export function isSameVersionGroup(versionA: string, versionB: string): boolean {
   return getVersionGroupKey(versionA) === getVersionGroupKey(versionB)
 }
+
+/**
+ * Filter versions by a semver range string.
+ *
+ * @param versions - Array of version strings to filter
+ * @param range - A semver range string (e.g., "^3.0.0", ">=2.0.0 <3.0.0")
+ * @returns Set of version strings that satisfy the range.
+ *   Returns all versions if range is empty/whitespace.
+ *   Returns empty set if range is invalid.
+ */
+export function filterVersions(versions: string[], range: string): Set<string> {
+  const trimmed = range.trim()
+  if (trimmed === '') {
+    return new Set(versions)
+  }
+
+  if (!validRange(trimmed)) {
+    return new Set()
+  }
+
+  const matched = new Set<string>()
+  for (const v of versions) {
+    if (satisfies(v, trimmed, { includePrerelease: true })) {
+      matched.add(v)
+    }
+  }
+  return matched
+}
diff --git a/docs/content/2.guide/5.semver-ranges.md b/docs/content/2.guide/5.semver-ranges.md
new file mode 100644
index 000000000..0c7708468
--- /dev/null
+++ b/docs/content/2.guide/5.semver-ranges.md
@@ -0,0 +1,58 @@
+---
+title: Semver Ranges
+description: Learn how to use semver ranges to filter package versions on npmx.dev
+navigation:
+  icon: i-lucide-filter
+---
+
+npm uses [semantic versioning](https://semver.org/) (semver) to manage package versions. A **semver range** is a string that describes a set of version numbers. On npmx, you can type a semver range into the version filter input on any package page to quickly find matching versions.
+
+## Version format
+
+Every npm version follows the format **MAJOR.MINOR.PATCH**, for example `3.2.1`:
+
+- **MAJOR** - incremented for breaking changes
+- **MINOR** - incremented for new features (backwards-compatible)
+- **PATCH** - incremented for bug fixes (backwards-compatible)
+
+Some versions also include a **prerelease** tag, such as `4.0.0-beta.1`.
+
+## Common range syntax
+
+| Range            | Meaning                                           | Example matches      |
+| ---------------- | ------------------------------------------------- | -------------------- |
+| `*`              | Any version                                       | 0.0.2, 3.1.0, 3.2.6  |
+| `^3.0.0`         | Compatible with 3.x (same major)                  | 3.0.0, 3.1.0, 3.9.5  |
+| `~3.2.0`         | At least 3.2.0, same major.minor                  | 3.2.0, 3.2.1, 3.2.99 |
+| `3.2.x`          | At least 3.2.0, same major.minor                  | 3.2.0, 3.2.1, 3.2.99 |
+| `>=2.0.0 <3.0.0` | At least 2.0.0 but below 3.0.0                    | 2.0.0, 2.5.3, 2.99.0 |
+| `1.2.3`          | Exactly this version                              | 1.2.3                |
+| `=1.2.3`         | Exactly this version                              | 1.2.3                |
+| `^0.3.1`         | At least 0.3.1, same major.minor (0.x is special) | 0.3.1, 0.3.2         |
+| `^0.0.4`         | Exactly 0.0.4 (0.0.x is special)                  | 0.0.4 (only)         |
+
+## Examples
+
+### Find all 3.x versions
+
+Type `^3.0.0` to see every version compatible with major version 3.
+
+### Find patch releases for a specific minor
+
+Type `~2.4.0` to see only 2.4.x patch releases (2.4.0, 2.4.1, 2.4.2, etc.).
+
+### Find versions in a specific range
+
+Type `>=1.0.0 <2.0.0` to see all 1.x stable releases.
+
+### Find a specific version
+
+Type the exact version number, like `5.3.1`, to check if it exists.
+
+### Find prerelease versions
+
+Type `>=3.0.0-alpha.0` to find alpha, beta, and release candidate versions for a major release.
+
+## Learn more
+
+The full semver range specification is documented at [node-semver](https://github.com/npm/node-semver#ranges).
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index d31897846..e483a2f77 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -300,7 +300,13 @@
       "show_low_usage": "Show low usage versions",
       "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads.",
       "date_range_tooltip": "Last week of version distributions only",
-      "y_axis_label": "Downloads"
+      "y_axis_label": "Downloads",
+      "filter_placeholder": "Filter by semver (e.g. ^3.0.0)",
+      "filter_invalid": "Invalid semver range",
+      "filter_help": "Semver range filter help",
+      "filter_tooltip": "Filter versions using a {link}. For example, ^3.0.0 shows all 3.x versions.",
+      "filter_tooltip_link": "semver range",
+      "no_matches": "No versions match this range"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
diff --git a/i18n/locales/fr-FR.json b/i18n/locales/fr-FR.json
index dc3fc9f86..0d5db6c31 100644
--- a/i18n/locales/fr-FR.json
+++ b/i18n/locales/fr-FR.json
@@ -278,7 +278,13 @@
       "more_tagged": "{count} de plus avec tag",
       "all_covered": "Toutes les versions sont couvertes par les tags ci-dessus",
       "deprecated_title": "{version} (dépréciée)",
-      "view_all": "Voir la version | Voir les {count} versions"
+      "view_all": "Voir la version | Voir les {count} versions",
+      "filter_placeholder": "Filtrer par plage semver (ex. ^3.0.0)",
+      "filter_invalid": "Plage semver invalide",
+      "filter_help": "Infos sur le filtre de plage semver",
+      "filter_tooltip": "Filtrer les versions avec une {link}. Par exemple, ^3.0.0 affiche toutes les versions 3.x.",
+      "filter_tooltip_link": "plage semver",
+      "no_matches": "Aucune version ne correspond à cette plage"
     },
     "dependencies": {
       "title": "Dépendances ({count})",
diff --git a/i18n/schema.json b/i18n/schema.json
index d9cd30e97..5604780cd 100644
--- a/i18n/schema.json
+++ b/i18n/schema.json
@@ -906,6 +906,24 @@
             },
             "y_axis_label": {
               "type": "string"
+            },
+            "filter_placeholder": {
+              "type": "string"
+            },
+            "filter_invalid": {
+              "type": "string"
+            },
+            "filter_help": {
+              "type": "string"
+            },
+            "filter_tooltip": {
+              "type": "string"
+            },
+            "filter_tooltip_link": {
+              "type": "string"
+            },
+            "no_matches": {
+              "type": "string"
             }
           },
           "additionalProperties": false
diff --git a/lunaria/files/en-GB.json b/lunaria/files/en-GB.json
index ec4fb804e..bb8076de4 100644
--- a/lunaria/files/en-GB.json
+++ b/lunaria/files/en-GB.json
@@ -299,7 +299,13 @@
       "show_low_usage": "Show low usage versions",
       "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads.",
       "date_range_tooltip": "Last week of version distributions only",
-      "y_axis_label": "Downloads"
+      "y_axis_label": "Downloads",
+      "filter_placeholder": "Filter by semver (e.g. ^3.0.0)",
+      "filter_invalid": "Invalid semver range",
+      "filter_help": "Semver range filter help",
+      "filter_tooltip": "Filter versions using a {link}. For example, ^3.0.0 shows all 3.x versions.",
+      "filter_tooltip_link": "semver range",
+      "no_matches": "No versions match this range"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
diff --git a/lunaria/files/en-US.json b/lunaria/files/en-US.json
index c7acc9fdb..f9b9ccfc2 100644
--- a/lunaria/files/en-US.json
+++ b/lunaria/files/en-US.json
@@ -299,7 +299,13 @@
       "show_low_usage": "Show low usage versions",
       "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads.",
       "date_range_tooltip": "Last week of version distributions only",
-      "y_axis_label": "Downloads"
+      "y_axis_label": "Downloads",
+      "filter_placeholder": "Filter by semver (e.g. ^3.0.0)",
+      "filter_invalid": "Invalid semver range",
+      "filter_help": "Semver range filter help",
+      "filter_tooltip": "Filter versions using a {link}. For example, ^3.0.0 shows all 3.x versions.",
+      "filter_tooltip_link": "semver range",
+      "no_matches": "No versions match this range"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
diff --git a/lunaria/files/fr-FR.json b/lunaria/files/fr-FR.json
index 56caacd0a..82a67b75b 100644
--- a/lunaria/files/fr-FR.json
+++ b/lunaria/files/fr-FR.json
@@ -277,7 +277,13 @@
       "more_tagged": "{count} de plus avec tag",
       "all_covered": "Toutes les versions sont couvertes par les tags ci-dessus",
       "deprecated_title": "{version} (dépréciée)",
-      "view_all": "Voir la version | Voir les {count} versions"
+      "view_all": "Voir la version | Voir les {count} versions",
+      "filter_placeholder": "Filtrer par plage semver (ex. ^3.0.0)",
+      "filter_invalid": "Plage semver invalide",
+      "filter_help": "Infos sur le filtre de plage semver",
+      "filter_tooltip": "Filtrer les versions avec une {link}. Par exemple, ^3.0.0 affiche toutes les versions 3.x.",
+      "filter_tooltip_link": "plage semver",
+      "no_matches": "Aucune version ne correspond à cette plage"
     },
     "dependencies": {
       "title": "Dépendances ({count})",
diff --git a/shared/utils/constants.ts b/shared/utils/constants.ts
index 4d940ce93..7ef81ff83 100644
--- a/shared/utils/constants.ts
+++ b/shared/utils/constants.ts
@@ -9,6 +9,7 @@ export const CACHE_MAX_AGE_ONE_YEAR = 60 * 60 * 24 * 365
 
 // API Strings
 export const NPMX_SITE = 'https://npmx.dev'
+export const NPMX_DOCS_SITE = 'https://docs.npmx.dev'
 export const BLUESKY_API = 'https://public.api.bsky.app'
 export const BLUESKY_COMMENTS_REQUEST = '/api/atproto/bluesky-comments'
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
diff --git a/test/nuxt/components/PackageVersions.spec.ts b/test/nuxt/components/PackageVersions.spec.ts
index 30bed4630..fab403e0f 100644
--- a/test/nuxt/components/PackageVersions.spec.ts
+++ b/test/nuxt/components/PackageVersions.spec.ts
@@ -928,6 +928,193 @@ describe('PackageVersions', () => {
     })
   })
 
+  describe('semver range filter', () => {
+    const multiVersionProps = {
+      packageName: 'test-package',
+      versions: {
+        '3.0.0': createVersion('3.0.0'),
+        '2.1.0': createVersion('2.1.0'),
+        '2.0.0': createVersion('2.0.0'),
+        '1.0.0': createVersion('1.0.0'),
+      },
+      distTags: {
+        latest: '3.0.0',
+        stable: '2.1.0',
+        legacy: '1.0.0',
+      },
+      time: {
+        '3.0.0': '2024-04-01T00:00:00.000Z',
+        '2.1.0': '2024-03-01T00:00:00.000Z',
+        '2.0.0': '2024-02-01T00:00:00.000Z',
+        '1.0.0': '2024-01-01T00:00:00.000Z',
+      },
+    }
+
+    it('renders the filter input', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      expect(input.exists()).toBe(true)
+      expect(input.attributes('placeholder')).toContain('semver')
+    })
+
+    it('filters visible tag rows by semver range', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('^2.0.0')
+
+      // 2.1.0 matches ^2.0.0, so the "stable" tag row should be visible
+      const text = component.text()
+      expect(text).toContain('2.1.0')
+      // 3.0.0 does NOT match ^2.0.0
+      // Find version links (exclude anchor and external links)
+      const versionLinks = component
+        .findAll('a')
+        .filter(a => !a.attributes('href')?.startsWith('#') && a.attributes('target') !== '_blank')
+      const versions = versionLinks.map(l => l.text())
+      expect(versions).not.toContain('3.0.0')
+    })
+
+    it('shows "no matches" message when no versions match', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('^99.0.0')
+
+      expect(component.text()).toContain('No versions match this range')
+    })
+
+    it('no matches message has aria-live for screen readers', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('^99.0.0')
+
+      const noMatchesEl = component.find('[role="status"]')
+      expect(noMatchesEl.exists()).toBe(true)
+      expect(noMatchesEl.attributes('aria-live')).toBe('polite')
+    })
+
+    it('shows all versions when filter is cleared', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('^2.0.0')
+      await input.setValue('')
+
+      // All tag rows should be visible again
+      const text = component.text()
+      expect(text).toContain('3.0.0')
+      expect(text).toContain('2.1.0')
+      expect(text).toContain('1.0.0')
+    })
+
+    it('shows invalid range indicator for bad input', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('not-a-range!!!')
+
+      // Error message should appear
+      const errorEl = component.find('#semver-filter-error')
+      expect(errorEl.exists()).toBe(true)
+      expect(errorEl.attributes('role')).toBe('alert')
+
+      // Input should be marked invalid
+      expect(input.attributes('aria-invalid')).toBe('true')
+      expect(input.attributes('aria-describedby')).toBe('semver-filter-error')
+    })
+
+    it('does not show invalid range indicator for valid input', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('^2.0.0')
+
+      expect(component.find('#semver-filter-error').exists()).toBe(false)
+      expect(input.attributes('aria-invalid')).toBeUndefined()
+    })
+
+    it('does not show invalid range indicator when input is empty', async () => {
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      const input = component.find('input[type="text"]')
+      await input.setValue('')
+
+      expect(component.find('#semver-filter-error').exists()).toBe(false)
+    })
+
+    it('filters expanded tag child versions', async () => {
+      mockFetchAllPackageVersions.mockResolvedValue([
+        { version: '3.0.0', time: '2024-04-01T00:00:00.000Z', hasProvenance: false },
+        { version: '2.1.0', time: '2024-03-01T00:00:00.000Z', hasProvenance: false },
+        { version: '2.0.0', time: '2024-02-01T00:00:00.000Z', hasProvenance: false },
+        { version: '1.0.0', time: '2024-01-01T00:00:00.000Z', hasProvenance: false },
+      ])
+
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      // Expand the "stable" tag (2.1.0)
+      const expandButtons = component.findAll('[data-testid="tag-expand-button"]')
+      const stableButton = expandButtons.find(btn =>
+        btn.attributes('aria-label')?.includes('stable'),
+      )
+      expect(stableButton?.exists()).toBe(true)
+      await stableButton!.trigger('click')
+      await vi.waitFor(() => {
+        expect(mockFetchAllPackageVersions).toHaveBeenCalled()
+      })
+
+      // Now filter to only 2.1.x
+      const input = component.find('input[type="text"]')
+      await input.setValue('~2.1.0')
+
+      // 2.0.0 should not appear in the expanded list
+      await vi.waitFor(() => {
+        const versionLinks = component
+          .findAll('a')
+          .filter(
+            a => !a.attributes('href')?.startsWith('#') && a.attributes('target') !== '_blank',
+          )
+        const versions = versionLinks.map(l => l.text())
+        expect(versions).not.toContain('2.0.0')
+      })
+    })
+
+    it('filters other major version groups', async () => {
+      mockFetchAllPackageVersions.mockResolvedValue([
+        { version: '3.0.0', time: '2024-04-01T00:00:00.000Z', hasProvenance: false },
+        { version: '2.1.0', time: '2024-03-01T00:00:00.000Z', hasProvenance: false },
+        { version: '2.0.0', time: '2024-02-01T00:00:00.000Z', hasProvenance: false },
+        { version: '1.0.0', time: '2024-01-01T00:00:00.000Z', hasProvenance: false },
+        { version: '0.5.0', time: '2023-06-01T00:00:00.000Z', hasProvenance: false },
+      ])
+
+      const component = await mountSuspended(PackageVersions, { props: multiVersionProps })
+
+      // Expand "Other versions"
+      const otherVersionsButton = component
+        .findAll('button')
+        .find(btn => btn.text().includes('Other versions'))
+      await otherVersionsButton!.trigger('click')
+
+      await vi.waitFor(() => {
+        expect(mockFetchAllPackageVersions).toHaveBeenCalled()
+      })
+
+      // Filter to >=2.0.0
+      const input = component.find('input[type="text"]')
+      await input.setValue('>=2.0.0')
+
+      // 0.5.0 should not appear
+      await vi.waitFor(() => {
+        const text = component.text()
+        expect(text).not.toContain('0.5.0')
+      })
+    })
+  })
+
   describe('error handling', () => {
     it('handles fetch errors gracefully', async () => {
       mockFetchAllPackageVersions.mockRejectedValue(new Error('Network error'))
diff --git a/test/unit/app/utils/versions.spec.ts b/test/unit/app/utils/versions.spec.ts
index cde36f99d..c15b864f5 100644
--- a/test/unit/app/utils/versions.spec.ts
+++ b/test/unit/app/utils/versions.spec.ts
@@ -3,6 +3,7 @@ import {
   buildTaggedVersionRows,
   buildVersionToTagsMap,
   filterExcludedTags,
+  filterVersions,
   getPrereleaseChannel,
   getVersionGroupKey,
   getVersionGroupLabel,
@@ -421,3 +422,47 @@ describe('isSameVersionGroup', () => {
     expect(isSameVersionGroup('0.5.0-beta.1', '0.6.0')).toBe(false)
   })
 })
+
+describe('filterVersions', () => {
+  const versions = ['1.0.0', '1.1.0', '1.5.3', '2.0.0', '2.1.0', '3.0.0-beta.1']
+
+  it('returns all versions for empty range', () => {
+    expect(filterVersions(versions, '')).toEqual(new Set(versions))
+  })
+
+  it('returns all versions for whitespace-only range', () => {
+    expect(filterVersions(versions, '   ')).toEqual(new Set(versions))
+  })
+
+  it('matches exact version', () => {
+    expect(filterVersions(versions, '1.0.0')).toEqual(new Set(['1.0.0']))
+  })
+
+  it('matches caret range', () => {
+    expect(filterVersions(versions, '^1.0.0')).toEqual(new Set(['1.0.0', '1.1.0', '1.5.3']))
+  })
+
+  it('matches tilde range', () => {
+    expect(filterVersions(versions, '~1.0.0')).toEqual(new Set(['1.0.0']))
+    expect(filterVersions(versions, '~1.1.0')).toEqual(new Set(['1.1.0']))
+  })
+
+  it('matches complex range', () => {
+    // 3.0.0-beta.1 is included because with includePrerelease it is < 3.0.0
+    expect(filterVersions(versions, '>=2.0.0 <3.0.0')).toEqual(
+      new Set(['2.0.0', '2.1.0', '3.0.0-beta.1']),
+    )
+  })
+
+  it('matches prerelease versions with includePrerelease', () => {
+    expect(filterVersions(versions, '>=3.0.0-beta.0')).toEqual(new Set(['3.0.0-beta.1']))
+  })
+
+  it('returns empty set for invalid range', () => {
+    expect(filterVersions(versions, 'not-a-range!!!')).toEqual(new Set())
+  })
+
+  it('returns empty set for empty versions array', () => {
+    expect(filterVersions([], '^1.0.0')).toEqual(new Set())
+  })
+})