fix(nav): hand scroll restoration back to the browser after arrival

app/components/cinematic/CinematicHome.test.tsx

@@ -1,5 +1,8 @@
 import { act, fireEvent, render, screen } from "@testing-library/react";
-import { useHomeFragmentNavigation } from "./useHomeFragmentNavigation";
+import {
+  resetHomeArrivalState,
+  useHomeFragmentNavigation,
+} from "./useHomeFragmentNavigation";
 
 function HomeNavigation() {
   const onLayoutReady = useHomeFragmentNavigation();
@@ -23,6 +26,7 @@ function HomeNavigation() {
 const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
 
 beforeEach(() => {
+  resetHomeArrivalState();
   window.history.replaceState(null, "", "/");
   HTMLElement.prototype.scrollIntoView = jest.fn();
 });
@@ -53,6 +57,26 @@ describe("home fragment navigation", () => {
     expect(restoredPosition).toBe(0);
   });
 
+  it("leaves a same-document return to the position the browser restores", () => {
+    const scrollTo = jest
+      .spyOn(window, "scrollTo")
+      .mockImplementation(() => {});
+    const firstVisit = render(<HomeNavigation />);
+    fireEvent.click(
+      screen.getByRole("button", { name: "Establish notebook layout" }),
+    );
+    firstVisit.unmount();
+    expect(window.history.scrollRestoration).not.toBe("manual");
+
+    scrollTo.mockClear();
+    render(<HomeNavigation />);
+    fireEvent.click(
+      screen.getByRole("button", { name: "Establish notebook layout" }),
+    );
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(window.history.scrollRestoration).not.toBe("manual");
+  });
+
   it("does not reset the visitor's position after intentional scrolling during startup", () => {
     let position = 0;
     jest

app/components/cinematic/useHomeFragmentNavigation.ts

@@ -16,6 +16,17 @@ function focusFragment(target: HTMLElement) {
   target.focus({ preventScroll: true });
 }
 
+/**
+ * A document owns one outstanding homepage arrival. Later mounts are same-document
+ * history, where the browser restores its own position.
+ */
+let arrivalSettled = false;
+
+/** Tests replay several documents inside one jsdom document. */
+export function resetHomeArrivalState() {
+  arrivalSettled = false;
+}
+
 /** Correct only an outstanding arrival; ordinary links and history keep native scrolling. */
 export function useHomeFragmentNavigation() {
   const ready = useRef(false);
@@ -26,12 +37,11 @@ export function useHomeFragmentNavigation() {
       | PerformanceNavigationTiming
       | undefined;
     // A history restoration owns its saved position, not the URL's old fragment.
-    let pending =
-      navigation?.type === "back_forward" ? "" : window.location.hash;
-    let pendingTop =
-      navigation?.type !== "back_forward" && !window.location.hash;
-    if (navigation?.type !== "back_forward")
-      window.history.scrollRestoration = "manual";
+    const restoration = navigation?.type === "back_forward";
+    const arrival = !restoration && !arrivalSettled;
+    let pending = restoration ? "" : window.location.hash;
+    let pendingTop = arrival && !window.location.hash;
+    if (arrival) window.history.scrollRestoration = "manual";
 
     const resolve = () => {
       if (!ready.current) return;
@@ -69,6 +79,7 @@ export function useHomeFragmentNavigation() {
     const cancelArrival = () => {
       pending = "";
       pendingTop = false;
+      window.history.scrollRestoration = "auto";
     };
     const onKeyDown = (event: KeyboardEvent) => {
       if (
@@ -151,5 +162,7 @@ export function useHomeFragmentNavigation() {
   return useCallback(() => {
     ready.current = true;
     resolveArrival.current?.();
+    arrivalSettled = true;
+    window.history.scrollRestoration = "auto";
   }, []);
 }