From 33817bbe4214a6568dc41bb900db020bddfdab4c Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sat, 21 Nov 2026 02:43:57 +0000 Subject: [PATCH 1/3] Remember scroll position on back/forward and reload BrowserRouter has no scroll handling and the browser's own restoration runs before the page has loaded its data, so it lands short. Track the window scroll per history entry in sessionStorage and restore it on POP, retrying as the page grows until it fits, the user scrolls or 5 s pass. Pushing a new pathname scrolls to the top; query-only pushes (table sort, filter, page) keep the position. Closes #1247 Co-Authored-By: Claude Opus 5.5 --- packages/web_ui/src/components/SiteLayout.tsx | 2 + .../web_ui/src/util/useScrollRestoration.ts | 138 ++++++++++++++++++ test/web_ui/useScrollRestoration.js | 63 ++++++++ 3 files changed, 203 insertions(+) create mode 100644 packages/web_ui/src/util/useScrollRestoration.ts create mode 100644 test/web_ui/useScrollRestoration.js diff --git a/packages/web_ui/src/components/SiteLayout.tsx b/packages/web_ui/src/components/SiteLayout.tsx index ed03e0ad..8bd02e75 100644 --- a/packages/web_ui/src/components/SiteLayout.tsx +++ b/packages/web_ui/src/components/SiteLayout.tsx @@ -11,6 +11,7 @@ import AboutModal from "./AboutModal"; import Link from "./Link"; import { saveJson } from "../util/save_file"; +import useScrollRestoration from "../util/useScrollRestoration"; import { useAccount } from "../model/account"; import { DraggingContext } from "../model/is_dragging"; import webUiPackage from "../../package.json"; @@ -50,6 +51,7 @@ function isActiveDropzone(element: HTMLElement | null): boolean { export default function SiteLayout() { let navigate = useNavigate(); + useScrollRestoration(); let [currentSidebarPath, setCurrentSidebarPath] = useState(null); const screens = Grid.useBreakpoint(); // On phone screens the sidebar becomes an overlay drawer instead of a fixed sider. diff --git a/packages/web_ui/src/util/useScrollRestoration.ts b/packages/web_ui/src/util/useScrollRestoration.ts new file mode 100644 index 00000000..05941397 --- /dev/null +++ b/packages/web_ui/src/util/useScrollRestoration.ts @@ -0,0 +1,138 @@ +import { useEffect, useLayoutEffect, useRef } from "react"; +import { type Location, useLocation, useNavigationType } from "react-router-dom"; + +const storageKey = "scroll_positions"; +const maxEntries = 100; +const restoreTimeoutMs = 5000; + +/** Read saved scroll positions, oldest first. */ +export function loadScrollPositions(storage: Pick): Map { + try { + const stored = JSON.parse(storage.getItem(storageKey) ?? "[]"); + if (Array.isArray(stored)) { + return new Map(stored.filter( + (entry): entry is [string, number] => typeof entry[0] === "string" && typeof entry[1] === "number" + )); + } + } catch { + // Fall through to an empty map on corrupt data. + } + return new Map(); +} + +/** Record a position as the newest entry, dropping the oldest past the limit. */ +export function setScrollPosition(positions: Map, key: string, y: number) { + positions.delete(key); + positions.set(key, y); + for (const oldest of positions.keys()) { + if (positions.size <= maxEntries) { + break; + } + positions.delete(oldest); + } +} + +export function saveScrollPositions(storage: Pick, positions: Map) { + try { + storage.setItem(storageKey, JSON.stringify([...positions])); + } catch { + // Ignore storage errors (e.g. quota exceeded or storage disabled). + } +} + +/** History entries created outside the router all share the key "default". */ +export function scrollKey(location: Pick) { + return location.key === "default" ? `${location.pathname}${location.search}` : location.key; +} + +/** + * Scroll to y, retrying as the page grows while its data loads. Gives up after + * a timeout or when the user scrolls. + */ +function restoreScroll(y: number, onDone: () => void) { + const inputEvents = ["wheel", "touchstart", "keydown", "pointerdown"]; + const observer = new ResizeObserver(attempt); + const timeout = setTimeout(stop, restoreTimeoutMs); + let stopped = false; + + function stop() { + if (stopped) { + return; + } + stopped = true; + observer.disconnect(); + clearTimeout(timeout); + for (const event of inputEvents) { + window.removeEventListener(event, stop, true); + } + onDone(); + } + + function attempt() { + window.scrollTo(0, y); + if (window.scrollY >= y - 1) { + stop(); + } + } + + for (const event of inputEvents) { + window.addEventListener(event, stop, { capture: true, passive: true }); + } + observer.observe(document.body); + attempt(); + return stop; +} + +/** + * Restore the window scroll position on back/forward and page reload, and + * scroll to the top when navigating to another page. + */ +export default function useScrollRestoration() { + const location = useLocation(); + const navigationType = useNavigationType(); + const key = scrollKey(location); + const positions = useRef | null>(null); + const currentKey = useRef(key); + const restoring = useRef(false); + const pathname = useRef(location.pathname); + if (!positions.current) { + positions.current = loadScrollPositions(sessionStorage); + } + + useEffect(() => { + window.history.scrollRestoration = "manual"; + function onScroll() { + if (!restoring.current) { + setScrollPosition(positions.current!, currentKey.current, window.scrollY); + } + } + function persist() { + saveScrollPositions(sessionStorage, positions.current!); + } + window.addEventListener("scroll", onScroll, { passive: true }); + window.addEventListener("pagehide", persist); + return () => { + window.removeEventListener("scroll", onScroll); + window.removeEventListener("pagehide", persist); + persist(); + }; + }, []); + + useLayoutEffect(() => { + currentKey.current = key; + saveScrollPositions(sessionStorage, positions.current!); + const pathChanged = pathname.current !== location.pathname; + pathname.current = location.pathname; + // Table sort, filter and page changes only change the query + if (navigationType === "PUSH" && pathChanged) { + window.scrollTo(0, 0); + return undefined; + } + if (navigationType !== "POP") { + setScrollPosition(positions.current!, key, window.scrollY); + return undefined; + } + restoring.current = true; + return restoreScroll(positions.current!.get(key) ?? 0, () => { restoring.current = false; }); + }, [key]); +} diff --git a/test/web_ui/useScrollRestoration.js b/test/web_ui/useScrollRestoration.js new file mode 100644 index 00000000..9bc748e4 --- /dev/null +++ b/test/web_ui/useScrollRestoration.js @@ -0,0 +1,63 @@ +import assert from "node:assert/strict"; + +import { + loadScrollPositions, saveScrollPositions, scrollKey, setScrollPosition, +} from "../../packages/web_ui/src/util/useScrollRestoration.ts"; + +class MemoryStorage { + items = new Map(); + getItem(key) { return this.items.get(key) ?? null; } + setItem(key, value) { this.items.set(key, String(value)); } +} + +describe("web_ui/util/useScrollRestoration", function() { + describe("loadScrollPositions()", function() { + it("should round trip through saveScrollPositions", function() { + const storage = new MemoryStorage(); + saveScrollPositions(storage, new Map([["a", 10], ["b", 20.5]])); + assert.deepEqual([...loadScrollPositions(storage)], [["a", 10], ["b", 20.5]]); + }); + it("should return an empty map when nothing is stored", function() { + assert.equal(loadScrollPositions(new MemoryStorage()).size, 0); + }); + it("should ignore corrupt data", function() { + const storage = new MemoryStorage(); + storage.setItem("scroll_positions", "{not json"); + assert.equal(loadScrollPositions(storage).size, 0); + storage.setItem("scroll_positions", JSON.stringify({ a: 1 })); + assert.equal(loadScrollPositions(storage).size, 0); + storage.setItem("scroll_positions", JSON.stringify([["a", 1], ["b", "x"], [2, 3]])); + assert.deepEqual([...loadScrollPositions(storage)], [["a", 1]]); + }); + }); + describe("saveScrollPositions()", function() { + it("should ignore storage errors", function() { + saveScrollPositions({ setItem() { throw new Error("QuotaExceededError"); } }, new Map([["a", 1]])); + }); + }); + describe("setScrollPosition()", function() { + it("should move an updated key to the newest position", function() { + const positions = new Map([["a", 1], ["b", 2]]); + setScrollPosition(positions, "a", 3); + assert.deepEqual([...positions], [["b", 2], ["a", 3]]); + }); + it("should drop the oldest entries past 100", function() { + const positions = new Map(); + for (let i = 0; i < 105; i++) { + setScrollPosition(positions, `k${i}`, i); + } + assert.equal(positions.size, 100); + assert.equal(positions.has("k4"), false); + assert.equal(positions.get("k5"), 5); + assert.equal(positions.get("k104"), 104); + }); + }); + describe("scrollKey()", function() { + it("should use the location key", function() { + assert.equal(scrollKey({ key: "abc123", pathname: "/users", search: "" }), "abc123"); + }); + it("should fall back to the path for entries created outside the router", function() { + assert.equal(scrollKey({ key: "default", pathname: "/users", search: "?q=a" }), "/users?q=a"); + }); + }); +}); From 628e59bf2cbb38660456a1cc33771ebb6f9af634 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sat, 21 Nov 2026 02:50:12 +0000 Subject: [PATCH 2/3] Move scroll restoration logic out of the hook for testing The effects now call a ScrollRestorer class and restoreScroll is exported, so the tests can drive both against a fake window, sessionStorage and ResizeObserver. The hook is three lines that wire them to the router. Co-Authored-By: Claude Opus 5.5 --- .../web_ui/src/util/useScrollRestoration.ts | 103 +++++----- test/web_ui/useScrollRestoration.js | 186 +++++++++++++++++- 2 files changed, 241 insertions(+), 48 deletions(-) diff --git a/packages/web_ui/src/util/useScrollRestoration.ts b/packages/web_ui/src/util/useScrollRestoration.ts index 05941397..e13e63d7 100644 --- a/packages/web_ui/src/util/useScrollRestoration.ts +++ b/packages/web_ui/src/util/useScrollRestoration.ts @@ -1,5 +1,5 @@ -import { useEffect, useLayoutEffect, useRef } from "react"; -import { type Location, useLocation, useNavigationType } from "react-router-dom"; +import { useEffect, useLayoutEffect, useState } from "react"; +import { type Location, type NavigationType, useLocation, useNavigationType } from "react-router-dom"; const storageKey = "scroll_positions"; const maxEntries = 100; @@ -49,7 +49,7 @@ export function scrollKey(location: Pick void) { +export function restoreScroll(y: number, onDone: () => void) { const inputEvents = ["wheel", "touchstart", "keydown", "pointerdown"]; const observer = new ResizeObserver(attempt); const timeout = setTimeout(stop, restoreTimeoutMs); @@ -83,6 +83,56 @@ function restoreScroll(y: number, onDone: () => void) { return stop; } +export class ScrollRestorer { + positions = loadScrollPositions(sessionStorage); + restoring = false; + + key: string; + pathname: string; + + constructor(key: string, pathname: string) { + this.key = key; + this.pathname = pathname; + } + + /** Start recording scroll positions, returns a function that stops it. */ + attach() { + window.history.scrollRestoration = "manual"; + const onScroll = () => { + if (!this.restoring) { + setScrollPosition(this.positions, this.key, window.scrollY); + } + }; + const persist = () => saveScrollPositions(sessionStorage, this.positions); + window.addEventListener("scroll", onScroll, { passive: true }); + window.addEventListener("pagehide", persist); + return () => { + window.removeEventListener("scroll", onScroll); + window.removeEventListener("pagehide", persist); + persist(); + }; + } + + /** Handle a location change, returns a function that cancels a pending restore. */ + navigate(key: string, pathname: string, navigationType: NavigationType) { + this.key = key; + saveScrollPositions(sessionStorage, this.positions); + const pathChanged = this.pathname !== pathname; + this.pathname = pathname; + // Table sort, filter and page changes only change the query + if (navigationType === "PUSH" && pathChanged) { + window.scrollTo(0, 0); + return undefined; + } + if (navigationType !== "POP") { + setScrollPosition(this.positions, key, window.scrollY); + return undefined; + } + this.restoring = true; + return restoreScroll(this.positions.get(key) ?? 0, () => { this.restoring = false; }); + } +} + /** * Restore the window scroll position on back/forward and page reload, and * scroll to the top when navigating to another page. @@ -91,48 +141,7 @@ export default function useScrollRestoration() { const location = useLocation(); const navigationType = useNavigationType(); const key = scrollKey(location); - const positions = useRef | null>(null); - const currentKey = useRef(key); - const restoring = useRef(false); - const pathname = useRef(location.pathname); - if (!positions.current) { - positions.current = loadScrollPositions(sessionStorage); - } - - useEffect(() => { - window.history.scrollRestoration = "manual"; - function onScroll() { - if (!restoring.current) { - setScrollPosition(positions.current!, currentKey.current, window.scrollY); - } - } - function persist() { - saveScrollPositions(sessionStorage, positions.current!); - } - window.addEventListener("scroll", onScroll, { passive: true }); - window.addEventListener("pagehide", persist); - return () => { - window.removeEventListener("scroll", onScroll); - window.removeEventListener("pagehide", persist); - persist(); - }; - }, []); - - useLayoutEffect(() => { - currentKey.current = key; - saveScrollPositions(sessionStorage, positions.current!); - const pathChanged = pathname.current !== location.pathname; - pathname.current = location.pathname; - // Table sort, filter and page changes only change the query - if (navigationType === "PUSH" && pathChanged) { - window.scrollTo(0, 0); - return undefined; - } - if (navigationType !== "POP") { - setScrollPosition(positions.current!, key, window.scrollY); - return undefined; - } - restoring.current = true; - return restoreScroll(positions.current!.get(key) ?? 0, () => { restoring.current = false; }); - }, [key]); + const [restorer] = useState(() => new ScrollRestorer(key, location.pathname)); + useEffect(() => restorer.attach(), []); + useLayoutEffect(() => restorer.navigate(key, location.pathname, navigationType), [key]); } diff --git a/test/web_ui/useScrollRestoration.js b/test/web_ui/useScrollRestoration.js index 9bc748e4..989b4fce 100644 --- a/test/web_ui/useScrollRestoration.js +++ b/test/web_ui/useScrollRestoration.js @@ -1,7 +1,7 @@ import assert from "node:assert/strict"; import { - loadScrollPositions, saveScrollPositions, scrollKey, setScrollPosition, + ScrollRestorer, loadScrollPositions, restoreScroll, saveScrollPositions, scrollKey, setScrollPosition, } from "../../packages/web_ui/src/util/useScrollRestoration.ts"; class MemoryStorage { @@ -10,6 +10,68 @@ class MemoryStorage { setItem(key, value) { this.items.set(key, String(value)); } } +class FakeWindow { + scrollY = 0; + maxScroll = 0; + listeners = new Map(); + history = { scrollRestoration: "auto" }; + scrollTo(_x, y) { + this.scrollY = Math.max(0, Math.min(y, this.maxScroll)); + this.emit("scroll"); + } + + addEventListener(type, listener) { + if (!this.listeners.has(type)) { + this.listeners.set(type, new Set()); + } + this.listeners.get(type).add(listener); + } + + removeEventListener(type, listener) { + this.listeners.get(type)?.delete(listener); + } + + emit(type) { + for (const listener of [...this.listeners.get(type) ?? []]) { + listener(); + } + } + + count(type) { + return this.listeners.get(type)?.size ?? 0; + } +} + +class FakeResizeObserver { + static observers = new Set(); + constructor(callback) { this.callback = callback; } + observe() { FakeResizeObserver.observers.add(this); } + disconnect() { FakeResizeObserver.observers.delete(this); } +} + +function resize(maxScroll) { + window.maxScroll = maxScroll; + for (const observer of [...FakeResizeObserver.observers]) { + observer.callback(); + } +} + +function withDom() { + beforeEach(function() { + FakeResizeObserver.observers.clear(); + globalThis.window = new FakeWindow(); + globalThis.document = { body: {} }; + globalThis.sessionStorage = new MemoryStorage(); + globalThis.ResizeObserver = FakeResizeObserver; + }); + afterEach(function() { + delete globalThis.window; + delete globalThis.document; + delete globalThis.sessionStorage; + delete globalThis.ResizeObserver; + }); +} + describe("web_ui/util/useScrollRestoration", function() { describe("loadScrollPositions()", function() { it("should round trip through saveScrollPositions", function() { @@ -60,4 +122,126 @@ describe("web_ui/util/useScrollRestoration", function() { assert.equal(scrollKey({ key: "default", pathname: "/users", search: "?q=a" }), "/users?q=a"); }); }); + describe("restoreScroll()", function() { + withDom(); + + it("should scroll immediately when the page is tall enough", function() { + window.maxScroll = 2000; + let done = 0; + restoreScroll(1500, () => { done += 1; }); + assert.equal(window.scrollY, 1500); + assert.equal(done, 1); + assert.equal(FakeResizeObserver.observers.size, 0); + assert.equal(window.count("wheel"), 0); + }); + it("should retry as the page grows", function() { + let done = 0; + restoreScroll(1500, () => { done += 1; }); + assert.equal(window.scrollY, 0); + resize(800); + assert.equal(window.scrollY, 800); + assert.equal(done, 0); + resize(3000); + assert.equal(window.scrollY, 1500); + assert.equal(done, 1); + }); + it("should give up when the user scrolls", function() { + let done = 0; + restoreScroll(1500, () => { done += 1; }); + window.emit("wheel"); + assert.equal(done, 1); + resize(3000); + assert.equal(window.scrollY, 0); + }); + it("should give up after the timeout", function() { + const realSetTimeout = globalThis.setTimeout; + let fire; + globalThis.setTimeout = (callback, ms) => { + assert.equal(ms, 5000); + fire = callback; + return 0; + }; + let done = 0; + try { + restoreScroll(1500, () => { done += 1; }); + } finally { + globalThis.setTimeout = realSetTimeout; + } + fire(); + assert.equal(done, 1); + resize(3000); + assert.equal(window.scrollY, 0); + }); + it("should stop only once when cancelled", function() { + let done = 0; + const stop = restoreScroll(1500, () => { done += 1; }); + stop(); + stop(); + assert.equal(done, 1); + }); + }); + describe("class ScrollRestorer", function() { + withDom(); + + it("should record scroll positions per key and persist them", function() { + const restorer = new ScrollRestorer("a", "/users"); + const detach = restorer.attach(); + assert.equal(window.history.scrollRestoration, "manual"); + window.maxScroll = 2000; + window.scrollTo(0, 700); + window.emit("pagehide"); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 700]]); + window.scrollTo(0, 900); + detach(); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 900]]); + assert.equal(window.count("scroll"), 0); + assert.equal(window.count("pagehide"), 0); + }); + it("should scroll to the top when pushing another path", function() { + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 1500); + restorer.navigate("b", "/users/x/view", "PUSH"); + assert.equal(window.scrollY, 0); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 1500]]); + }); + it("should keep the position when only the query changes", function() { + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 1500); + restorer.navigate("b", "/users", "PUSH"); + assert.equal(window.scrollY, 1500); + assert.equal(restorer.positions.get("b"), 1500); + restorer.navigate("c", "/users", "REPLACE"); + assert.equal(restorer.positions.get("c"), 1500); + }); + it("should restore the saved position on pop", function() { + saveScrollPositions(sessionStorage, new Map([["a", 1500], ["b", 0]])); + const restorer = new ScrollRestorer("b", "/users/x/view"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 400); + assert.equal(restorer.positions.get("b"), 400); + restorer.navigate("a", "/users", "POP"); + assert.equal(window.scrollY, 1500); + restorer.navigate("b", "/users/x/view", "POP"); + assert.equal(window.scrollY, 400); + restorer.navigate("unknown", "/hosts", "POP"); + assert.equal(window.scrollY, 0); + }); + it("should not record positions while restoring", function() { + saveScrollPositions(sessionStorage, new Map([["a", 1500]])); + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + const cancel = restorer.navigate("a", "/users", "POP"); + resize(600); + assert.equal(window.scrollY, 600); + assert.equal(restorer.positions.get("a"), 1500); + cancel(); + window.scrollTo(0, 300); + assert.equal(restorer.positions.get("a"), 300); + }); + }); }); From e1ffb848b19b975456cbde505fd64d1ed27d2df3 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sat, 21 Nov 2026 02:54:18 +0000 Subject: [PATCH 3/3] Define fake DOM globals as non-enumerable in tests mocha --check-leaks flagged window, document and ResizeObserver set by the scroll restoration tests. Define them with defineProperty and restore the original descriptors afterwards. Co-Authored-By: Claude Opus 5.5 --- test/web_ui/useScrollRestoration.js | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/test/web_ui/useScrollRestoration.js b/test/web_ui/useScrollRestoration.js index 989b4fce..dec3ad03 100644 --- a/test/web_ui/useScrollRestoration.js +++ b/test/web_ui/useScrollRestoration.js @@ -56,19 +56,32 @@ function resize(maxScroll) { } } +// Non-enumerable so mocha --check-leaks ignores them function withDom() { + const names = ["window", "document", "sessionStorage", "ResizeObserver"]; + const saved = new Map(); beforeEach(function() { FakeResizeObserver.observers.clear(); - globalThis.window = new FakeWindow(); - globalThis.document = { body: {} }; - globalThis.sessionStorage = new MemoryStorage(); - globalThis.ResizeObserver = FakeResizeObserver; + const fakes = { + window: new FakeWindow(), + document: { body: {} }, + sessionStorage: new MemoryStorage(), + ResizeObserver: FakeResizeObserver, + }; + for (const name of names) { + saved.set(name, Object.getOwnPropertyDescriptor(globalThis, name)); + Object.defineProperty(globalThis, name, { value: fakes[name], configurable: true, writable: true }); + } }); afterEach(function() { - delete globalThis.window; - delete globalThis.document; - delete globalThis.sessionStorage; - delete globalThis.ResizeObserver; + for (const name of names) { + const descriptor = saved.get(name); + if (descriptor) { + Object.defineProperty(globalThis, name, descriptor); + } else { + delete globalThis[name]; + } + } }); }