refactor: centralize search provider resolution and SSR payload bridging

- Deduplicate provider resolution into single `resolvedSearchProvider` computed
- Extract shared `bridgeSSRPayload()` utility to prevent hydration mismatches
- Update e2e tests to cover org suggestion keyboard navigation

Author: gusa4grr

app/components/SearchProviderToggle.client.vue

@@ -1,12 +1,7 @@
 <script setup lang="ts">
 const route = useRoute()
 const router = useRouter()
-const { searchProvider } = useSearchProvider()
-const searchProviderValue = computed(() => {
-  const p = normalizeSearchParam(route.query.p)
-  if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-  return 'algolia'
-})
+const { searchProvider, resolvedSearchProvider: searchProviderValue } = useSearchProvider()
 
 const isOpen = shallowRef(false)
 const toggleRef = useTemplateRef('toggleRef')

app/composables/npm/search-utils.ts

@@ -1,3 +1,30 @@
+/**
+ * Bridge SSR payload when the resolved search provider on the client differs
+ * from the server default ('algolia'). Copies the SSR-cached data to the
+ * client's cache key so `useLazyAsyncData` hydrates without a refetch.
+ *
+ * Must be called at composable setup time (not inside an async callback).
+ */
+export function bridgeSSRPayload(
+  prefix: string,
+  identifier: MaybeRefOrGetter<string>,
+  provider: MaybeRefOrGetter<string>,
+): void {
+  if (import.meta.client) {
+    const nuxtApp = useNuxtApp()
+    const id = toValue(identifier)
+    const p = toValue(provider)
+
+    if (nuxtApp.isHydrating && id && p !== 'algolia') {
+      const ssrKey = `${prefix}:algolia:${id}`
+      const clientKey = `${prefix}:${p}:${id}`
+      if (nuxtApp.payload.data[ssrKey] && !nuxtApp.payload.data[clientKey]) {
+        nuxtApp.payload.data[clientKey] = nuxtApp.payload.data[ssrKey]
+      }
+    }
+  }
+}
+
 export function metaToSearchResult(meta: PackageMetaResponse): NpmSearchResult {
   return {
     package: {

app/composables/npm/useOrgPackages.ts

@@ -1,3 +1,5 @@
+import { bridgeSSRPayload } from './search-utils'
+
 /**
  * Fetch all packages for an npm organization.
  *
@@ -6,15 +8,11 @@
  * 3. Falls back to lightweight server-side package-meta lookups
  */
 export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
-  const route = useRoute()
-  const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const { resolvedSearchProvider: searchProviderValue } = useSearchProvider()
   const { getPackagesByName } = useAlgoliaSearch()
 
+  bridgeSSRPayload('org-packages', orgName, searchProviderValue)
+
   const asyncData = useLazyAsyncData(
     () => `org-packages:${searchProviderValue.value}:${toValue(orgName)}`,
     async ({ ssrContext }, { signal }) => {

app/composables/npm/useSearch.ts

@@ -1,4 +1,5 @@
 import type { SearchProvider } from '#shared/schemas/userPreferences'
+import { bridgeSSRPayload } from './search-utils'
 
 function emptySearchPayload() {
   return {
@@ -138,22 +139,7 @@ export function useSearch(
     suggestionsLoading.value = false
   }
 
-  // Bridge SSR payload when provider differs between server and client.
-  // SSR always uses the default provider ('algolia'), but the client may
-  // read a different provider from localStorage. Copy the SSR data to the
-  // client's cache key so useLazyAsyncData can hydrate without a mismatch.
-  if (import.meta.client) {
-    const nuxtApp = useNuxtApp()
-    const q = toValue(query)
-    const provider = toValue(searchProvider)
-    if (nuxtApp.isHydrating && q && provider !== 'algolia') {
-      const ssrKey = `search:algolia:${q}`
-      const clientKey = `search:${provider}:${q}`
-      if (nuxtApp.payload.data[ssrKey] && !nuxtApp.payload.data[clientKey]) {
-        nuxtApp.payload.data[clientKey] = nuxtApp.payload.data[ssrKey]
-      }
-    }
-  }
+  bridgeSSRPayload('search', query, searchProvider)
 
   const asyncData = useLazyAsyncData(
     () => `search:${toValue(searchProvider)}:${toValue(query)}`,

app/composables/npm/useUserPackages.ts

@@ -1,3 +1,5 @@
+import { bridgeSSRPayload } from './search-utils'
+
 /** Default page size for incremental loading (npm registry path) */
 const PAGE_SIZE = 50 as const
 
@@ -19,13 +21,7 @@ const MAX_RESULTS = 250
  * ```
  */
 export function useUserPackages(username: MaybeRefOrGetter<string>) {
-  const route = useRoute()
-  const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const { resolvedSearchProvider: searchProviderValue } = useSearchProvider()
   // this is only used in npm path, but we need to extract it when the composable runs
   const { $npmRegistry } = useNuxtApp()
   const { searchByOwner } = useAlgoliaSearch()
@@ -37,6 +33,8 @@ export function useUserPackages(username: MaybeRefOrGetter<string>) {
    *  searchProvider when Algolia returns empty and we fall through to npm) */
   const activeProvider = shallowRef<'npm' | 'algolia'>(searchProviderValue.value)
 
+  bridgeSSRPayload('user-packages', username, searchProviderValue)
+
   const cache = shallowRef<{
     username: string
     objects: NpmSearchResult[]

app/composables/useGlobalSearch.ts

@@ -1,4 +1,3 @@
-import { normalizeSearchParam } from '#shared/utils/url'
 import { debounce } from 'perfect-debounce'
 
 // Pages that have their own local filter using ?q
@@ -8,12 +7,7 @@ const SEARCH_DEBOUNCE_MS = 100
 
 export function useGlobalSearch(place: 'header' | 'content' = 'content') {
   const instantSearch = useInstantSearchPreference()
-  const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const { searchProvider, resolvedSearchProvider: searchProviderValue } = useSearchProvider()
 
   const router = useRouter()
   const route = useRoute()
@@ -36,7 +30,7 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
   // This is basically doing instant search as user types
   watch(searchQuery, val => {
     if (instantSearch.value) {
-      commitSearchQuery(val)
+      void commitSearchQuery(val)
     }
   })
 
@@ -52,14 +46,15 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
 
   // Updates URL when search query changes (immediately for instantSearch or after Enter hit otherwise)
   const updateUrlQueryImpl = (value: string, provider: 'npm' | 'algolia') => {
-    const isSameQuery = route.query.q === value && route.query.p === provider
+    const urlProvider = provider === 'npm' ? 'npm' : undefined
+    const isSameQuery = route.query.q === value && route.query.p === urlProvider
     // Don't navigate away from pages that use ?q for local filtering
     if ((pagesWithLocalFilter.has(route.name as string) && place === 'content') || isSameQuery) {
       return
     }
 
     if (route.name === 'search') {
-      router.replace({
+      void router.replace({
         query: {
           ...route.query,
           q: value || undefined,
@@ -68,7 +63,7 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
       })
       return
     }
-    router.push({
+    void router.push({
       name: 'search',
       query: {
         q: value,
@@ -104,7 +99,7 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
       if (!updateUrlQuery.isPending()) {
         updateUrlQueryImpl(value, searchProvider.value)
       }
-      updateUrlQuery(value, searchProvider.value)
+      void updateUrlQuery(value, searchProvider.value)
     },
   })
 

app/composables/userPreferences/useSearchProvider.ts

@@ -1,7 +1,9 @@
 import type { SearchProvider } from '#shared/schemas/userPreferences'
+import { normalizeSearchParam } from '#shared/utils/url'
 
 export function useSearchProvider() {
   const { preferences } = useUserPreferencesState()
+  const route = useRoute()
 
   const searchProvider = computed({
     get: () => preferences.value.searchProvider ?? 'algolia',
@@ -10,14 +12,23 @@ export function useSearchProvider() {
     },
   })
 
-  const isAlgolia = computed(() => searchProvider.value === 'algolia')
+  // Resolved provider: merges URL query param override with persisted preference.
+  // URL ?p=npm takes priority; otherwise falls back to the saved preference.
+  const resolvedSearchProvider = computed<SearchProvider>(() => {
+    const p = normalizeSearchParam(route.query.p)
+    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
+    return 'algolia'
+  })
+
+  const isAlgolia = computed(() => resolvedSearchProvider.value === 'algolia')
 
   function toggle() {
     searchProvider.value = searchProvider.value === 'npm' ? 'algolia' : 'npm'
   }
 
   return {
     searchProvider,
+    resolvedSearchProvider,
     isAlgolia,
     toggle,
   }

test/e2e/interactions.spec.ts

@@ -102,15 +102,19 @@ test.describe('Search Pages', () => {
     const firstResult = page.locator('[data-result-index="0"]').first()
     await expect(firstResult).toBeVisible()
 
-    // Global keyboard navigation works regardless of focus
-    // ArrowDown selects the next result
+    // Wait for the @vue org suggestion card to appear
+    const orgSuggestion = page.locator('[data-suggestion-index="0"]')
+    await expect(orgSuggestion).toBeVisible({ timeout: 10000 })
+
+    // ArrowDown focuses the org suggestion card
     await page.keyboard.press('ArrowDown')
 
-    // ArrowUp selects the previous result
+    // ArrowUp returns to the search input
     await page.keyboard.press('ArrowUp')
 
-    // Enter navigates to the selected result
+    // ArrowDown again, then Enter navigates to the suggestion
     // URL is /package/vue or /org/vue or /user/vue. Not /vue
+    await page.keyboard.press('ArrowDown')
     await page.keyboard.press('Enter')
     await expect(page).toHaveURL(/\/(package|org|user)\/vue/)
   })
@@ -130,16 +134,24 @@ test.describe('Search Pages', () => {
     await expect(firstResult).toBeVisible()
     await expect(secondResult).toBeVisible()
 
-    // ArrowDown from input focuses the first result
+    // Wait for the @vue org suggestion card to appear
+    const orgSuggestion = page.locator('[data-suggestion-index="0"]')
+    await expect(orgSuggestion).toBeVisible({ timeout: 10000 })
+
+    // ArrowDown focuses the org suggestion first
+    await page.keyboard.press('ArrowDown')
+    await expect(orgSuggestion).toBeFocused()
+
+    // Next ArrowDown focuses the first package result
     await page.keyboard.press('ArrowDown')
     await expect(firstResult).toBeFocused()
 
-    // Second ArrowDown focuses the second result (not a keyword button within the first)
+    // Next ArrowDown focuses the second result (not a keyword button within the first)
     await page.keyboard.press('ArrowDown')
     await expect(secondResult).toBeFocused()
   })
 
-  test('/search?q=vue → ArrowUp from first result returns focus to search input', async ({
+  test('/search?q=vue → ArrowUp from first result navigates back through suggestions to input', async ({
     page,
     goto,
   }) => {
@@ -149,11 +161,22 @@ test.describe('Search Pages', () => {
       timeout: 15000,
     })
 
-    // Navigate to first result
+    // Wait for the @vue org suggestion card to appear
+    const orgSuggestion = page.locator('[data-suggestion-index="0"]')
+    await expect(orgSuggestion).toBeVisible({ timeout: 10000 })
+
+    // Navigate: suggestion → first package result
+    await page.keyboard.press('ArrowDown')
+    await expect(orgSuggestion).toBeFocused()
+
     await page.keyboard.press('ArrowDown')
     await expect(page.locator('[data-result-index="0"]').first()).toBeFocused()
 
-    // ArrowUp returns to the search input
+    // ArrowUp goes back to the org suggestion
+    await page.keyboard.press('ArrowUp')
+    await expect(orgSuggestion).toBeFocused()
+
+    // ArrowUp from suggestion returns to the search input
     await page.keyboard.press('ArrowUp')
     await expect(page.locator('input[type="search"]')).toBeFocused()
   })