From 2de6a60104743d6d57584fc44ac68fcbd0af56b5 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Sun, 26 Apr 2026 18:53:27 -0400
Subject: [PATCH 1/2] refactor: accept versioned route builder in cmd palette

The placeholder shape made callers that already had named-route helpers
resolve routes to strings and then patch encoded placeholders back into
place. That was brittle, especially for routes where Vue Router encodes
params differently from the URL shape users see.

We have a documented guideline that internal navigation should use
route object syntax with named routes instead of strings. This commit
allows callers to respect that guideline.
---
 .../useCommandPaletteVersionCommands.ts       | 15 ++++++++------
 .../[packageName]/v/[versionRange].vue        | 20 +++++++++----------
 .../v/[version]/[...filePath].vue             | 12 ++++++++++-
 app/pages/package-docs/[...path].vue          | 15 +++++++++++++-
 app/pages/package/[[org]]/[name].vue          |  4 +++-
 .../use-command-palette-commands.spec.ts      | 12 +++++------
 6 files changed, 52 insertions(+), 26 deletions(-)

diff --git a/app/composables/useCommandPaletteVersionCommands.ts b/app/composables/useCommandPaletteVersionCommands.ts
index ecc676e50f..f02b563795 100644
--- a/app/composables/useCommandPaletteVersionCommands.ts
+++ b/app/composables/useCommandPaletteVersionCommands.ts
@@ -1,5 +1,6 @@
 // @unocss-include
-import type { MaybeRefOrGetter } from 'vue'
+import type { MaybeRef, MaybeRefOrGetter } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import type {
   CommandPaletteCommand,
   CommandPaletteContextCommandInput,
@@ -7,6 +8,8 @@ import type {
 } from '~/types/command-palette'
 import { compare, satisfies, validRange } from 'semver'
 
+type CommandPaletteVersionRoute = (version: string) => RouteLocationRaw
+
 function getSortedVersions(context: CommandPalettePackageContext) {
   return [...context.versions].sort((a, b) => {
     if (a === context.resolvedVersion) return -1
@@ -19,7 +22,7 @@ function createVersionCommands(
   context: CommandPalettePackageContext,
   t: ReturnType<typeof useI18n>['t'],
   versions = getSortedVersions(context),
-  urlPattern?: string | null,
+  routeForVersion?: CommandPaletteVersionRoute | null,
 ): CommandPaletteCommand[] {
   return versions.map(version => ({
     id: `version:${version}`,
@@ -28,13 +31,13 @@ function createVersionCommands(
     keywords: [context.packageName, version, t('command_palette.groups.versions')],
     iconClass: 'i-lucide:tag',
     active: version === context.resolvedVersion,
-    to: urlPattern?.replace('{version}', version) ?? packageRoute(context.packageName, version),
+    to: routeForVersion?.(version) ?? packageRoute(context.packageName, version),
   }))
 }
 
 export function useCommandPaletteVersionCommands(
   context: MaybeRefOrGetter<CommandPalettePackageContext | null>,
-  urlPattern?: MaybeRefOrGetter<string | null | undefined>,
+  routeForVersion?: MaybeRef<CommandPaletteVersionRoute | null | undefined>,
 ) {
   const { t } = useI18n()
 
@@ -43,7 +46,7 @@ export function useCommandPaletteVersionCommands(
       const resolvedContext = toValue(context)
       if (!resolvedContext?.resolvedVersion) return []
 
-      return createVersionCommands(resolvedContext, t, undefined, toValue(urlPattern))
+      return createVersionCommands(resolvedContext, t, undefined, unref(routeForVersion))
     }),
   )
 
@@ -58,6 +61,6 @@ export function useCommandPaletteVersionCommands(
       satisfies(version, semverRange, { includePrerelease: true }),
     )
 
-    return createVersionCommands(resolvedContext, t, matchingVersions, toValue(urlPattern))
+    return createVersionCommands(resolvedContext, t, matchingVersions, unref(routeForVersion))
   })
 }
diff --git a/app/pages/diff/[[org]]/[packageName]/v/[versionRange].vue b/app/pages/diff/[[org]]/[packageName]/v/[versionRange].vue
index 1bc6ac2c94..3da147500d 100644
--- a/app/pages/diff/[[org]]/[packageName]/v/[versionRange].vue
+++ b/app/pages/diff/[[org]]/[packageName]/v/[versionRange].vue
@@ -116,19 +116,19 @@ const latestVersionDetailed = computed(() => {
   return pkg.value.versions[latestTag] ?? null
 })
 
-const normalizeRoutePath = (routeLocation: RouteLocationRaw) => {
-  const resolvedHref = router.resolve(routeLocation).href
-  return resolvedHref.replace(/%7B/g, '{').replace(/%7D/g, '}')
+function diffVersionUrlPattern(from: string, to: string) {
+  const { org, packageName: name } = route.params
+  return `/diff/${org ? `${org}/` : ''}${name}/v/${from}...${to}`
 }
 
-const fromVersionUrlPattern = computed(() => {
-  return normalizeRoutePath(diffRoute(packageName.value, '{version}', toVersion.value))
-})
-const toVersionUrlPattern = computed(() => {
-  return normalizeRoutePath(diffRoute(packageName.value, fromVersion.value, '{version}'))
-})
+const fromVersionUrlPattern = computed(() => diffVersionUrlPattern('{version}', toVersion.value))
+const toVersionUrlPattern = computed(() => diffVersionUrlPattern(fromVersion.value, '{version}'))
+
+function fromVersionRoute(version: string): RouteLocationRaw {
+  return diffRoute(packageName.value, version, toVersion.value)
+}
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, fromVersionUrlPattern)
+useCommandPaletteVersionCommands(commandPalettePackageContext, fromVersionRoute)
 
 useSeoMeta({
   title: () => {
diff --git a/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue b/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
index 8c2e43988d..8bdfa23c43 100644
--- a/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
+++ b/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { RouteLocationRaw } from 'vue-router'
 import type { CommandPaletteContextCommandInput } from '~/types/command-palette'
 
 // Maximum file size we'll try to load (500KB) - must match server
@@ -86,7 +87,16 @@ const versionUrlPattern = computed(() =>
   }),
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+function codeVersionRoute(nextVersion: string): RouteLocationRaw {
+  return getCodeUrl({
+    org: route.params.org,
+    packageName: route.params.packageName,
+    version: nextVersion,
+    filePath: filePath.value,
+  })
+}
+
+useCommandPaletteVersionCommands(commandPalettePackageContext, codeVersionRoute)
 
 // Fetch file tree
 const { data: fileTree, status: treeStatus } = useFetch<PackageFileTreeResponse>(
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index d07a3d023d..e37dd28134 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { RouteLocationRaw } from 'vue-router'
 import { setResponseHeader } from 'h3'
 
 definePageMeta({
@@ -123,7 +124,19 @@ const versionUrlPattern = computed(
   () => `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`,
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+function docsVersionRoute(version: string): RouteLocationRaw {
+  const name = pkg.value?.name || packageName.value
+  const [firstSegment = name, ...remainingSegments] = name.split('/')
+
+  return {
+    name: 'docs',
+    params: {
+      path: [firstSegment, ...remainingSegments, 'v', version],
+    },
+  }
+}
+
+useCommandPaletteVersionCommands(commandPalettePackageContext, docsVersionRoute)
 
 const pageTitle = computed(() => {
   if (!packageName.value) return t('package.docs.page_title')
diff --git a/app/pages/package/[[org]]/[name].vue b/app/pages/package/[[org]]/[name].vue
index f88876e753..fa965e1e67 100644
--- a/app/pages/package/[[org]]/[name].vue
+++ b/app/pages/package/[[org]]/[name].vue
@@ -487,7 +487,9 @@ const versionUrlPattern = computed(
   () => `/package/${pkg.value?.name || packageName.value}/v/{version}`,
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+useCommandPaletteVersionCommands(commandPalettePackageContext, version =>
+  packageRoute(packageName.value, version),
+)
 
 const dependencyCount = computed(() => getDependencyCount(displayVersion.value))
 
diff --git a/test/nuxt/composables/use-command-palette-commands.spec.ts b/test/nuxt/composables/use-command-palette-commands.spec.ts
index 778e4ea8f4..650e51de18 100644
--- a/test/nuxt/composables/use-command-palette-commands.spec.ts
+++ b/test/nuxt/composables/use-command-palette-commands.spec.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { computed, defineComponent, h, ref, watchEffect, type Ref } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import { mockNuxtImport, mountSuspended } from '@nuxt/test-utils/runtime'
 import { downloadPackageTarball } from '~/utils/package-download'
 import type {
@@ -49,7 +50,7 @@ async function captureCommandPalette(options?: {
   npmUser?: string | null
   atprotoHandle?: string | null
   packageContext?: CommandPalettePackageContext | null
-  versionUrlPattern?: string
+  versionRoute?: (version: string) => RouteLocationRaw
   contextCommands?: CommandPaletteContextCommandInput[]
 }) {
   const groupedCommands = ref<CommandPaletteCommandGroup[]>([]) as Ref<CommandPaletteCommandGroup[]>
@@ -76,10 +77,7 @@ async function captureCommandPalette(options?: {
       if (options?.packageContext) {
         setPackageContext(options.packageContext)
         useCommandPalettePackageCommands(() => options.packageContext ?? null)
-        useCommandPaletteVersionCommands(
-          () => options.packageContext ?? null,
-          () => options.versionUrlPattern,
-        )
+        useCommandPaletteVersionCommands(() => options.packageContext ?? null, options.versionRoute)
       } else {
         clearPackageContext()
       }
@@ -345,7 +343,7 @@ describe('useCommandPaletteCommands', () => {
     wrapper.unmount()
   })
 
-  it('keeps version navigation on the current surface when a version URL pattern is provided', async () => {
+  it('keeps version navigation on the current surface when a version route builder is provided', async () => {
     const { wrapper, flatCommands, routePath } = await captureCommandPalette({
       route: '/package-code/vue/v/3.4.2/src/index.ts',
       packageContext: {
@@ -354,7 +352,7 @@ describe('useCommandPaletteCommands', () => {
         latestVersion: '4.0.0',
         versions: ['4.0.0', '3.5.0', '3.4.2'],
       },
-      versionUrlPattern: '/package-code/vue/v/{version}/src/index.ts',
+      versionRoute: version => `/package-code/vue/v/${version}/src/index.ts`,
     })
 
     const versionCommand = flatCommands.value.find(command => command.id === 'version:3.5.0')

From 4f54ad43f6a61bec5177dc6aa224a2a68e5d2b84 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Wed, 29 Apr 2026 11:44:08 -0400
Subject: [PATCH 2/2] feat: add the new package timeline page to the command
 palette (#2636)

---
 app/components/Package/Header.vue             | 10 +-------
 .../useCommandPalettePackageCommands.ts       | 14 +++++++++++
 .../[[org]]/[packageName].vue                 | 23 +++++++++++++++++++
 app/utils/router.ts                           | 13 +++++++++++
 .../use-command-palette-commands.spec.ts      | 16 +++++++++++++
 5 files changed, 67 insertions(+), 9 deletions(-)

diff --git a/app/components/Package/Header.vue b/app/components/Package/Header.vue
index 571dff4264..8af227e8a9 100644
--- a/app/components/Package/Header.vue
+++ b/app/components/Package/Header.vue
@@ -164,15 +164,7 @@ const diffLink = computed((): RouteLocationRaw | null => {
 
 const timelineLink = computed((): RouteLocationRaw | null => {
   if (props.pkg == null || props.resolvedVersion == null) return null
-  const split = props.pkg.name.split('/')
-  return {
-    name: 'timeline',
-    params: {
-      org: split.length === 2 ? split[0] : undefined,
-      packageName: split.length === 2 ? split[1]! : split[0]!,
-      version: props.resolvedVersion,
-    },
-  }
+  return packageTimelineRoute(props.pkg.name, props.resolvedVersion)
 })
 
 useShortcuts({
diff --git a/app/composables/useCommandPalettePackageCommands.ts b/app/composables/useCommandPalettePackageCommands.ts
index 5533acd5c4..cf09fa5997 100644
--- a/app/composables/useCommandPalettePackageCommands.ts
+++ b/app/composables/useCommandPalettePackageCommands.ts
@@ -88,6 +88,20 @@ export function useCommandPalettePackageCommands(
           activeLabel: activeLabel(route.name === 'code', t('command_palette.here')),
           to: codeLink,
         },
+        {
+          id: 'package-timeline',
+          group: 'package',
+          label: t('package.links.timeline'),
+          keywords: [
+            resolvedContext.packageName,
+            t('shortcuts.open_timeline'),
+            t('package.links.timeline'),
+          ],
+          iconClass: 'i-lucide:history',
+          active: route.name === 'timeline',
+          activeLabel: activeLabel(route.name === 'timeline', t('command_palette.here')),
+          to: packageTimelineRoute(resolvedContext.packageName, resolvedContext.resolvedVersion),
+        },
         {
           id: 'package-compare',
           group: 'package',
diff --git a/app/pages/package-timeline/[[org]]/[packageName].vue b/app/pages/package-timeline/[[org]]/[packageName].vue
index bb9f577eb0..d368494258 100644
--- a/app/pages/package-timeline/[[org]]/[packageName].vue
+++ b/app/pages/package-timeline/[[org]]/[packageName].vue
@@ -22,6 +22,8 @@ const packageName = computed(() =>
 const version = computed(() => route.params.version)
 
 const { data: pkg } = usePackage(packageName, version)
+const { versions: commandPaletteVersions, ensureLoaded: ensureCommandPaletteVersionsLoaded } =
+  useCommandPalettePackageVersions(packageName)
 
 const latestVersion = computed(() => {
   if (!pkg.value) return null
@@ -30,11 +32,32 @@ const latestVersion = computed(() => {
   return pkg.value.versions[latestTag] ?? null
 })
 
+const commandPalettePackageContext = computed(() => {
+  const packageData = pkg.value
+  if (!packageData) return null
+
+  return {
+    packageName: packageData.name,
+    resolvedVersion: version.value ?? packageData['dist-tags']?.latest ?? null,
+    latestVersion: packageData['dist-tags']?.latest ?? null,
+    versions: commandPaletteVersions.value ?? Object.keys(packageData.versions ?? {}),
+  }
+})
+
+useCommandPalettePackageContext(commandPalettePackageContext, {
+  onOpen: ensureCommandPaletteVersionsLoaded,
+})
+useCommandPalettePackageCommands(commandPalettePackageContext)
+
 const versionUrlPattern = computed(() => {
   const { org, packageName: name } = route.params
   return `/package-timeline/${org ? `${org}/` : ''}${name}/v/{version}`
 })
 
+useCommandPaletteVersionCommands(commandPalettePackageContext, nextVersion =>
+  packageTimelineRoute(packageName.value, nextVersion),
+)
+
 function packageRoute(ver: string): RouteLocationRaw {
   return {
     name: 'package-version',
diff --git a/app/utils/router.ts b/app/utils/router.ts
index ac3c9a46a6..7fcc8ad898 100644
--- a/app/utils/router.ts
+++ b/app/utils/router.ts
@@ -52,3 +52,16 @@ export function diffRoute(
     },
   }
 }
+
+export function packageTimelineRoute(packageName: string, version: string): RouteLocationRaw {
+  const { org, name } = splitPackageName(packageName)
+
+  return {
+    name: 'timeline',
+    params: {
+      org: org || undefined,
+      packageName: name,
+      version: version.replace(/\s+/g, ''),
+    },
+  }
+}
diff --git a/test/nuxt/composables/use-command-palette-commands.spec.ts b/test/nuxt/composables/use-command-palette-commands.spec.ts
index 650e51de18..ae56784db3 100644
--- a/test/nuxt/composables/use-command-palette-commands.spec.ts
+++ b/test/nuxt/composables/use-command-palette-commands.spec.ts
@@ -230,6 +230,14 @@ describe('useCommandPaletteCommands', () => {
     expect(flatCommands.value.find(command => command.id === 'package-diff')).toBeTruthy()
     expect(flatCommands.value.find(command => command.id === 'package-download')).toBeTruthy()
     expect(flatCommands.value.find(command => command.id === 'package-main')?.to).toBeTruthy()
+    expect(flatCommands.value.find(command => command.id === 'package-timeline')?.to).toEqual({
+      name: 'timeline',
+      params: {
+        org: undefined,
+        packageName: 'vue',
+        version: '3.4.0',
+      },
+    })
     expect(groupedCommands.value.at(-1)?.id).toBe('versions')
     expect(groupedCommands.value.at(-1)?.items[0]?.id).toBe('version:3.4.0')
     expect(groupedCommands.value.at(-1)?.items[0]?.active).toBe(true)
@@ -511,6 +519,14 @@ describe('useCommandPaletteCommands', () => {
         path: ['@scope', 'pkg', 'v', '1.0.0'],
       },
     })
+    expect(flatCommands.value.find(command => command.id === 'package-timeline')?.to).toEqual({
+      name: 'timeline',
+      params: {
+        org: '@scope',
+        packageName: 'pkg',
+        version: '1.0.0',
+      },
+    })
 
     wrapper.unmount()
   })