From 98f2c443ad2f717d56905d510fd02d26d2f71461 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 15:46:16 +0800
Subject: [PATCH 01/11] feat(theme): add ScrollRestoration for back/forward
 scroll position recovery

Previously, Rspress always scrolled to top on navigation, losing the user's
reading position when pressing browser back/forward. This adds a ScrollRestoration
component (inspired by React Router's ScrollRestoration) that:

- Saves scroll positions keyed by React Router's location.key
- Restores them on POP (back/forward) navigation
- Renders an inline <script> for pre-hydration restoration to avoid flash
- Persists positions to sessionStorage via pagehide for page reload support
---
 packages/core/src/theme/index.ts              |   2 +-
 .../core/src/theme/layout/Layout/index.tsx    |   4 +-
 .../src/theme/logic/ScrollRestoration.tsx     | 143 ++++++++++++++++++
 .../core/src/theme/logic/useScrollAfterNav.ts |   8 +-
 .../core/src/theme/logic/useScrollReset.ts    |  18 ---
 5 files changed, 153 insertions(+), 22 deletions(-)
 create mode 100644 packages/core/src/theme/logic/ScrollRestoration.tsx
 delete mode 100644 packages/core/src/theme/logic/useScrollReset.ts

diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index 06551af20d..9148d7c81d 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -105,11 +105,11 @@ export { Layout, type LayoutProps } from './layout/Layout/index';
 export { NotFoundLayout } from './layout/NotFountLayout/index';
 // logic
 export { mergeRefs } from './logic/mergeRefs';
+export { ScrollRestoration } from './logic/ScrollRestoration';
 export { useFullTextSearch } from './logic/useFullTextSearch';
 export { usePrevNextPage } from './logic/usePrevNextPage';
 export { useRedirect4FirstVisit } from './logic/useRedirect4FirstVisit';
 export { useScrollAfterNav } from './logic/useScrollAfterNav';
-export { useScrollReset } from './logic/useScrollReset';
 export { useSetup } from './logic/useSetup';
 export { useStorageValue } from './logic/useStorageValue';
 export { useThemeState } from './logic/useThemeState';
diff --git a/packages/core/src/theme/layout/Layout/index.tsx b/packages/core/src/theme/layout/Layout/index.tsx
index 56158fda3f..068e64919b 100644
--- a/packages/core/src/theme/layout/Layout/index.tsx
+++ b/packages/core/src/theme/layout/Layout/index.tsx
@@ -14,8 +14,8 @@ import {
   type DocLayoutProps,
   Nav,
   type NavProps,
+  ScrollRestoration,
   useRedirect4FirstVisit,
-  useScrollReset,
   useSetup,
 } from '@theme';
 import { Head, useHead } from '@unhead/react';
@@ -203,7 +203,6 @@ export function Layout(props: LayoutProps) {
   }
 
   useSetup();
-  useScrollReset();
   useRedirect4FirstVisit();
 
   const {
@@ -219,6 +218,7 @@ export function Layout(props: LayoutProps) {
         frontmatter={frontmatter}
       />
 
+      <ScrollRestoration />
       {top}
       {pageType !== 'blank' && showNavbar && (
         <>
diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
new file mode 100644
index 0000000000..5afd007836
--- /dev/null
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -0,0 +1,143 @@
+import { useLayoutEffect, useRef } from 'react';
+import { useLocation, useNavigationType } from 'react-router-dom';
+
+const STORAGE_KEY = 'rspress-scroll-positions';
+const SCROLL_THROTTLE_MS = 100;
+
+let savedScrollPositions: Record<string, number> = {};
+let isInitialized = false;
+
+function loadFromSessionStorage() {
+  try {
+    const stored = sessionStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      savedScrollPositions = JSON.parse(stored);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+function persistToSessionStorage() {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(savedScrollPositions));
+  } catch {
+    // ignore
+  }
+}
+
+// The inline script that runs before React hydration.
+// It reads the saved scroll position from sessionStorage and restores it immediately,
+// preventing a flash of wrong scroll position.
+const inlineScript = `(function(){
+  try {
+    var k = window.history.state && window.history.state.key;
+    if (k) {
+      var p = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
+      var y = p[k];
+      if (typeof y === 'number') {
+        window.history.scrollRestoration = 'manual';
+        window.scrollTo(0, y);
+      }
+    }
+  } catch(e) {}
+})()`;
+
+function useScrollRestoration() {
+  const location = useLocation();
+  const navigationType = useNavigationType();
+  const prevKeyRef = useRef<string | undefined>(undefined);
+
+  // Initialize: load from sessionStorage, take control of scroll restoration
+  useLayoutEffect(() => {
+    if (!isInitialized) {
+      loadFromSessionStorage();
+      isInitialized = true;
+    }
+    window.history.scrollRestoration = 'manual';
+    return () => {
+      window.history.scrollRestoration = 'auto';
+    };
+  }, []);
+
+  // Save scroll position continuously via throttled scroll listener
+  useLayoutEffect(() => {
+    let ticking = false;
+
+    const onScroll = () => {
+      if (ticking) {
+        return;
+      }
+      ticking = true;
+      setTimeout(() => {
+        const key = location.key;
+        if (key) {
+          savedScrollPositions[key] = window.scrollY;
+        }
+        ticking = false;
+      }, SCROLL_THROTTLE_MS);
+    };
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+    };
+  }, [location.key]);
+
+  // Persist to sessionStorage on pagehide
+  useLayoutEffect(() => {
+    const onPageHide = () => {
+      // Save current position one last time
+      const key = location.key;
+      if (key) {
+        savedScrollPositions[key] = window.scrollY;
+      }
+      persistToSessionStorage();
+    };
+    window.addEventListener('pagehide', onPageHide);
+    return () => {
+      window.removeEventListener('pagehide', onPageHide);
+    };
+  }, [location.key]);
+
+  // Handle scroll on navigation
+  useLayoutEffect(() => {
+    // Save previous page's scroll position
+    const prevKey = prevKeyRef.current;
+    if (prevKey) {
+      savedScrollPositions[prevKey] = window.scrollY;
+    }
+    prevKeyRef.current = location.key;
+
+    const hash = decodeURIComponent(window.location.hash);
+
+    if (navigationType === 'POP') {
+      // Back/forward: restore saved position
+      const savedY = location.key
+        ? savedScrollPositions[location.key]
+        : undefined;
+      if (typeof savedY === 'number') {
+        window.scrollTo(0, savedY);
+      }
+    } else if (hash.length === 0) {
+      // New navigation without hash: scroll to top
+      window.scrollTo(0, 0);
+    }
+    // With hash: do nothing here, let useScrollAfterNav handle it
+  }, [location, navigationType]);
+}
+
+/**
+ * @private
+ * @unstable
+ */
+export function ScrollRestoration() {
+  useScrollRestoration();
+
+  return (
+    <script
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: intentional inline script for pre-hydration scroll restoration
+      dangerouslySetInnerHTML={{ __html: inlineScript }}
+    />
+  );
+}
diff --git a/packages/core/src/theme/logic/useScrollAfterNav.ts b/packages/core/src/theme/logic/useScrollAfterNav.ts
index 0d2e8ff271..1163308485 100644
--- a/packages/core/src/theme/logic/useScrollAfterNav.ts
+++ b/packages/core/src/theme/logic/useScrollAfterNav.ts
@@ -1,5 +1,6 @@
 import { useLocation } from '@rspress/core/runtime';
 import { useLayoutEffect } from 'react';
+import { useNavigationType } from 'react-router-dom';
 
 /**
  * Parse CSS length value to number (in pixels)
@@ -48,11 +49,16 @@ function scrollToTarget(target: HTMLElement) {
  */
 export function useScrollAfterNav() {
   const location = useLocation();
+  const navigationType = useNavigationType();
 
   useLayoutEffect(() => {
     if (typeof window === 'undefined') {
       return;
     }
+    // On POP (back/forward), scroll position is restored by ScrollRestoration
+    if (navigationType === 'POP') {
+      return;
+    }
     const decodedHash = decodeURIComponent(window.location.hash);
     if (decodedHash.length > 0) {
       const target = document.getElementById(decodedHash.slice(1));
@@ -60,5 +66,5 @@ export function useScrollAfterNav() {
         scrollToTarget(target);
       }
     }
-  }, [location, location.pathname]);
+  }, [location, location.pathname, navigationType]);
 }
diff --git a/packages/core/src/theme/logic/useScrollReset.ts b/packages/core/src/theme/logic/useScrollReset.ts
deleted file mode 100644
index 071acfd84e..0000000000
--- a/packages/core/src/theme/logic/useScrollReset.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { useLayoutEffect } from 'react';
-import { useLocation } from 'react-router-dom';
-
-/**
- * @private
- * @unstable
- */
-export function useScrollReset() {
-  const { pathname } = useLocation();
-
-  useLayoutEffect(() => {
-    const decodedHash = decodeURIComponent(window.location.hash);
-    if (decodedHash.length === 0) {
-      window.scrollTo(0, 0);
-    }
-  }, [pathname]);
-  return;
-}

From c3fb72a2cb68757a5ac6b2d7fc97c71e18b37b98 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 16:08:26 +0800
Subject: [PATCH 02/11] chore: update

---
 packages/core/src/theme/layout/Layout/index.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/src/theme/layout/Layout/index.tsx b/packages/core/src/theme/layout/Layout/index.tsx
index 068e64919b..0293679e5f 100644
--- a/packages/core/src/theme/layout/Layout/index.tsx
+++ b/packages/core/src/theme/layout/Layout/index.tsx
@@ -218,7 +218,6 @@ export function Layout(props: LayoutProps) {
         frontmatter={frontmatter}
       />
 
-      <ScrollRestoration />
       {top}
       {pageType !== 'blank' && showNavbar && (
         <>
@@ -236,6 +235,7 @@ export function Layout(props: LayoutProps) {
 
       {getContentLayout()}
       {bottom}
+      <ScrollRestoration />
     </>
   );
 }

From 4571dc8d7d11dd1d0107e472a0a94cf5f4d7836e Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 16:12:06 +0800
Subject: [PATCH 03/11] refactor(theme): merge useScrollAfterNav into
 ScrollRestoration

Consolidate all scroll logic (restoration, scroll-to-top, hash anchor
scrolling) into the single ScrollRestoration component, removing the
separate useScrollAfterNav hook.
---
 .../src/theme/components/DocContent/index.tsx |  9 +--
 packages/core/src/theme/index.ts              |  1 -
 .../src/theme/logic/ScrollRestoration.tsx     | 42 ++++++++++-
 .../core/src/theme/logic/useScrollAfterNav.ts | 70 -------------------
 4 files changed, 41 insertions(+), 81 deletions(-)
 delete mode 100644 packages/core/src/theme/logic/useScrollAfterNav.ts

diff --git a/packages/core/src/theme/components/DocContent/index.tsx b/packages/core/src/theme/components/DocContent/index.tsx
index 3c8650f26b..1a6bad840c 100644
--- a/packages/core/src/theme/components/DocContent/index.tsx
+++ b/packages/core/src/theme/components/DocContent/index.tsx
@@ -1,11 +1,6 @@
 import { MDXProvider } from '@mdx-js/react';
 import { Content, usePage, useSite } from '@rspress/core/runtime';
-import {
-  Callout,
-  FallbackHeading,
-  getCustomMDXComponent,
-  useScrollAfterNav,
-} from '@theme';
+import { Callout, FallbackHeading, getCustomMDXComponent } from '@theme';
 import './doc.scss';
 
 function FallbackTitle() {
@@ -38,8 +33,6 @@ export function DocContent({
    */
   afterDocContent?: React.ReactNode;
 }) {
-  useScrollAfterNav();
-
   const mdxComponents = {
     ...getCustomMDXComponent(),
     ...components,
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index 9148d7c81d..543adcbfa0 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -109,7 +109,6 @@ export { ScrollRestoration } from './logic/ScrollRestoration';
 export { useFullTextSearch } from './logic/useFullTextSearch';
 export { usePrevNextPage } from './logic/usePrevNextPage';
 export { useRedirect4FirstVisit } from './logic/useRedirect4FirstVisit';
-export { useScrollAfterNav } from './logic/useScrollAfterNav';
 export { useSetup } from './logic/useSetup';
 export { useStorageValue } from './logic/useStorageValue';
 export { useThemeState } from './logic/useThemeState';
diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index 5afd007836..cda44944e5 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -26,6 +26,42 @@ function persistToSessionStorage() {
   }
 }
 
+/**
+ * Parse CSS length value to number (in pixels).
+ * Supports: px
+ */
+function parseCSSLength(value: string): number {
+  if (!value || value === 'auto' || value === 'none') {
+    return 0;
+  }
+
+  const numValue = Number.parseFloat(value);
+  if (Number.isNaN(numValue)) {
+    return 0;
+  }
+
+  return numValue;
+}
+
+function scrollToHashTarget(hash: string) {
+  const target = document.getElementById(hash.slice(1));
+  if (!target) {
+    return;
+  }
+
+  const scrollPaddingTop = parseCSSLength(
+    window
+      .getComputedStyle(document.documentElement)
+      .getPropertyValue('scroll-padding-top'),
+  );
+
+  const offsetTop = Math.round(
+    window.scrollY + target.getBoundingClientRect().top - scrollPaddingTop,
+  );
+
+  window.scrollTo({ left: 0, top: offsetTop });
+}
+
 // The inline script that runs before React hydration.
 // It reads the saved scroll position from sessionStorage and restores it immediately,
 // preventing a flash of wrong scroll position.
@@ -119,11 +155,13 @@ function useScrollRestoration() {
       if (typeof savedY === 'number') {
         window.scrollTo(0, savedY);
       }
-    } else if (hash.length === 0) {
+    } else if (hash.length > 0) {
+      // New navigation with hash: scroll to anchor (respecting scroll-padding-top)
+      scrollToHashTarget(hash);
+    } else {
       // New navigation without hash: scroll to top
       window.scrollTo(0, 0);
     }
-    // With hash: do nothing here, let useScrollAfterNav handle it
   }, [location, navigationType]);
 }
 
diff --git a/packages/core/src/theme/logic/useScrollAfterNav.ts b/packages/core/src/theme/logic/useScrollAfterNav.ts
deleted file mode 100644
index 1163308485..0000000000
--- a/packages/core/src/theme/logic/useScrollAfterNav.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { useLocation } from '@rspress/core/runtime';
-import { useLayoutEffect } from 'react';
-import { useNavigationType } from 'react-router-dom';
-
-/**
- * Parse CSS length value to number (in pixels)
- * Supports: px
- */
-function parseCSSLength(value: string): number {
-  if (!value || value === 'auto' || value === 'none') {
-    return 0;
-  }
-
-  const numValue = Number.parseFloat(value);
-  if (Number.isNaN(numValue)) {
-    return 0;
-  }
-
-  // For px or plain number, just return the numeric value
-  return numValue;
-}
-
-function getTargetTop(element: HTMLElement) {
-  // get scroll-padding-top from html
-  const scrollPaddingTop = parseCSSLength(
-    window
-      .getComputedStyle(document.documentElement)
-      .getPropertyValue('scroll-padding-top'),
-  );
-
-  const targetTop =
-    window.scrollY + element.getBoundingClientRect().top - scrollPaddingTop;
-
-  return Math.round(targetTop);
-}
-
-function scrollToTarget(target: HTMLElement) {
-  const offsetTop = getTargetTop(target);
-
-  window.scrollTo({
-    left: 0,
-    top: offsetTop,
-  });
-}
-
-/**
- * @private
- * @unstable
- */
-export function useScrollAfterNav() {
-  const location = useLocation();
-  const navigationType = useNavigationType();
-
-  useLayoutEffect(() => {
-    if (typeof window === 'undefined') {
-      return;
-    }
-    // On POP (back/forward), scroll position is restored by ScrollRestoration
-    if (navigationType === 'POP') {
-      return;
-    }
-    const decodedHash = decodeURIComponent(window.location.hash);
-    if (decodedHash.length > 0) {
-      const target = document.getElementById(decodedHash.slice(1));
-      if (target) {
-        scrollToTarget(target);
-      }
-    }
-  }, [location, location.pathname, navigationType]);
-}

From 498b88e99a1af07dd256f5109f6f55c762c1c49b Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 16:14:24 +0800
Subject: [PATCH 04/11] docs: add React Router ScrollRestoration reference link

---
 packages/core/src/theme/logic/ScrollRestoration.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index cda44944e5..9d3f061d2b 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -166,6 +166,8 @@ function useScrollRestoration() {
 }
 
 /**
+ * Scroll restoration component inspired by React Router's ScrollRestoration.
+ * @see https://reactrouter.com/api/components/ScrollRestoration
  * @private
  * @unstable
  */

From b4ac69064edd6ad346edfc637522c1db0a4087bb Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:05:02 +0800
Subject: [PATCH 05/11] chore: update

---
 .../src/theme/logic/ScrollRestoration.tsx     | 195 ++++++++++--------
 1 file changed, 110 insertions(+), 85 deletions(-)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index 9d3f061d2b..e03030764b 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -2,29 +2,9 @@ import { useLayoutEffect, useRef } from 'react';
 import { useLocation, useNavigationType } from 'react-router-dom';
 
 const STORAGE_KEY = 'rspress-scroll-positions';
-const SCROLL_THROTTLE_MS = 100;
 
+// Module-level state for scroll positions
 let savedScrollPositions: Record<string, number> = {};
-let isInitialized = false;
-
-function loadFromSessionStorage() {
-  try {
-    const stored = sessionStorage.getItem(STORAGE_KEY);
-    if (stored) {
-      savedScrollPositions = JSON.parse(stored);
-    }
-  } catch {
-    // ignore
-  }
-}
-
-function persistToSessionStorage() {
-  try {
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(savedScrollPositions));
-  } catch {
-    // ignore
-  }
-}
 
 /**
  * Parse CSS length value to number (in pixels).
@@ -43,10 +23,13 @@ function parseCSSLength(value: string): number {
   return numValue;
 }
 
-function scrollToHashTarget(hash: string) {
+/**
+ * Scroll to a hash target element, respecting scroll-padding-top.
+ */
+function scrollToHashTarget(hash: string): boolean {
   const target = document.getElementById(hash.slice(1));
   if (!target) {
-    return;
+    return false;
   }
 
   const scrollPaddingTop = parseCSSLength(
@@ -60,6 +43,47 @@ function scrollToHashTarget(hash: string) {
   );
 
   window.scrollTo({ left: 0, top: offsetTop });
+  return true;
+}
+
+/**
+ * Get the scroll restoration key from location.
+ * Uses location.key by default, which provides unique keys for each navigation.
+ */
+function getScrollRestorationKey(location: { key: string }): string {
+  return location.key;
+}
+
+/**
+ * Load scroll positions from sessionStorage.
+ */
+function loadSavedPositions(): void {
+  try {
+    const stored = sessionStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      savedScrollPositions = JSON.parse(stored);
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Persist scroll positions to sessionStorage.
+ */
+function persistSavedPositions(): void {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(savedScrollPositions));
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Generate a random key for history state if missing.
+ */
+function generateKey(): string {
+  return Math.random().toString(32).slice(2);
 }
 
 // The inline script that runs before React hydration.
@@ -67,99 +91,94 @@ function scrollToHashTarget(hash: string) {
 // preventing a flash of wrong scroll position.
 const inlineScript = `(function(){
   try {
-    var k = window.history.state && window.history.state.key;
-    if (k) {
-      var p = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
-      var y = p[k];
-      if (typeof y === 'number') {
-        window.history.scrollRestoration = 'manual';
-        window.scrollTo(0, y);
-      }
+    // Ensure history.state.key exists (React Router behavior)
+    if (!window.history.state || !window.history.state.key) {
+      var key = Math.random().toString(32).slice(2);
+      window.history.replaceState({ key: key }, "");
+    }
+    
+    var positions = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
+    var y = positions[window.history.state.key];
+    if (typeof y === 'number') {
+      window.history.scrollRestoration = 'manual';
+      window.scrollTo(0, y);
     }
   } catch(e) {}
 })()`;
 
+/**
+ * Hook for scroll restoration logic.
+ * Follows React Router's implementation closely.
+ */
 function useScrollRestoration() {
   const location = useLocation();
   const navigationType = useNavigationType();
   const prevKeyRef = useRef<string | undefined>(undefined);
+  const isRestoringRef = useRef(false);
 
   // Initialize: load from sessionStorage, take control of scroll restoration
   useLayoutEffect(() => {
-    if (!isInitialized) {
-      loadFromSessionStorage();
-      isInitialized = true;
-    }
+    loadSavedPositions();
     window.history.scrollRestoration = 'manual';
-    return () => {
-      window.history.scrollRestoration = 'auto';
-    };
   }, []);
 
-  // Save scroll position continuously via throttled scroll listener
-  useLayoutEffect(() => {
-    let ticking = false;
-
-    const onScroll = () => {
-      if (ticking) {
-        return;
-      }
-      ticking = true;
-      setTimeout(() => {
-        const key = location.key;
-        if (key) {
-          savedScrollPositions[key] = window.scrollY;
-        }
-        ticking = false;
-      }, SCROLL_THROTTLE_MS);
-    };
-
-    window.addEventListener('scroll', onScroll, { passive: true });
-    return () => {
-      window.removeEventListener('scroll', onScroll);
-    };
-  }, [location.key]);
-
-  // Persist to sessionStorage on pagehide
+  // Save positions on pagehide (React Router's approach)
+  // This is the ONLY place we save positions, ensuring accuracy
   useLayoutEffect(() => {
     const onPageHide = () => {
-      // Save current position one last time
-      const key = location.key;
-      if (key) {
-        savedScrollPositions[key] = window.scrollY;
-      }
-      persistToSessionStorage();
+      // Save current position before the page is hidden
+      const key = getScrollRestorationKey(location);
+      savedScrollPositions[key] = window.scrollY;
+      persistSavedPositions();
+      // Let browser handle scroll restoration on page refresh
+      window.history.scrollRestoration = 'auto';
     };
+
     window.addEventListener('pagehide', onPageHide);
     return () => {
       window.removeEventListener('pagehide', onPageHide);
     };
-  }, [location.key]);
+  }, [location]);
 
   // Handle scroll on navigation
   useLayoutEffect(() => {
-    // Save previous page's scroll position
-    const prevKey = prevKeyRef.current;
-    if (prevKey) {
-      savedScrollPositions[prevKey] = window.scrollY;
+    // Skip if we're in the middle of a restore
+    if (isRestoringRef.current) {
+      isRestoringRef.current = false;
+      return;
     }
-    prevKeyRef.current = location.key;
 
-    const hash = decodeURIComponent(window.location.hash);
+    const prevKey = prevKeyRef.current;
+    const currentKey = getScrollRestorationKey(location);
+    prevKeyRef.current = currentKey;
 
+    // For POP navigation (back/forward), restore saved position
     if (navigationType === 'POP') {
-      // Back/forward: restore saved position
-      const savedY = location.key
-        ? savedScrollPositions[location.key]
-        : undefined;
+      const savedY = savedScrollPositions[currentKey];
+
       if (typeof savedY === 'number') {
-        window.scrollTo(0, savedY);
+        // Use requestAnimationFrame to ensure DOM is ready
+        // This handles cases where content is dynamically loaded
+        requestAnimationFrame(() => {
+          isRestoringRef.current = true;
+          window.scrollTo(0, savedY);
+        });
       }
-    } else if (hash.length > 0) {
-      // New navigation with hash: scroll to anchor (respecting scroll-padding-top)
-      scrollToHashTarget(hash);
+      // If no saved position, let browser handle it naturally
+      return;
+    }
+
+    // For PUSH/REPLACE navigation
+    const hash = decodeURIComponent(window.location.hash);
+
+    if (hash.length > 0) {
+      // Try to scroll to hash target
+      // Use requestAnimationFrame to ensure target element is rendered
+      requestAnimationFrame(() => {
+        scrollToHashTarget(hash);
+      });
     } else {
-      // New navigation without hash: scroll to top
+      // Scroll to top for new navigation
       window.scrollTo(0, 0);
     }
   }, [location, navigationType]);
@@ -167,6 +186,12 @@ function useScrollRestoration() {
 
 /**
  * Scroll restoration component inspired by React Router's ScrollRestoration.
+ *
+ * This component:
+ * 1. Renders an inline script that restores scroll position before React hydration
+ * 2. Sets up scroll position saving on pagehide
+ * 3. Handles scroll restoration on navigation
+ *
  * @see https://reactrouter.com/api/components/ScrollRestoration
  * @private
  * @unstable

From 868fdccd6f6b105d904ae58a911e860058f1ccf2 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:05:19 +0800
Subject: [PATCH 06/11] chore: fixed by antigravity

---
 .../src/theme/logic/ScrollRestoration.tsx     | 49 ++++++++++---------
 1 file changed, 26 insertions(+), 23 deletions(-)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index e03030764b..6e0fa1e4e2 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -2,6 +2,7 @@ import { useLayoutEffect, useRef } from 'react';
 import { useLocation, useNavigationType } from 'react-router-dom';
 
 const STORAGE_KEY = 'rspress-scroll-positions';
+const MAX_SCROLL_ENTRIES = 100;
 
 // Module-level state for scroll positions
 let savedScrollPositions: Record<string, number> = {};
@@ -70,22 +71,24 @@ function loadSavedPositions(): void {
 
 /**
  * Persist scroll positions to sessionStorage.
+ * Prunes oldest entries if exceeding MAX_SCROLL_ENTRIES.
  */
 function persistSavedPositions(): void {
   try {
+    const keys = Object.keys(savedScrollPositions);
+    if (keys.length > MAX_SCROLL_ENTRIES) {
+      // Remove oldest entries (first inserted keys)
+      const excess = keys.length - MAX_SCROLL_ENTRIES;
+      for (let i = 0; i < excess; i++) {
+        delete savedScrollPositions[keys[i]];
+      }
+    }
     sessionStorage.setItem(STORAGE_KEY, JSON.stringify(savedScrollPositions));
   } catch {
     // Ignore errors
   }
 }
 
-/**
- * Generate a random key for history state if missing.
- */
-function generateKey(): string {
-  return Math.random().toString(32).slice(2);
-}
-
 // The inline script that runs before React hydration.
 // It reads the saved scroll position from sessionStorage and restores it immediately,
 // preventing a flash of wrong scroll position.
@@ -114,7 +117,6 @@ function useScrollRestoration() {
   const location = useLocation();
   const navigationType = useNavigationType();
   const prevKeyRef = useRef<string | undefined>(undefined);
-  const isRestoringRef = useRef(false);
 
   // Initialize: load from sessionStorage, take control of scroll restoration
   useLayoutEffect(() => {
@@ -122,14 +124,16 @@ function useScrollRestoration() {
     window.history.scrollRestoration = 'manual';
   }, []);
 
-  // Save positions on pagehide (React Router's approach)
-  // This is the ONLY place we save positions, ensuring accuracy
+  // Save positions on pagehide for tab close / page refresh scenarios.
+  // Reads key from history.state directly so this effect only runs once.
   useLayoutEffect(() => {
     const onPageHide = () => {
-      // Save current position before the page is hidden
-      const key = getScrollRestorationKey(location);
-      savedScrollPositions[key] = window.scrollY;
-      persistSavedPositions();
+      const state = window.history.state;
+      const key = state?.key;
+      if (key) {
+        savedScrollPositions[key] = window.scrollY;
+        persistSavedPositions();
+      }
       // Let browser handle scroll restoration on page refresh
       window.history.scrollRestoration = 'auto';
     };
@@ -138,29 +142,28 @@ function useScrollRestoration() {
     return () => {
       window.removeEventListener('pagehide', onPageHide);
     };
-  }, [location]);
+  }, []);
 
   // Handle scroll on navigation
   useLayoutEffect(() => {
-    // Skip if we're in the middle of a restore
-    if (isRestoringRef.current) {
-      isRestoringRef.current = false;
-      return;
-    }
-
     const prevKey = prevKeyRef.current;
     const currentKey = getScrollRestorationKey(location);
     prevKeyRef.current = currentKey;
 
+    // Save the previous page's scroll position before handling the new page.
+    // This is essential for SPA navigation where pagehide does not fire.
+    if (prevKey) {
+      savedScrollPositions[prevKey] = window.scrollY;
+      persistSavedPositions();
+    }
+
     // For POP navigation (back/forward), restore saved position
     if (navigationType === 'POP') {
       const savedY = savedScrollPositions[currentKey];
 
       if (typeof savedY === 'number') {
         // Use requestAnimationFrame to ensure DOM is ready
-        // This handles cases where content is dynamically loaded
         requestAnimationFrame(() => {
-          isRestoringRef.current = true;
           window.scrollTo(0, savedY);
         });
       }

From 986f6bd8e55bf7fa7f8761e6a93290418f0eb733 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:21:48 +0800
Subject: [PATCH 07/11] chore: fixed by glm-5

---
 .../core/src/theme/logic/ScrollRestoration.tsx   | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index 6e0fa1e4e2..040ed4778c 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -122,6 +122,22 @@ function useScrollRestoration() {
   useLayoutEffect(() => {
     loadSavedPositions();
     window.history.scrollRestoration = 'manual';
+
+    // Handle hashchange for same-page anchor navigation
+    // This is needed because clicking an anchor link doesn't trigger
+    // React Router navigation (no PUSH/REPLACE), but we need to scroll
+    // since scrollRestoration is 'manual'
+    const handleHashChange = () => {
+      const hash = window.location.hash;
+      if (hash.length > 0) {
+        scrollToHashTarget(hash);
+      }
+    };
+
+    window.addEventListener('hashchange', handleHashChange);
+    return () => {
+      window.removeEventListener('hashchange', handleHashChange);
+    };
   }, []);
 
   // Save positions on pagehide for tab close / page refresh scenarios.

From 65453d30164f26b3b51278a92a73b7f1393d5e84 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:29:18 +0800
Subject: [PATCH 08/11] chore: update

---
 packages/core/src/theme/logic/ScrollRestoration.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index 040ed4778c..6176aa3819 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -128,7 +128,7 @@ function useScrollRestoration() {
     // React Router navigation (no PUSH/REPLACE), but we need to scroll
     // since scrollRestoration is 'manual'
     const handleHashChange = () => {
-      const hash = window.location.hash;
+      const hash = decodeURIComponent(window.location.hash);
       if (hash.length > 0) {
         scrollToHashTarget(hash);
       }

From 461234d93a5c0549577a63126ca4c04ceda0956a Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:31:35 +0800
Subject: [PATCH 09/11] chore: update

---
 .../core/src/theme/logic/ScrollRestoration.tsx    | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index 6176aa3819..cb030eff19 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -92,6 +92,7 @@ function persistSavedPositions(): void {
 // The inline script that runs before React hydration.
 // It reads the saved scroll position from sessionStorage and restores it immediately,
 // preventing a flash of wrong scroll position.
+// Also handles hash anchor scrolling since scrollRestoration is 'manual'.
 const inlineScript = `(function(){
   try {
     // Ensure history.state.key exists (React Router behavior)
@@ -102,6 +103,20 @@ const inlineScript = `(function(){
     
     var positions = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
     var y = positions[window.history.state.key];
+    
+    // Check for hash anchor first
+    var hash = window.location.hash;
+    if (hash && hash.length > 1) {
+      window.history.scrollRestoration = 'manual';
+      var target = document.getElementById(hash.slice(1));
+      if (target) {
+        var scrollPaddingTop = parseInt(window.getComputedStyle(document.documentElement).getPropertyValue('scroll-padding-top')) || 0;
+        var offsetTop = target.getBoundingClientRect().top + window.scrollY - scrollPaddingTop;
+        window.scrollTo(0, Math.round(offsetTop));
+        return;
+      }
+    }
+    
     if (typeof y === 'number') {
       window.history.scrollRestoration = 'manual';
       window.scrollTo(0, y);

From 25ac3bbbea111df57274c5659d70917fcba42301 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Thu, 26 Feb 2026 17:38:56 +0800
Subject: [PATCH 10/11] chore: update

---
 packages/core/src/theme/logic/ScrollRestoration.tsx | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index cb030eff19..d957b669f2 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -1,5 +1,5 @@
+import { useLocation, useNavigationType } from '@rspress/core/runtime';
 import { useLayoutEffect, useRef } from 'react';
-import { useLocation, useNavigationType } from 'react-router-dom';
 
 const STORAGE_KEY = 'rspress-scroll-positions';
 const MAX_SCROLL_ENTRIES = 100;
@@ -95,7 +95,6 @@ function persistSavedPositions(): void {
 // Also handles hash anchor scrolling since scrollRestoration is 'manual'.
 const inlineScript = `(function(){
   try {
-    // Ensure history.state.key exists (React Router behavior)
     if (!window.history.state || !window.history.state.key) {
       var key = Math.random().toString(32).slice(2);
       window.history.replaceState({ key: key }, "");
@@ -104,16 +103,14 @@ const inlineScript = `(function(){
     var positions = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
     var y = positions[window.history.state.key];
     
-    // Check for hash anchor first
     var hash = window.location.hash;
     if (hash && hash.length > 1) {
       window.history.scrollRestoration = 'manual';
-      var target = document.getElementById(hash.slice(1));
+      var target = document.getElementById(decodeURIComponent(hash.slice(1)));
       if (target) {
         var scrollPaddingTop = parseInt(window.getComputedStyle(document.documentElement).getPropertyValue('scroll-padding-top')) || 0;
         var offsetTop = target.getBoundingClientRect().top + window.scrollY - scrollPaddingTop;
-        window.scrollTo(0, Math.round(offsetTop));
-        return;
+        y = Math.round(offsetTop);
       }
     }
     

From 5a28af28ff7ba71f33f5fed7579bbbe7cf214ac3 Mon Sep 17 00:00:00 2001
From: SoonIter <sooniter@gmail.com>
Date: Fri, 27 Feb 2026 13:02:02 +0800
Subject: [PATCH 11/11] chore: update

---
 .../src/theme/logic/ScrollRestoration.tsx     | 71 ++++---------------
 1 file changed, 14 insertions(+), 57 deletions(-)

diff --git a/packages/core/src/theme/logic/ScrollRestoration.tsx b/packages/core/src/theme/logic/ScrollRestoration.tsx
index d957b669f2..9707e3c5f8 100644
--- a/packages/core/src/theme/logic/ScrollRestoration.tsx
+++ b/packages/core/src/theme/logic/ScrollRestoration.tsx
@@ -5,7 +5,10 @@ const STORAGE_KEY = 'rspress-scroll-positions';
 const MAX_SCROLL_ENTRIES = 100;
 
 // Module-level state for scroll positions
-let savedScrollPositions: Record<string, number> = {};
+const savedScrollPositions: Record<string, number> =
+  typeof window === 'undefined'
+    ? {}
+    : JSON.parse(sessionStorage.getItem(STORAGE_KEY) || '{}');
 
 /**
  * Parse CSS length value to number (in pixels).
@@ -55,20 +58,6 @@ function getScrollRestorationKey(location: { key: string }): string {
   return location.key;
 }
 
-/**
- * Load scroll positions from sessionStorage.
- */
-function loadSavedPositions(): void {
-  try {
-    const stored = sessionStorage.getItem(STORAGE_KEY);
-    if (stored) {
-      savedScrollPositions = JSON.parse(stored);
-    }
-  } catch {
-    // Ignore errors
-  }
-}
-
 /**
  * Persist scroll positions to sessionStorage.
  * Prunes oldest entries if exceeding MAX_SCROLL_ENTRIES.
@@ -103,17 +92,6 @@ const inlineScript = `(function(){
     var positions = JSON.parse(sessionStorage.getItem('${STORAGE_KEY}') || '{}');
     var y = positions[window.history.state.key];
     
-    var hash = window.location.hash;
-    if (hash && hash.length > 1) {
-      window.history.scrollRestoration = 'manual';
-      var target = document.getElementById(decodeURIComponent(hash.slice(1)));
-      if (target) {
-        var scrollPaddingTop = parseInt(window.getComputedStyle(document.documentElement).getPropertyValue('scroll-padding-top')) || 0;
-        var offsetTop = target.getBoundingClientRect().top + window.scrollY - scrollPaddingTop;
-        y = Math.round(offsetTop);
-      }
-    }
-    
     if (typeof y === 'number') {
       window.history.scrollRestoration = 'manual';
       window.scrollTo(0, y);
@@ -130,28 +108,6 @@ function useScrollRestoration() {
   const navigationType = useNavigationType();
   const prevKeyRef = useRef<string | undefined>(undefined);
 
-  // Initialize: load from sessionStorage, take control of scroll restoration
-  useLayoutEffect(() => {
-    loadSavedPositions();
-    window.history.scrollRestoration = 'manual';
-
-    // Handle hashchange for same-page anchor navigation
-    // This is needed because clicking an anchor link doesn't trigger
-    // React Router navigation (no PUSH/REPLACE), but we need to scroll
-    // since scrollRestoration is 'manual'
-    const handleHashChange = () => {
-      const hash = decodeURIComponent(window.location.hash);
-      if (hash.length > 0) {
-        scrollToHashTarget(hash);
-      }
-    };
-
-    window.addEventListener('hashchange', handleHashChange);
-    return () => {
-      window.removeEventListener('hashchange', handleHashChange);
-    };
-  }, []);
-
   // Save positions on pagehide for tab close / page refresh scenarios.
   // Reads key from history.state directly so this effect only runs once.
   useLayoutEffect(() => {
@@ -187,14 +143,15 @@ function useScrollRestoration() {
 
     // For POP navigation (back/forward), restore saved position
     if (navigationType === 'POP') {
-      const savedY = savedScrollPositions[currentKey];
-
-      if (typeof savedY === 'number') {
-        // Use requestAnimationFrame to ensure DOM is ready
-        requestAnimationFrame(() => {
-          window.scrollTo(0, savedY);
-        });
-      }
+      // console.log(`[ScrollRestoration] POP navigation detected. Restoring scroll position for key: ${currentKey}`);
+      // const savedY = savedScrollPositions[currentKey];
+
+      // if (typeof savedY === 'number') {
+      //   // Use requestAnimationFrame to ensure DOM is ready
+      //   requestAnimationFrame(() => {
+      //     window.scrollTo(0, savedY);
+      //   });
+      // }
       // If no saved position, let browser handle it naturally
       return;
     }
@@ -212,7 +169,7 @@ function useScrollRestoration() {
       // Scroll to top for new navigation
       window.scrollTo(0, 0);
     }
-  }, [location, navigationType]);
+  }, [location.search, location.hash, location.pathname, navigationType]);
 }
 
 /**