From 1aedb46eec947c39e52e52c83ef35397ecba5b8f Mon Sep 17 00:00:00 2001
From: FedericoBiccheddu <service+git@f15u.dev>
Date: Tue, 18 Aug 2026 17:04:02 +0200
Subject: [PATCH] ui: keep memory of the current active page in the sidebar

---
 .../ui/sidebar/SidebarScrollMemory.astro      | 76 +++++++++++++++++++
 apps/web/src/layouts/DocShell.astro           |  7 +-
 .../[version]/api/[package]/[...module].astro | 28 +------
 3 files changed, 82 insertions(+), 29 deletions(-)
 create mode 100644 apps/web/src/components/ui/sidebar/SidebarScrollMemory.astro

diff --git a/apps/web/src/components/ui/sidebar/SidebarScrollMemory.astro b/apps/web/src/components/ui/sidebar/SidebarScrollMemory.astro
new file mode 100644
index 000000000..fa0132f3f
--- /dev/null
+++ b/apps/web/src/components/ui/sidebar/SidebarScrollMemory.astro
@@ -0,0 +1,76 @@
+---
+/**
+ * Remembers the documentation sidebar rail's scroll position across full-page
+ * navigations and reveals the active entry on a cold load — so following a link
+ * never dumps the reader back at the top of a long tree.
+ *
+ * Docs and the API Reference share one scrolling rail (owned by `DocShell`) but
+ * render different trees, so each variant passes its own `storageKey` to keep
+ * their saved offsets apart. It targets the rail via `data-doc-sidebar-rail`,
+ * set by `DocShell`.
+ *
+ * The script is intentionally `is:inline`: it must set `scrollTop` before the
+ * first paint to avoid a visible jump, which a bundled (deferred) module script
+ * cannot guarantee. `define:vars` injects `storageKey` as a leading `const`.
+ */
+interface Props {
+  readonly storageKey: string
+}
+
+const { storageKey } = Astro.props
+---
+
+<script is:inline define:vars={{ storageKey }}>
+  ;(() => {
+    const rail = document.querySelector("[data-doc-sidebar-rail]")
+    if (rail === null) {
+      return
+    }
+
+    const persist = () => {
+      sessionStorage.setItem(storageKey, String(rail.scrollTop))
+    }
+
+    // Restore the offset saved on the previous page of this session.
+    const saved = sessionStorage.getItem(storageKey)
+    if (saved !== null) {
+      rail.scrollTop = Number.parseInt(saved, 10)
+    }
+
+    // Match on href so the version switcher's own aria-current="page" link is
+    // ignored and we target the actual current-page entry.
+    const active = rail.querySelector('a[aria-current="page"][href="' + location.pathname + '"]')
+    if (active !== null) {
+      const railBox = rail.getBoundingClientRect()
+      const itemBox = active.getBoundingClientRect()
+      const offScreen = itemBox.top < railBox.top || itemBox.bottom > railBox.bottom
+
+      // Center the active entry when nothing was restored or the restore left it
+      // out of view: a fresh visit, a version switch, or a stale saved offset
+      // from a differently shaped tree.
+      if (saved === null || offScreen) {
+        const delta = itemBox.top - railBox.top - rail.clientHeight / 2 + active.clientHeight / 2
+        rail.scrollTop += delta
+      }
+    }
+
+    // Save on scroll, throttled to one write per animation frame.
+    let frame = 0
+    rail.addEventListener(
+      "scroll",
+      () => {
+        if (frame !== 0) {
+          return
+        }
+        frame = requestAnimationFrame(() => {
+          frame = 0
+          persist()
+        })
+      },
+      { passive: true },
+    )
+
+    // pagehide covers link navigation and bfcache unload alike.
+    window.addEventListener("pagehide", persist)
+  })()
+</script>
diff --git a/apps/web/src/layouts/DocShell.astro b/apps/web/src/layouts/DocShell.astro
index 40a61e00c..ee39f5adf 100644
--- a/apps/web/src/layouts/DocShell.astro
+++ b/apps/web/src/layouts/DocShell.astro
@@ -1,6 +1,7 @@
 ---
 import Footer from "@/components/Footer.astro"
 import Navigation from "@/components/navigation/Navigation.astro"
+import SidebarScrollMemory from "@/components/ui/sidebar/SidebarScrollMemory.astro"
 import BaseLayout from "@/layouts/BaseLayout.astro"
 import { PAGE_TITLE_ID } from "@/lib/constants/skip-link"
 import type { NavigationActiveSlug } from "@/lib/navigation"
@@ -48,7 +49,7 @@ const railClass = "sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-6 p
       {
         hasSidebar && (
           <aside class="hidden border-r border-border lg:block">
-            <div data-doc-rail class={railClass}>
+            <div data-doc-sidebar-rail class={railClass}>
               <slot name="sidebar" />
             </div>
           </aside>
@@ -62,7 +63,7 @@ const railClass = "sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-6 p
       {
         hasToc && (
           <aside class="hidden border-l border-border xl:block">
-            <div data-doc-rail class={railClass}>
+            <div class={railClass}>
               <slot name="toc" />
             </div>
           </aside>
@@ -72,4 +73,6 @@ const railClass = "sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-6 p
 
     <Footer />
   </div>
+
+  {hasSidebar && <SidebarScrollMemory storageKey={`docShellSidebarScroll:${activeSlug}`} />}
 </BaseLayout>
diff --git a/apps/web/src/pages/docs/[version]/api/[package]/[...module].astro b/apps/web/src/pages/docs/[version]/api/[package]/[...module].astro
index b788fa300..5347cbb14 100644
--- a/apps/web/src/pages/docs/[version]/api/[package]/[...module].astro
+++ b/apps/web/src/pages/docs/[version]/api/[package]/[...module].astro
@@ -100,7 +100,6 @@ const sidebarSections = sections.map((section) => ({
           href: moduleHref(candidate.data.modulePath),
           label: sidebarModuleName(candidate.data.modulePath, group),
           active,
-          data: { "data-current-module": active ? "" : undefined },
         }
       }),
   })),
@@ -178,7 +177,7 @@ const tocItems = apiModule.groups.map((group) => ({
     modules={mobileModules}
   />
 
-  <nav slot="sidebar" aria-label="API reference navigation" data-api-sidebar data-module-sidebar>
+  <nav slot="sidebar" aria-label="API reference navigation" data-api-sidebar>
     {
       showVersionSwitch && (
         <VersionSwitch versions={sidebarVersions} aria-label="API reference version" />
@@ -282,28 +281,3 @@ const tocItems = apiModule.groups.map((group) => ({
 
   {tocItems.length > 0 && <TableOfContents slot="toc" items={tocItems} />}
 </DocShell>
-
-<script>
-  const moduleSidebar = document.querySelector<HTMLElement>("[data-module-sidebar]")
-  const currentModuleLink = moduleSidebar?.querySelector<HTMLElement>("[data-current-module]")
-
-  if (moduleSidebar !== null && currentModuleLink !== undefined && currentModuleLink !== null) {
-    const details = currentModuleLink.closest("details")
-    if (details instanceof HTMLDetailsElement) details.open = true
-
-    // DocShell owns the scrolling rail; use it rather than the navigation
-    // element so the active module is centered after the shared layout change.
-    const sidebarScroller = moduleSidebar.closest<HTMLElement>("[data-doc-rail]") ?? moduleSidebar
-
-    requestAnimationFrame(() => {
-      const sidebarBounds = sidebarScroller.getBoundingClientRect()
-      const linkBounds = currentModuleLink.getBoundingClientRect()
-      const isVisible =
-        linkBounds.top >= sidebarBounds.top && linkBounds.bottom <= sidebarBounds.bottom
-      if (isVisible) return
-
-      sidebarScroller.scrollTop +=
-        linkBounds.top - sidebarBounds.top - (sidebarScroller.clientHeight - linkBounds.height) / 2
-    })
-  }
-</script>