Merge branch 'main' into claude/tender-allen-f9l6hh

A cross-page anchor link navigated to the right page but stayed at the top.
GitBook's `scrollToHash` scrolled once, but a soft navigation delivers the
destination asynchronously — content keeps mounting and reflowing for a few
hundred ms after the URL changes — so the single scroll landed before the
target reached its final position, and #4089 routed cross-section navigations
through it. It also scrolled to the top on a transiently-empty hash context.

- scrollToHash re-scrolls to the target on each DOM change until the DOM goes
  quiet, mirroring the fragment scrolling the browser does for free during a
  full page load. It bails if the visitor scrolls, so we never fight them.
- useScrollPage decides the hash from the context value for same-page anchors
  (authoritative, set on click) and from `window.location.hash` for cross-page
  navigations (where the context hash is transiently empty during the remount).

Next keeps handling the baseline scroll (top on plain/query navigations, the
top fallback for missing anchors); GitBook only re-asserts the hash scroll it
would otherwise land too early on.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.changeset/scroll-to-anchor-soft-nav.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix anchor links (e.g. `/page#heading`) not scrolling to the target heading during client-side navigation between pages.

packages/gitbook/src/components/hooks/useScrollPage.ts

@@ -47,11 +47,20 @@ function useScrollPage() {
             return;
         }
 
-        if (hash) {
-            scrollToHash(hash);
+        // For a same-page anchor the context `hash` is authoritative (set on click, before Next
+        // commits the URL). For a cross-page navigation the context hash is transiently empty while
+        // the section remounts, so read the committed URL instead.
+        const samePage = previous !== undefined && previous.pathname === pathname;
+        const targetHash = samePage ? hash : window.location.hash.slice(1);
+
+        if (targetHash) {
+            scrollToHash(targetHash);
             return;
         }
 
+        // No hash: cancel any in-flight scroll-to-hash from a previous navigation so it can't fight
+        // this one. Next handles the actual scroll-to-top of the new page.
+        cancelScrollToHash?.();
         window.scrollTo(0, 0);
     }, [hash, pathname, previous]);
 }
@@ -77,17 +86,45 @@ export function useScrollToHash() {
     }, [hash]);
 }
 
+/** Cancels an in-flight {@link scrollToHash} run, if any. */
+let cancelScrollToHash: (() => void) | null = null;
+
+/** Treat a navigation as settled — and stop re-asserting the scroll — once the DOM is quiet this long. */
+const SCROLL_TO_HASH_SETTLE_MS = 400;
+
 /**
- * Scroll to a hash, if scroll didn't work, return false.
+ * Scroll to the element matching a hash after a client-side navigation.
+ *
+ * A soft navigation delivers the destination asynchronously: its content keeps mounting and reflowing
+ * for a few hundred ms after the URL changes, so a single scroll lands before the target reaches its
+ * final position. Re-scroll on every DOM change until it goes quiet — mirroring the fragment scrolling
+ * the browser does for free during a full page load. Bail if the visitor scrolls, so we never fight
+ * them. (`instant` so re-scrolling to an already-reached position is a no-op.)
  */
 function scrollToHash(hash: string) {
-    const element = document.getElementById(hash);
-    if (element) {
-        element.scrollIntoView({
-            block: 'start',
-            behavior: 'smooth',
-        });
-        return true;
-    }
-    return false;
+    cancelScrollToHash?.();
+
+    let settleTimer = 0;
+    const stop = () => {
+        observer.disconnect();
+        window.clearTimeout(settleTimer);
+        window.removeEventListener('wheel', stop);
+        window.removeEventListener('touchmove', stop);
+        cancelScrollToHash = null;
+    };
+
+    const reassert = () => {
+        document.getElementById(hash)?.scrollIntoView({ block: 'start', behavior: 'instant' });
+        window.clearTimeout(settleTimer);
+        settleTimer = window.setTimeout(stop, SCROLL_TO_HASH_SETTLE_MS);
+    };
+
+    // Our own `scrollIntoView` dispatches `scroll`, not `wheel`/`touchmove`, so it can't self-cancel.
+    const observer = new MutationObserver(reassert);
+    observer.observe(document.body, { childList: true, subtree: true });
+    window.addEventListener('wheel', stop, { passive: true });
+    window.addEventListener('touchmove', stop, { passive: true });
+
+    reassert();
+    cancelScrollToHash = stop;
 }