fix(app): scroll to top on route change

app/src/components/RootLayout.test.tsx

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render } from '@testing-library/react';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { MemoryRouter, Routes, Route, Link } from 'react-router-dom';
+import userEvent from '@testing-library/user-event';
+import { RootLayout } from './RootLayout';
+
+vi.mock('../hooks', () => ({
+  useAnalytics: () => ({ trackEvent: vi.fn(), trackPageview: vi.fn() }),
+}));
+
+vi.mock('./MastheadRule', () => ({
+  MastheadRule: () => <div data-testid="masthead" />,
+}));
+
+vi.mock('./NavBar', () => ({
+  NavBar: () => <div data-testid="navbar" />,
+}));
+
+vi.mock('./Footer', () => ({
+  Footer: () => <div data-testid="footer" />,
+}));
+
+const theme = createTheme();
+
+function renderAt(initialPath: string) {
+  return render(
+    <ThemeProvider theme={theme}>
+      <MemoryRouter initialEntries={[initialPath]}>
+        <Routes>
+          <Route element={<RootLayout />}>
+            <Route
+              path="/"
+              element={
+                <div>
+                  <Link to="/legal">go-legal</Link>
+                  <Link to="/about#section">go-about-hash</Link>
+                </div>
+              }
+            />
+            <Route path="/legal" element={<div>legal-page</div>} />
+            <Route path="/about" element={<div>about-page</div>} />
+          </Route>
+        </Routes>
+      </MemoryRouter>
+    </ThemeProvider>,
+  );
+}
+
+describe('RootLayout', () => {
+  let scrollSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    scrollSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    scrollSpy.mockRestore();
+  });
+
+  it('scrolls to top when navigating to a new path (PUSH)', async () => {
+    const user = userEvent.setup();
+    renderAt('/');
+    scrollSpy.mockClear();
+
+    await user.click(document.querySelector('a[href="/legal"]') as HTMLElement);
+
+    expect(scrollSpy).toHaveBeenCalledWith(0, 0);
+  });
+
+  it('does not scroll to top when the destination has a hash anchor', async () => {
+    const user = userEvent.setup();
+    renderAt('/');
+    scrollSpy.mockClear();
+
+    await user.click(document.querySelector('a[href="/about#section"]') as HTMLElement);
+
+    expect(scrollSpy).not.toHaveBeenCalledWith(0, 0);
+  });
+});

app/src/components/RootLayout.tsx

@@ -1,4 +1,5 @@
-import { Outlet, useLocation } from 'react-router-dom';
+import { useEffect } from 'react';
+import { Outlet, useLocation, useNavigationType } from 'react-router-dom';
 import Box from '@mui/material/Box';
 import Container from '@mui/material/Container';
 
@@ -22,9 +23,22 @@ const containerSx = {
  */
 export function RootLayout() {
   const { trackEvent } = useAnalytics();
-  const { pathname } = useLocation();
+  const { pathname, hash } = useLocation();
+  const navigationType = useNavigationType();
   const mastheadSticks = pathname !== '/plots';
 
+  // Reset scroll on forward navigation (PUSH/REPLACE). Without this, short
+  // pages like /legal inherit the previous page's scroll position because
+  // PlotsPage sets scrollRestoration='manual'. Skip on POP so browser
+  // back/forward keeps native scroll restoration; skip when a hash anchor
+  // is present so in-page anchors still work. PlotsPage runs its own
+  // saved-scroll restore in a later effect, so it still overrides this.
+  useEffect(() => {
+    if (hash) return;
+    if (navigationType === 'POP') return;
+    window.scrollTo(0, 0);
+  }, [pathname, hash, navigationType]);
+
   return (
     <Box sx={{
       display: 'flex',

app/src/pages/HomePage.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { render, screen } from '../test-utils';
 
 // Mock hooks
@@ -116,4 +116,20 @@ describe('HomePage', () => {
     render(<HomePage />);
     expect(screen.getByTestId('helmet')).toBeInTheDocument();
   });
+
+  describe('scrollRestoration', () => {
+    const original = history.scrollRestoration;
+
+    afterEach(() => {
+      history.scrollRestoration = original;
+    });
+
+    it("sets scrollRestoration to 'manual' on mount and restores 'auto' on unmount", () => {
+      history.scrollRestoration = 'auto';
+      const { unmount } = render(<HomePage />);
+      expect(history.scrollRestoration).toBe('manual');
+      unmount();
+      expect(history.scrollRestoration).toBe('auto');
+    });
+  });
 });

app/src/pages/HomePage.tsx

@@ -28,11 +28,15 @@ export function HomePage() {
   const { specsData, librariesData, stats } = useAppData();
   const { homeStateRef, saveScrollPosition } = useHomeState();
 
-  // Disable browser's automatic scroll restoration
+  // Disable browser's automatic scroll restoration so we can restore from
+  // our persisted state (homeStateRef.scrollY) instead. Restore on unmount
+  // so other routes get native back/forward behavior.
   useEffect(() => {
-    if ('scrollRestoration' in history) {
-      history.scrollRestoration = 'manual';
-    }
+    if (!('scrollRestoration' in history)) return;
+    history.scrollRestoration = 'manual';
+    return () => {
+      history.scrollRestoration = 'auto';
+    };
   }, []);
 
   // Custom hooks

app/src/pages/PlotsPage.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { render, screen } from '../test-utils';
 
 vi.mock('../hooks', () => ({
@@ -68,4 +68,20 @@ describe('PlotsPage', () => {
     render(<PlotsPage />);
     expect(screen.getByTestId('helmet')).toBeInTheDocument();
   });
+
+  describe('scrollRestoration', () => {
+    const original = history.scrollRestoration;
+
+    afterEach(() => {
+      history.scrollRestoration = original;
+    });
+
+    it("sets scrollRestoration to 'manual' on mount and restores 'auto' on unmount", () => {
+      history.scrollRestoration = 'auto';
+      const { unmount } = render(<PlotsPage />);
+      expect(history.scrollRestoration).toBe('manual');
+      unmount();
+      expect(history.scrollRestoration).toBe('auto');
+    });
+  });
 });

app/src/pages/PlotsPage.tsx

@@ -21,11 +21,15 @@ export function PlotsPage() {
   const { specsData, librariesData } = useAppData();
   const { homeStateRef, saveScrollPosition } = useHomeState();
 
-  // Disable browser's automatic scroll restoration
+  // Disable browser's automatic scroll restoration so we can restore from
+  // our persisted state (homeStateRef.scrollY) instead. Restore on unmount
+  // so other routes get native back/forward behavior.
   useEffect(() => {
-    if ('scrollRestoration' in history) {
-      history.scrollRestoration = 'manual';
-    }
+    if (!('scrollRestoration' in history)) return;
+    history.scrollRestoration = 'manual';
+    return () => {
+      history.scrollRestoration = 'auto';
+    };
   }, []);
 
   const { trackPageview, trackEvent } = useAnalytics();