fix(pages): keep refresh in place and write preserveState hash visits

- router.refresh() goes through one shared helper used by the core and
  React routers. React's copy still pushed a new history entry.
- refresh() keeps the URL hash; it now replaces the entry, which dropped
  it. An internal _refresh flag stops it from being taken as a hash-only
  visit, so the page is still fetched.
- Same-page hash visits write history with preserveState too, like other
  visits.
- A replaced history entry keeps its scroll key, so repeated refreshes
  no longer add a saved position each time.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: Brooooooklyn

docs/guide/pages-routing/overview.md

@@ -208,7 +208,7 @@ import { useRouter } from '@void/vue'; // or "@void/react", "@void/svelte", "@vo
 
 const router = useRouter();
 router.visit('/users');
-router.refresh(); // re-fetch current page props
+router.refresh(); // re-fetch current page props, keeping the same history entry
 router.visit('/logout', { method: 'POST' }); // non-GET navigation
 ```
 

packages/react/src/runtime/pages-client.ts

@@ -19,6 +19,7 @@ import {
   idleNavigationState,
   isAbortError,
   isCallSiteActionError,
+  refreshPage,
   type PageNavigationResource,
   type PageNavigationResult,
   type NavigationState,
@@ -295,11 +296,7 @@ function createRouter(engine: Awaited<ReturnType<typeof createPageNavigationEngi
       return scheduleVisit(normalizeUrl(url), options);
     },
     refresh(options = {}) {
-      return router.visit(window.location.pathname + window.location.search, {
-        preserveState: true,
-        preserveScroll: true,
-        ...options,
-      });
+      return refreshPage(router, options);
     },
     prefetch(url, options = {}) {
       return engine.prefetch(normalizeUrl(url), options);

packages/void/src/pages/client.ts

@@ -219,6 +219,21 @@ export function createSsrRouter(url = '/', params: Record<string, string> = {}):
 
 export const ssrProxy: VoidRouter = createSsrRouter();
 
+/** Refetch the current page in place: same history entry, URL hash, state and scroll. */
+export function refreshPage(
+  router: Pick<VoidRouter, 'visit'>,
+  options: VisitOptions = {},
+): Promise<unknown> {
+  const { pathname, search, hash } = window.location;
+  return router.visit(pathname + search + hash, {
+    preserveState: true,
+    preserveScroll: true,
+    replace: true,
+    ...options,
+    _refresh: true,
+  });
+}
+
 export async function submitAction(
   router: VoidRouter,
   url: string,
@@ -398,12 +413,7 @@ export async function createVoidRouter(config: VoidRouterConfig): Promise<{
     },
 
     refresh(options = {}) {
-      return router.visit(window.location.pathname + window.location.search, {
-        preserveState: true,
-        preserveScroll: true,
-        replace: true,
-        ...options,
-      });
+      return refreshPage(router, options);
     },
 
     prefetch(url, options = {}) {

packages/void/src/pages/navigation-engine.ts

@@ -38,6 +38,8 @@ export type VisitOptions = {
   _scrollPosition?: { x: number; y: number } | null;
   /** @internal Used by popstate handler to avoid writing history while traversing */
   _popstate?: boolean;
+  /** @internal Used by router.refresh() to refetch the current URL even when it has a hash */
+  _refresh?: boolean;
 };
 
 export type PrefetchOptions = {
@@ -952,18 +954,14 @@ export async function createPageNavigationEngine(
       _pendingResource = null;
 
       const isSamePageHashNavigation =
+        !options._refresh &&
         effectiveFetchUrl === hashNavigationBaseUrl &&
         method === 'GET' &&
         !options.data &&
         Boolean(hash || options._popstate);
 
       if (isSamePageHashNavigation) {
-        commitHashNavigation(
-          effectiveFetchUrl,
-          hash,
-          options,
-          !options._popstate && !options.preserveState,
-        );
+        commitHashNavigation(effectiveFetchUrl, hash, options, !options._popstate);
         return {
           id,
           url,

packages/void/src/pages/scroll-restoration.ts

@@ -94,7 +94,8 @@ export function createScrollRestoration(): ScrollRestoration {
     save,
 
     writeHistory(url: string, replace: boolean): void {
-      renderedKey = newKey();
+      // A replaced entry keeps its key: its position is saved again when it is left.
+      renderedKey = (replace ? readKey(history.state) : null) ?? newKey();
       const state = { ...(replace ? history.state : {}), __voidScrollKey: renderedKey };
       if (replace) {
         history.replaceState(state, '', url);

packages/void/test/unit/pages-client.test.ts

@@ -689,7 +689,7 @@ describe('createVoidRouter', () => {
     expect(window.scrollTo).toHaveBeenCalledWith(0, 42);
   });
 
-  it('does not write history for same-page hash visits when state is preserved', async () => {
+  it('writes history for same-page hash visits when state is preserved', async () => {
     stubClientGlobals();
     window.location.pathname = '/docs';
     window.location.search = '?tab=api';
@@ -702,7 +702,11 @@ describe('createVoidRouter', () => {
 
     expect(fetch).not.toHaveBeenCalled();
     expect(applyUpdate).not.toHaveBeenCalled();
-    expect(history.pushState).not.toHaveBeenCalled();
+    expect(history.pushState).toHaveBeenCalledWith(
+      expect.objectContaining({ __voidScrollKey: expect.any(String) }),
+      '',
+      '/docs?tab=api#section',
+    );
     expect(history.replaceState).not.toHaveBeenCalled();
     expect(window.scrollTo).toHaveBeenCalledWith(0, 0);
   });
@@ -1299,14 +1303,22 @@ describe('preserveState history updates (#506)', () => {
     );
   });
 
-  it('does not add a history entry on router.refresh()', async () => {
+  it('refetches the current URL in place on router.refresh(), hash included', async () => {
     const { applyUpdate } = setup();
+    window.location.search = '?tab=a';
+    window.location.hash = '#top';
     const r = await router(applyUpdate);
 
     await r.refresh();
 
+    expect(fetch).toHaveBeenCalledWith('/case?tab=a', expect.anything());
     expect(applyUpdate.mock.calls[0][3]).toEqual({ preserveState: true });
     expect(history.pushState).not.toHaveBeenCalled();
+    expect(history.replaceState).toHaveBeenCalledWith(
+      expect.objectContaining({ __voidScrollKey: expect.any(String) }),
+      '',
+      '/case?tab=a#top',
+    );
   });
 
   it('does not write history for back/forward navigation', async () => {

packages/void/test/unit/pages-scroll.test.ts

@@ -193,6 +193,34 @@ describe('Pages scroll restoration', () => {
     expect(returned.window.scrollTo).toHaveBeenCalledExactlyOnceWith(0, 3500);
   });
 
+  it('keeps one saved position for an entry that is replaced again and again', async () => {
+    const page = await setup();
+    page.engine.start();
+    page.engine.commitInitialRender();
+    const state = structuredClone(page.history.state);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () =>
+        Response.json({ component: 'home', props: {} }, { headers: { 'X-VoidPages': 'true' } }),
+      ),
+    );
+    for (const scrollY of [100, 200, 300]) {
+      page.window.scrollY = scrollY;
+      const visit = page.engine.prepareVisit('/', { replace: true, preserveState: true });
+      await visit.shell;
+      await visit.commit();
+    }
+    expect(page.history.state).toEqual(state);
+    expect(page.storage.size).toBe(1);
+
+    page.window.scrollY = 900;
+    page.window.dispatchEvent(new Event('pagehide'));
+    const returned = await setup(state, page.storage);
+    returned.engine.start();
+    returned.engine.commitInitialRender();
+    expect(returned.window.scrollTo).toHaveBeenCalledExactlyOnceWith(0, 900);
+  });
+
   it('uses the latest in-memory position when a storage write fails', async () => {
     const page = await setup();
     page.engine.start();