updated with changes from coderabbit's comments

Author: mihaizaurus

app/types/index.ts

@@ -10,5 +10,9 @@ declare module '#app' {
      * @default 70
      */
     scrollMargin?: number
+    /**
+     * preserve scroll position when only query params change on same path/hash
+     */
+    preserveScrollOnQuery?: boolean
   }
 }

test/unit/app/router.options.spec.ts

@@ -1,13 +1,17 @@
 import { describe, expect, it } from 'vitest'
 import routerOptions from '../../../app/router.options'
 
-function createRoute(overrides: Record<string, unknown> = {}) {
+type ScrollBehavior = NonNullable<typeof routerOptions.scrollBehavior>
+type RouteArg = Parameters<ScrollBehavior>[0]
+
+function createRoute(overrides: Partial<RouteArg> = {}) {
   return {
     path: '/',
     hash: '',
+    query: {},
     meta: {},
     ...overrides,
-  } as any
+  } as RouteArg
 }
 
 describe('router scrollBehavior', () => {
@@ -22,16 +26,31 @@ describe('router scrollBehavior', () => {
   it('preserves scroll on query-only updates for pages that opt in', () => {
     const to = createRoute({
       path: '/compare',
+      query: { packages: 'vue,nuxt', facets: 'downloads,license' },
       meta: { preserveScrollOnQuery: true },
     })
     const from = createRoute({
       path: '/compare',
+      query: { packages: 'vue', facets: 'downloads' },
       meta: { preserveScrollOnQuery: true },
     })
 
     expect(routerOptions.scrollBehavior(to, from, null)).toBe(false)
   })
 
+  it('does not preserve scroll on query-only updates without opt-in', () => {
+    const to = createRoute({
+      path: '/compare',
+      query: { packages: 'vue,nuxt', facets: 'downloads,license' },
+    })
+    const from = createRoute({
+      path: '/compare',
+      query: { packages: 'vue', facets: 'downloads' },
+    })
+
+    expect(routerOptions.scrollBehavior(to, from, null)).toEqual({ left: 0, top: 0 })
+  })
+
   it('scrolls to hash anchors', () => {
     const to = createRoute({
       hash: '#section-function',