Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(frontend): restore paginated dashboard scroll positions (#20936)

boojack5c4693a4190c
diff --git a/docs/superpowers/plans/2026-07-20-dashboard-scroll-restoration.md b/docs/superpowers/plans/2026-07-20-dashboard-scroll-restoration.md
new file mode 100644
index 0000000000..f84dfa4a45
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-20-dashboard-scroll-restoration.md
@@ -0,0 +1,1834 @@
+# Dashboard Scroll Restoration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make browser Back/Forward restore paginated dashboard lists immediately and accurately, with Issues and Plans as required consumers, including when a header banner changes the available viewport height, without moving dashboard scrolling to `window`.
+
+**Architecture:** Keep the existing app-shell model: `DashboardFrameShell` owns the full viewport, the banner and dashboard header remain outside route scrolling, and `#bb-layout-main` remains the only route-level vertical scroll owner. The restoration engine and `usePagedData` cache are resource-agnostic: each paginated page supplies only a stable view key and each row supplies only a stable resource name. On browser-history POP, hydrate the matching bounded page snapshot, restore the saved coordinate, then correct it against the semantic row anchor; PUSH/REPLACE fetch normally and expired/missing snapshots retain `useScrollRestorationLoadMore` as the cold-cache fallback.
+
+**Tech Stack:** React, TypeScript, React Router data router, Vitest/jsdom, Playwright, Tailwind CSS v4.
+
+## Global Constraints
+
+- Dashboard only. SQL Editor is explicitly out of scope.
+- Work directly on `main` and leave every change uncommitted and unstaged.
+- No backend, proto, schema, API, or dependency changes.
+- Do not replace React Router or add TanStack Router/Query solely for this fix.
+- Do not migrate dashboard scrolling to `window`.
+- Do not virtualize the issue list in this change. The cache and anchor contracts should remain compatible with later virtualization.
+- Keep `DashboardFrameShell.tsx` and `DashboardBodyShell.tsx` structurally unchanged; their current banner/header/main separation is the desired architecture.
+- The cache and restoration lifecycle must not contain Issue- or Plan-specific logic. Project Issues, My Issues, and Project Plans are required consumers; Databases, Instances, Projects, and other paginated pages can opt in later by supplying the same generic view-key and row-anchor contract.
+- The page cache is a tab-local history snapshot, not a source of truth. Only POP may hydrate it; PUSH/REPLACE and explicit `refresh()` fetch normally.
+- Cache entries expire five minutes after the successful fetch/mutation that wrote them. Reads and hydrations may update LRU order but must not extend this absolute lifetime or write the same snapshot back.
+
+---
+
+## Root cause and target behavior
+
+PR #20920 introduced history-entry-keyed restoration, but the current `useLayoutEffect` snapshots the previous history key after the destination route has committed. When the destination resets `#bb-layout-main` to `0`, that late snapshot overwrites the correct outgoing value already captured by the router subscription. The failure is most visible when the list and detail routes have different layout/scroll behavior.
+
+The target behavior follows the modern app-shell pattern observed in Linear:
+
+1. `window.scrollY` stays `0`; the shell owns viewport sizing.
+2. The banner and dashboard header consume natural height above the route scroller.
+3. `#bb-layout-main` is the one dashboard route-level vertical scroller.
+4. Browser history stores the scroll state for each history entry, not just each pathname.
+5. A warm Back/Forward POP restores previously loaded pages synchronously, then restores the scroll position; PUSH/REPLACE fetches normally.
+6. A semantic resource-row anchor corrects coordinate drift caused by variable-height content.
+7. A cold Back can still grow paged content until the saved coordinate is reachable.
+
+## File map
+
+**Create:**
+
+- `frontend/src/react/hooks/pagedDataCache.ts` — bounded tab-memory cache for complete paged-list snapshots with absolute expiry.
+- `frontend/src/react/hooks/pagedDataCache.test.ts` — cloning, non-sliding expiry, and LRU eviction coverage.
+- `frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts` — browser Back regression coverage with and without the workspace banner.
+
+**Modify:**
+
+- `frontend/src/react/router/NavigationScrollRestoration.tsx` — remove the late outgoing snapshot; capture and apply semantic anchors.
+- `frontend/src/react/router/NavigationScrollRestoration.test.tsx` — reproduce the timing regression and variable-height anchor drift.
+- `frontend/src/react/hooks/usePagedData.tsx` — add explicit history-only synchronous hydration while preserving PUSH/REPLACE fetch and Load More behavior.
+- `frontend/src/react/hooks/usePagedData.test.tsx` — verify POP paints all loaded pages immediately, resumes with the cached token, and PUSH bypasses the snapshot.
+- `frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx` — provide a filter/order-aware project issue cache key.
+- `frontend/src/react/pages/workspace/MyIssuesPage.tsx` — provide a filter/order-aware workspace issue cache key.
+- `frontend/src/react/components/IssueTable.tsx` — expose each issue row as a stable scroll-restoration anchor and E2E seam.
+- `frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx` — make Plan filters URL-backed, provide the Plans view key/POP token, and expose Plan rows as stable anchors.
+- `frontend/src/react/pages/project/ProjectPlanDashboardPage.test.tsx` — verify the Plans page consumes the same generic pagination-restoration contract as Issues.
+- `frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx` — make the dashboard main pane, not the page host, own vertical scrolling.
+- `frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx` — lock the single-scroll-owner and sticky-header behavior.
+
+---
+
+## Task 1: Reproduce and fix the outgoing-snapshot timing regression
+
+**Files:**
+
+- Modify: `frontend/src/react/router/NavigationScrollRestoration.test.tsx`
+- Modify: `frontend/src/react/router/NavigationScrollRestoration.tsx`
+
+**Interfaces:**
+
+- Consumes: `subscribeRoute(onChange: () => void)` as the synchronous pre-commit router seam.
+- Produces: corrected history-entry snapshots; no new exported API.
+
+- [ ] **Step 1: Add a destination-layout regression helper**
+
+Change the React import in `NavigationScrollRestoration.test.tsx` to include `useLayoutEffect`:
+
+```tsx
+import { act, useLayoutEffect, useState } from "react";
+```
+
+Add this helper below `recordScroll`. It deliberately changes the shared main target during the destination commit, matching the real list-to-detail transition:
+
+```tsx
+function RouteScrollMetrics({
+ scrollHeight,
+ resetScrollTop = false,
+}: {
+ scrollHeight: number;
+ resetScrollTop?: boolean;
+}) {
+ useLayoutEffect(() => {
+ const main = document.querySelector<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ if (!main) throw new Error("Missing main scroll target");
+ Object.defineProperty(main, "scrollHeight", {
+ configurable: true,
+ value: scrollHeight,
+ });
+ if (resetScrollTop) main.scrollTop = 0;
+ }, [resetScrollTop, scrollHeight]);
+
+ return null;
+}
+```
+
+Extend `renderRouter` so both route elements are injectable:
+
+```tsx
+async function renderRouter(
+ firstElement = <div>First</div>,
+ secondElement = <div>Second</div>
+) {
+ const router = createMemoryRouter(
+ [
+ {
+ path: "/",
+ element: <TestShell />,
+ children: [
+ { path: "first", element: firstElement },
+ { path: "second", element: secondElement },
+ ],
+ },
+ ],
+ {
+ initialEntries: [{ pathname: "/first", key: "first-entry" }],
+ }
+ );
+```
+
+- [ ] **Step 2: Write the failing history-snapshot test**
+
+Add this test after `snapshots the outgoing entry without waiting for a scroll event`:
+
+```tsx
+test("does not overwrite the outgoing position after destination layout commits", async () => {
+ const { main, router, unmount } = await renderRouter(
+ <RouteScrollMetrics scrollHeight={1000} />,
+ <RouteScrollMetrics scrollHeight={200} resetScrollTop />
+ );
+
+ main.scrollTop = 640;
+ await act(async () => {
+ await router.navigate("/second");
+ });
+ expect(main.scrollTop).toBe(0);
+
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(640);
+ unmount();
+});
+```
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/router/NavigationScrollRestoration.test.tsx
+```
+
+Expected: the new test fails with `expected 0 to be 640`, proving that the destination commit overwrote the outgoing entry.
+
+- [ ] **Step 3: Remove the post-commit snapshot**
+
+In the navigation `useLayoutEffect` in `NavigationScrollRestoration.tsx`, replace:
+
+```tsx
+const previousLocationKey = currentLocationKeyRef.current;
+if (previousLocationKey !== locationKey) {
+ recordAllTargets(previousLocationKey);
+}
+cancelPendingRestores();
+```
+
+with:
+
+```tsx
+const previousLocationKey = currentLocationKeyRef.current;
+cancelPendingRestores();
+```
+
+Remove `recordAllTargets` from that layout effect's dependency array. Do not remove this pre-commit subscription:
+
+```tsx
+useEffect(() => subscribeRoute(recordAllTargets), [recordAllTargets]);
+```
+
+That subscription is the authoritative outgoing snapshot; scroll events remain the incremental fast path, and `pagehide`/unmount remain persistence fallbacks.
+
+- [ ] **Step 4: Run the focused restoration tests**
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/router/NavigationScrollRestoration.test.tsx
+```
+
+Expected: all tests pass, including the new route-content-change regression and the existing repeated Push/Back, `preventScrollReset`, cancellation, and slow-page tests.
+
+- [ ] **Step 5: Inspect the timing-fix diff**
+
+Run `git diff --check` and keep the timing fix uncommitted on `main`.
+
+---
+
+## Task 2: Add semantic anchor correction for variable-height issue rows
+
+**Files:**
+
+- Modify: `frontend/src/react/router/NavigationScrollRestoration.test.tsx`
+- Modify: `frontend/src/react/router/NavigationScrollRestoration.tsx`
+
+**Interfaces:**
+
+- Consumes: registered targets using `data-scroll-restoration-id` and `MAIN_SCROLL_RESTORATION_ID`.
+- Produces: optional `ScrollPosition.anchor` and the DOM contract `data-scroll-restoration-anchor="stable-resource-name"` used by Task 5.
+
+- [ ] **Step 1: Add an anchor geometry test helper**
+
+Add `useRef` to the React import in `NavigationScrollRestoration.test.tsx`. First make `TestShell` capable of rendering the route directly under `main` while preserving the nested `panel` used by existing tests:
+
+```tsx
+function TestShell({ routeInsidePanel = true }: { routeInsidePanel?: boolean }) {
+ return (
+ <NavigationScrollRestoration>
+ <div data-scroll-restoration-id={MAIN_SCROLL_RESTORATION_ID}>
+ <div data-scroll-restoration-id="panel">
+ {routeInsidePanel ? <Outlet /> : null}
+ </div>
+ {routeInsidePanel ? null : <Outlet />}
+ </div>
+ </NavigationScrollRestoration>
+ );
+}
+```
+
+Extend the `renderRouter` signature introduced in Task 1 and pass the option into the shell. The empty `panel` remains mounted so its existing return type and all earlier tests stay unchanged:
+
+```tsx
+async function renderRouter(
+ firstElement = <div>First</div>,
+ secondElement = <div>Second</div>,
+ { routeInsidePanel = true }: { routeInsidePanel?: boolean } = {}
+) {
+ const router = createMemoryRouter(
+ [
+ {
+ path: "/",
+ element: <TestShell routeInsidePanel={routeInsidePanel} />,
+ children: [
+ { path: "first", element: firstElement },
+ { path: "second", element: secondElement },
+ ],
+ },
+ ],
+ {
+ initialEntries: [{ pathname: "/first", key: "first-entry" }],
+ }
+ );
+```
+
+Then extend `makeScrollable` with a real viewport rectangle so visibility checks do not use jsdom's zero-sized default:
+
+```tsx
+function makeScrollable(element: HTMLElement): void {
+ Object.defineProperties(element, {
+ clientHeight: { configurable: true, value: 200 },
+ clientWidth: { configurable: true, value: 200 },
+ scrollHeight: { configurable: true, value: 1000 },
+ scrollWidth: { configurable: true, value: 1000 },
+ });
+ element.getBoundingClientRect = () => ({
+ x: 0,
+ y: 0,
+ top: 0,
+ bottom: 200,
+ left: 0,
+ right: 200,
+ width: 200,
+ height: 200,
+ toJSON: () => ({}),
+ });
+}
+```
+
+Then add:
+
+```tsx
+function AnchorPage({ anchorTop }: { anchorTop: () => number }) {
+ const anchorRef = useRef<HTMLDivElement>(null);
+
+ useLayoutEffect(() => {
+ const anchor = anchorRef.current;
+ const main = anchor?.closest<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ if (!anchor || !main) throw new Error("Missing anchor test elements");
+
+ anchor.getBoundingClientRect = () => {
+ const top = anchorTop() - main.scrollTop;
+ return {
+ x: 0,
+ y: top,
+ top,
+ bottom: top + 40,
+ left: 0,
+ right: 200,
+ width: 200,
+ height: 40,
+ toJSON: () => ({}),
+ };
+ };
+ }, [anchorTop]);
+
+ return (
+ <div
+ ref={anchorRef}
+ data-scroll-restoration-anchor="issues/anchor"
+ >
+ Anchor
+ </div>
+ );
+}
+```
+
+- [ ] **Step 2: Write the failing variable-height test**
+
+Add:
+
+```tsx
+test("keeps the same semantic anchor offset when row geometry changes", async () => {
+ let anchorTop = 400;
+ const { main, router, unmount } = await renderRouter(
+ <AnchorPage anchorTop={() => anchorTop} />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+
+ recordScroll(main, 380);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ // Simulate content above the saved row becoming 60px taller before Back.
+ anchorTop = 460;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ // Coordinate-only restoration would leave scrollTop at 380 and move the
+ // anchor from 20px to 80px below the scroll viewport's top edge.
+ expect(main.scrollTop).toBe(440);
+ unmount();
+});
+```
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/router/NavigationScrollRestoration.test.tsx
+```
+
+Expected: the new test fails with `expected 380 to be 440`.
+
+- [ ] **Step 3: Extend saved positions with an optional anchor**
+
+Near the restoration constants and types, add:
+
+```tsx
+const ANCHOR_ATTRIBUTE = "data-scroll-restoration-anchor";
+
+type ScrollAnchor = {
+ key: string;
+ offset: number;
+};
+
+type ScrollPosition = {
+ x: number;
+ y: number;
+ anchor?: ScrollAnchor;
+};
+```
+
+Replace the existing `ScrollPosition` declaration rather than defining it twice.
+
+- [ ] **Step 4: Capture only anchors owned by the current scroll target**
+
+Add these helpers before `readPosition`:
+
+```tsx
+function anchorBelongsToTarget(
+ anchor: HTMLElement,
+ target: ScrollTarget
+): boolean {
+ const owner = anchor.closest<HTMLElement>(`[${TARGET_ATTRIBUTE}]`);
+ return isWindowTarget(target) ? owner === null : owner === target;
+}
+
+function readAnchor(target: ScrollTarget): ScrollAnchor | undefined {
+ const root: ParentNode = isWindowTarget(target) ? document : target;
+ const viewportTop = isWindowTarget(target)
+ ? 0
+ : target.getBoundingClientRect().top;
+ const viewportBottom = isWindowTarget(target)
+ ? window.innerHeight
+ : target.getBoundingClientRect().bottom;
+
+ for (const anchor of root.querySelectorAll<HTMLElement>(
+ `[${ANCHOR_ATTRIBUTE}]`
+ )) {
+ if (!anchorBelongsToTarget(anchor, target)) continue;
+ const key = anchor.getAttribute(ANCHOR_ATTRIBUTE);
+ const rect = anchor.getBoundingClientRect();
+ if (key && rect.bottom > viewportTop && rect.top < viewportBottom) {
+ return { key, offset: rect.top - viewportTop };
+ }
+ }
+ return undefined;
+}
+```
+
+Change `readPosition` to take an explicit anchor flag:
+
+```tsx
+function readPosition(
+ target: ScrollTarget,
+ includeAnchor = false
+): ScrollPosition {
+ const coordinate = isWindowTarget(target)
+ ? { x: window.scrollX, y: window.scrollY }
+ : { x: target.scrollLeft, y: target.scrollTop };
+ const anchor = includeAnchor ? readAnchor(target) : undefined;
+ return anchor ? { ...coordinate, anchor } : coordinate;
+}
+```
+
+Keep high-frequency scroll-event recording coordinate-only. In `recordAllTargets`, change every full snapshot to:
+
+```tsx
+savePosition(savedPositions, key, id, readPosition(target, true));
+```
+
+This covers both the router-subscription snapshot and the `pagehide`/unmount flush, because both call `recordAllTargets`. Anchors remain serializable in session storage, while avoiding row scans on every scroll event.
+
+- [ ] **Step 5: Apply the anchor after the coordinate becomes reachable**
+
+Add:
+
+```tsx
+function applyAnchor(target: ScrollTarget, anchor: ScrollAnchor): boolean {
+ const root: ParentNode = isWindowTarget(target) ? document : target;
+ const element = Array.from(
+ root.querySelectorAll<HTMLElement>(`[${ANCHOR_ATTRIBUTE}]`)
+ ).find(
+ (candidate) =>
+ candidate.getAttribute(ANCHOR_ATTRIBUTE) === anchor.key &&
+ anchorBelongsToTarget(candidate, target)
+ );
+ if (!element) return false;
+
+ const viewportTop = isWindowTarget(target)
+ ? 0
+ : target.getBoundingClientRect().top;
+ const delta = element.getBoundingClientRect().top - viewportTop - anchor.offset;
+ if (Math.abs(delta) < 1) return true;
+
+ if (isWindowTarget(target)) {
+ window.scrollTo(window.scrollX, window.scrollY + delta);
+ } else {
+ target.scrollTop += delta;
+ }
+ return true;
+}
+```
+
+In `restoreWhenReady`'s `attempt`, replace the `reached` branch with:
+
+```tsx
+const { range, reached } = applyPosition(observedTarget, position);
+if (reached) {
+ if (position.anchor) applyAnchor(observedTarget, position.anchor);
+ stop();
+ return;
+}
+```
+
+The coordinate remains the required fallback. The anchor is best-effort: a deleted or filtered-out row must not keep restoration alive for 30 seconds. During cold restoration, the existing range-growth loop delays this branch until enough pages have rendered; during warm restoration, the cached row is already in the DOM.
+
+- [ ] **Step 6: Run the restoration suite and inspect the diff**
+
+```bash
+pnpm --dir frontend exec vitest run src/react/router/NavigationScrollRestoration.test.tsx
+git diff --check
+```
+
+Expected: all restoration tests pass; the anchor test ends at `scrollTop === 440`.
+
+---
+
+## Task 3: Add an absolutely-expiring tab-memory cache for paged view snapshots
+
+**Files:**
+
+- Create: `frontend/src/react/hooks/pagedDataCache.ts`
+- Create: `frontend/src/react/hooks/pagedDataCache.test.ts`
+
+**Interfaces:**
+
+- Produces: `readPagedDataCache<T>(key)`, `writePagedDataCache<T>(key, snapshot)`, `deletePagedDataCache(key)`, `clearPagedDataCache()`, and `PagedDataCacheSnapshot<T>` for Task 4.
+- Lifetime: absolute five minutes from write; reads refresh only LRU order.
+
+- [ ] **Step 1: Write failing cache contract tests**
+
+Create `pagedDataCache.test.ts`:
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vitest";
+import {
+ clearPagedDataCache,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "./pagedDataCache";
+
+describe("pagedDataCache", () => {
+ afterEach(() => {
+ clearPagedDataCache();
+ vi.useRealTimers();
+ });
+
+ test("returns an isolated copy of a cached view", () => {
+ writePagedDataCache("issues", {
+ dataList: [{ name: "issues/1" }],
+ hasMore: true,
+ nextPageToken: "page-2",
+ });
+
+ const first = readPagedDataCache<{ name: string }>("issues");
+ first?.dataList.push({ name: "issues/local-only" });
+
+ expect(readPagedDataCache("issues")).toEqual({
+ dataList: [{ name: "issues/1" }],
+ hasMore: true,
+ nextPageToken: "page-2",
+ });
+ });
+
+ test("expires five minutes after write even when reads refresh LRU order", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-20T00:00:00Z"));
+ writePagedDataCache("issues", {
+ dataList: [{ name: "issues/1" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+
+ vi.advanceTimersByTime(4 * 60 * 1000);
+ expect(readPagedDataCache("issues")).toBeDefined();
+
+ vi.advanceTimersByTime(60 * 1000 + 1);
+
+ expect(readPagedDataCache("issues")).toBeUndefined();
+ });
+
+ test("evicts the least recently used view after twenty entries", () => {
+ for (let i = 0; i < 20; i++) {
+ writePagedDataCache(`issues-${i}`, {
+ dataList: [{ name: `issues/${i}` }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+ }
+ expect(readPagedDataCache("issues-0")).toBeDefined();
+
+ writePagedDataCache("issues-20", {
+ dataList: [{ name: "issues/20" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+
+ expect(readPagedDataCache("issues-1")).toBeUndefined();
+ expect(readPagedDataCache("issues-0")).toBeDefined();
+ });
+});
+```
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/hooks/pagedDataCache.test.ts
+```
+
+Expected: the suite fails because `pagedDataCache.ts` does not exist.
+
+- [ ] **Step 2: Implement the cache**
+
+Create `pagedDataCache.ts`:
+
+```ts
+export type PagedDataCacheSnapshot<T> = {
+ dataList: T[];
+ hasMore: boolean;
+ nextPageToken: string;
+};
+
+type StoredSnapshot<T> = PagedDataCacheSnapshot<T> & {
+ cachedAt: number;
+};
+
+const MAX_ENTRIES = 20;
+const MAX_AGE_MS = 5 * 60 * 1000;
+const cache = new Map<string, StoredSnapshot<unknown>>();
+
+// List arrays are copied so consumers cannot change membership/order in the
+// stored view. Items remain shared under the app's immutable proto convention.
+const cloneSnapshot = <T>(
+ snapshot: PagedDataCacheSnapshot<T>
+): PagedDataCacheSnapshot<T> => ({
+ dataList: [...snapshot.dataList],
+ hasMore: snapshot.hasMore,
+ nextPageToken: snapshot.nextPageToken,
+});
+
+export function readPagedDataCache<T>(
+ key: string | undefined
+): PagedDataCacheSnapshot<T> | undefined {
+ if (!key) return undefined;
+ const stored = cache.get(key) as StoredSnapshot<T> | undefined;
+ if (!stored) return undefined;
+ if (Date.now() - stored.cachedAt > MAX_AGE_MS) {
+ cache.delete(key);
+ return undefined;
+ }
+
+ // Refresh Map insertion order for LRU eviction without extending expiry.
+ cache.delete(key);
+ cache.set(key, stored as StoredSnapshot<unknown>);
+ return cloneSnapshot(stored);
+}
+
+export function writePagedDataCache<T>(
+ key: string | undefined,
+ snapshot: PagedDataCacheSnapshot<T>
+): void {
+ if (!key) return;
+ cache.delete(key);
+ cache.set(key, {
+ ...cloneSnapshot(snapshot),
+ cachedAt: Date.now(),
+ } as StoredSnapshot<unknown>);
+
+ while (cache.size > MAX_ENTRIES) {
+ const oldestKey = cache.keys().next().value as string | undefined;
+ if (!oldestKey) break;
+ cache.delete(oldestKey);
+ }
+}
+
+export function deletePagedDataCache(key: string | undefined): void {
+ if (key) cache.delete(key);
+}
+
+export function clearPagedDataCache(): void {
+ cache.clear();
+}
+```
+
+- [ ] **Step 3: Run the cache tests**
+
+```bash
+pnpm --dir frontend exec vitest run src/react/hooks/pagedDataCache.test.ts
+```
+
+Expected: 3 tests pass.
+
+---
+
+## Task 4: Hydrate `usePagedData` only for browser-history POP
+
+**Files:**
+
+- Modify: `frontend/src/react/hooks/usePagedData.test.tsx`
+- Modify: `frontend/src/react/hooks/usePagedData.tsx`
+
+**Interfaces:**
+
+- Consumes: the cache functions and snapshot type from Task 3.
+- Produces: optional `usePagedData({ cacheKey?: string, cacheRestoreToken?: string, ... })`; a history-entry token authorizes one synchronous cache read for that POP activation without changing `PagedDataResult<T>`.
+
+- [ ] **Step 1: Write failing POP-hydration and PUSH-bypass tests**
+
+Import `clearPagedDataCache` into `usePagedData.test.tsx` and call it in the existing `afterEach` inside `describe("usePagedData")`:
+
+```tsx
+import { clearPagedDataCache } from "./pagedDataCache";
+```
+
+```tsx
+clearPagedDataCache();
+```
+
+Add this module-level harness below the existing `Harness`:
+
+```tsx
+function CacheHarness({
+ cacheKey,
+ cacheRestoreToken,
+ fetchList,
+}: {
+ cacheKey: string;
+ cacheRestoreToken?: string;
+ fetchList: FetchList;
+}) {
+ const paged = usePagedData<Item>({
+ sessionKey: "test-cached-paged-data",
+ cacheKey,
+ cacheRestoreToken,
+ fetchList,
+ });
+
+ return (
+ <div>
+ <div data-state={paged.isLoading ? "loading" : "ready"}>
+ {paged.dataList.map((item) => item.name).join(",")}
+ </div>
+ <button type="button" onClick={paged.loadMore}>
+ load more
+ </button>
+ </div>
+ );
+}
+```
+
+Place both new tests inside the first `describe("usePagedData")` block, where the existing `container` and `root` bindings are defined. The first test proves a POP-style remount restores every page and the continuation token:
+
+```tsx
+test("restores every loaded page and cached token for history POP", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi
+ .fn<FetchList>()
+ .mockResolvedValueOnce({
+ list: [{ name: "items/1" }],
+ nextPageToken: "page-2",
+ })
+ .mockResolvedValueOnce({
+ list: [{ name: "items/2" }],
+ nextPageToken: "page-3",
+ });
+
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+ await act(async () => {
+ container!.querySelector("button")?.click();
+ await Promise.resolve();
+ });
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/1,items/2"
+ );
+
+ act(() => root?.unmount());
+ root = createRoot(container);
+ const resumedFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/3" }],
+ }));
+
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={resumedFetch}
+ />
+ );
+ });
+ expect(container.querySelector("[data-state]")?.getAttribute("data-state")).toBe(
+ "ready"
+ );
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/1,items/2"
+ );
+ expect(resumedFetch).not.toHaveBeenCalled();
+
+ await act(async () => {
+ container!.querySelector("button")?.click();
+ await Promise.resolve();
+ });
+ expect(resumedFetch).toHaveBeenCalledWith({
+ pageSize: 50,
+ pageToken: "page-3",
+ });
+});
+```
+
+The second test proves a PUSH-style remount ignores an existing snapshot and fetches current data:
+
+```tsx
+test("fetches current data for a push-style remount", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/cached" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+
+ act(() => root?.unmount());
+ root = createRoot(container);
+ const currentFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/current" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={currentFetch} />
+ );
+ await Promise.resolve();
+ });
+
+ expect(currentFetch).toHaveBeenCalledOnce();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/current"
+ );
+});
+```
+
+Add a fourth regression that keeps the hook mounted, visits another cache key
+with no POP token, then returns to the original history token. The original
+snapshot must hydrate again without a request; this proves token consumption is
+scoped to one POP activation rather than permanently suppressing that history
+entry.
+
+Add another test to prove that merely hydrating the snapshot does not renew its absolute age:
+
+```tsx
+test("does not extend absolute expiry when a history view is hydrated", async () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-20T00:00:00Z"));
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/cached" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+ act(() => root?.unmount());
+
+ act(() => vi.advanceTimersByTime(4 * 60 * 1000));
+ root = createRoot(container);
+ const warmFetch = vi.fn<FetchList>(async () => ({ list: [] }));
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={warmFetch}
+ />
+ );
+ });
+ expect(warmFetch).not.toHaveBeenCalled();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/cached"
+ );
+ act(() => root?.unmount());
+
+ act(() => vi.advanceTimersByTime(60 * 1000 + 1));
+ root = createRoot(container);
+ const expiredFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/current" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={expiredFetch}
+ />
+ );
+ await Promise.resolve();
+ });
+
+ expect(expiredFetch).toHaveBeenCalledOnce();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/current"
+ );
+});
+```
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/hooks/usePagedData.test.tsx
+```
+
+Expected: TypeScript/Vitest fails because `usePagedData` does not accept `cacheKey` or `cacheRestoreToken`, does not persist/hydrate snapshots, and has no protection against hydration renewing cache age.
+
+- [ ] **Step 2: Add cache ownership and dirty-state tracking to the reducer**
+
+In `usePagedData.tsx`, import `useLayoutEffect` and `useState`, plus the cache helpers:
+
+```tsx
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useReducer,
+ useRef,
+ useState,
+} from "react";
+import {
+ deletePagedDataCache,
+ type PagedDataCacheSnapshot,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "./pagedDataCache";
+```
+
+Extend the reducer state/actions. `cacheWriteState` is the critical distinction: hydrated snapshots are `clean`, while successful fetches and local list mutations are `dirty` and may reset absolute cache age.
+
+```tsx
+type PagedDataState<T> = {
+ cacheKey?: string;
+ cacheWriteState: "clean" | "dirty";
+ dataList: T[];
+ status: "idle" | "loading" | "ready" | "loadingMore";
+ hasMore: boolean;
+};
+
+type PagedDataAction<T> =
+ | {
+ type: "restore-cache";
+ cacheKey?: string;
+ snapshot?: PagedDataCacheSnapshot<T>;
+ }
+ | { type: "fetch-start"; mode: FetchMode; cacheKey?: string }
+ | {
+ type: "fetch-success";
+ mode: FetchMode;
+ cacheKey?: string;
+ list: T[];
+ hasMore: boolean;
+ }
+ | { type: "fetch-error" }
+ | { type: "update-cache"; items: T[] }
+ | { type: "remove-cache"; item: T }
+ | { type: "cache-persisted"; cacheKey?: string };
+
+const stateFromSnapshot = <T extends { name: string }>(
+ cacheKey: string | undefined,
+ snapshot?: PagedDataCacheSnapshot<T>
+): PagedDataState<T> => ({
+ cacheKey,
+ cacheWriteState: "clean",
+ dataList: snapshot?.dataList ?? [],
+ status: snapshot ? "ready" : "idle",
+ hasMore: snapshot?.hasMore ?? false,
+});
+```
+
+Replace the corresponding reducer cases with:
+
+```tsx
+case "restore-cache":
+ return stateFromSnapshot(action.cacheKey, action.snapshot);
+case "fetch-start":
+ return {
+ ...state,
+ cacheKey: action.cacheKey,
+ status: action.mode === "refresh" ? "loading" : "loadingMore",
+ };
+case "fetch-success":
+ return {
+ cacheKey: action.cacheKey,
+ cacheWriteState: "dirty",
+ dataList:
+ action.mode === "refresh"
+ ? action.list
+ : [...state.dataList, ...action.list],
+ status: "ready",
+ hasMore: action.hasMore,
+ };
+case "fetch-error":
+ return {
+ ...state,
+ cacheWriteState: "clean",
+ status: "ready",
+ };
+case "update-cache": {
+ const dataList = [...state.dataList];
+ for (const item of action.items) {
+ const index = dataList.findIndex((data) => data.name === item.name);
+ if (index >= 0) dataList[index] = item;
+ else dataList.push(item);
+ }
+ return { ...state, cacheWriteState: "dirty", dataList };
+}
+case "remove-cache":
+ return {
+ ...state,
+ cacheWriteState: "dirty",
+ dataList: state.dataList.filter(
+ (data) => data.name !== action.item.name
+ ),
+ };
+case "cache-persisted":
+ return action.cacheKey === state.cacheKey
+ ? { ...state, cacheWriteState: "clean" }
+ : state;
+```
+
+- [ ] **Step 3: Seed cache only when the caller identifies history restoration**
+
+Add both options to the hook; they remain optional so the other 14 call sites keep existing behavior:
+
+```tsx
+export function usePagedData<T extends { name: string }>({
+ sessionKey,
+ cacheKey,
+ cacheRestoreToken,
+ fetchList,
+ enabled = true,
+}: {
+ sessionKey: string;
+ cacheKey?: string;
+ cacheRestoreToken?: string;
+ fetchList: (params: {
+ pageSize: number;
+ pageToken: string;
+ }) => Promise<{ list: T[]; nextPageToken?: string }>;
+ enabled?: boolean;
+}): PagedDataResult<T> {
+```
+
+After obtaining `pageSize`, initialize the reducer and refs from at most one POP-authorized cache read:
+
+```tsx
+const resolvedCacheKey = cacheKey
+ ? `${cacheKey}:page-size=${pageSize}`
+ : undefined;
+const [initialCache] = useState(() => ({
+ key: resolvedCacheKey,
+ cacheRestoreToken,
+ snapshot: cacheRestoreToken
+ ? readPagedDataCache<T>(resolvedCacheKey)
+ : undefined,
+}));
+const [state, dispatch] = useReducer(
+ pagedDataReducer<T>,
+ initialCache,
+ ({ key, snapshot }) => stateFromSnapshot(key, snapshot)
+);
+
+const abortRef = useRef<AbortController | null>(null);
+const fetchIdRef = useRef(0);
+const nextPageTokenRef = useRef(initialCache.snapshot?.nextPageToken ?? "");
+const activeCacheKeyRef = useRef(initialCache.key);
+const activeCacheRestoreTokenRef = useRef(initialCache.cacheRestoreToken);
+const consumedCacheRestoreTokenRef = useRef(initialCache.cacheRestoreToken);
+const skipNextFetchRef = useRef(Boolean(initialCache.snapshot));
+```
+
+Delete the old reducer initialization and duplicate refs. Add this layout effect before the fetch-on-mount effect so filter/order history POP can switch views before paint:
+
+```tsx
+useLayoutEffect(() => {
+ if (
+ activeCacheKeyRef.current === resolvedCacheKey &&
+ activeCacheRestoreTokenRef.current === cacheRestoreToken
+ ) {
+ return;
+ }
+ fetchIdRef.current++;
+ abortRef.current?.abort();
+ activeCacheKeyRef.current = resolvedCacheKey;
+ activeCacheRestoreTokenRef.current = cacheRestoreToken;
+
+ const shouldRestore =
+ cacheRestoreToken !== undefined &&
+ consumedCacheRestoreTokenRef.current !== cacheRestoreToken;
+ consumedCacheRestoreTokenRef.current = cacheRestoreToken;
+ const snapshot = shouldRestore
+ ? readPagedDataCache<T>(resolvedCacheKey)
+ : undefined;
+ nextPageTokenRef.current = snapshot?.nextPageToken ?? "";
+ skipNextFetchRef.current = Boolean(snapshot);
+ dispatch({
+ type: "restore-cache",
+ cacheKey: resolvedCacheKey,
+ snapshot,
+ });
+}, [cacheRestoreToken, resolvedCacheKey]);
+```
+
+- [ ] **Step 4: Persist only fetched or mutated state**
+
+In `doFetch`, associate both dispatches with the active key:
+
+```tsx
+const mode: FetchMode = isRefresh ? "refresh" : "append";
+const activeCacheKey = activeCacheKeyRef.current;
+dispatch({ type: "fetch-start", mode, cacheKey: activeCacheKey });
+```
+
+```tsx
+dispatch({
+ type: "fetch-success",
+ mode,
+ cacheKey: activeCacheKey,
+ list: result.list,
+ hasMore: Boolean(result.nextPageToken),
+});
+```
+
+After `removeCache`, add this effect. It writes once for dirty state and immediately marks that state clean, so a POP hydration never renews `cachedAt`:
+
+```tsx
+useEffect(() => {
+ if (
+ state.cacheWriteState !== "dirty" ||
+ state.status !== "ready" ||
+ state.cacheKey !== resolvedCacheKey
+ ) {
+ return;
+ }
+ writePagedDataCache(state.cacheKey, {
+ dataList: state.dataList,
+ hasMore: state.hasMore,
+ nextPageToken: nextPageTokenRef.current,
+ });
+ dispatch({ type: "cache-persisted", cacheKey: state.cacheKey });
+}, [resolvedCacheKey, state]);
+```
+
+Make explicit refresh remove the snapshot before fetching:
+
+```tsx
+const refresh = useCallback(() => {
+ deletePagedDataCache(activeCacheKeyRef.current);
+ doFetch(true);
+}, [doFetch]);
+```
+
+An initial/refresh error stays `clean`, so it cannot write an empty or stale error state into a new five-minute snapshot.
+
+- [ ] **Step 5: Skip the request only when a POP snapshot was actually found**
+
+Update the existing fetch-on-mount effect:
+
+```tsx
+const isFirstLoad = useRef(true);
+useEffect(() => {
+ if (!enabled) return;
+ if (skipNextFetchRef.current) {
+ skipNextFetchRef.current = false;
+ isFirstLoad.current = false;
+ return;
+ }
+ if (isFirstLoad.current) {
+ isFirstLoad.current = false;
+ doFetch(true);
+ return;
+ }
+ fetchIdRef.current++;
+ abortRef.current?.abort();
+ dispatch({
+ type: "fetch-start",
+ mode: "refresh",
+ cacheKey: activeCacheKeyRef.current,
+ });
+ const timer = setTimeout(() => doFetch(true), 300);
+ return () => clearTimeout(timer);
+}, [cacheRestoreToken, doFetch, enabled, resolvedCacheKey]);
+```
+
+Do not background-revalidate page one after a successful POP hydration: replacing a multi-page view with page one collapses scroll range. PUSH/REPLACE already fetches current data; POP after the absolute five-minute age becomes a cold fetch and uses the existing page-growth protocol.
+
+- [ ] **Step 6: Run both cache suites and inspect the diff**
+
+```bash
+pnpm --dir frontend exec vitest run src/react/hooks/pagedDataCache.test.ts src/react/hooks/usePagedData.test.tsx
+git diff --check
+```
+
+Expected: cache tests, POP hydration, cached-token continuation, PUSH bypass, and the pre-existing debounced-refresh test all pass.
+
+---
+
+## Task 5: Opt issue dashboards into cached views and stable row anchors
+
+**Files:**
+
+- Modify: `frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx`
+- Modify: `frontend/src/react/pages/workspace/MyIssuesPage.tsx`
+- Modify: `frontend/src/react/components/IssueTable.tsx`
+
+**Interfaces:**
+
+- Consumes: `cacheRestoreToken` from Task 4 and `data-scroll-restoration-anchor` from Task 2.
+- Produces: independent filter/order/page-size view keys plus issue-row anchors keyed by `issue.name`.
+
+- [ ] **Step 1: Add a POP-aware, filter-aware project issue view key**
+
+In `ProjectIssueDashboardPage.tsx`, import `useLocation` and `useNavigationType`:
+
+```tsx
+import { useNavigationType } from "react-router";
+```
+
+Read the navigation action inside the page and add this memo after `orderBy`:
+
+```tsx
+const navigationType = useNavigationType();
+const location = useLocation();
+const viewCacheKey = useMemo(
+ () =>
+ JSON.stringify([
+ "project-issues",
+ projectName,
+ serializeSearchParams(searchParams),
+ orderBy,
+ ]),
+ [orderBy, projectName, searchParams]
+);
+```
+
+Pass it to the hook:
+
+```tsx
+const paged = usePagedData<Issue>({
+ sessionKey: "bb.issue-table.project-issues",
+ cacheKey: viewCacheKey,
+ cacheRestoreToken: navigationType === "POP" ? location.key : undefined,
+ fetchList: fetchIssueList,
+});
+```
+
+`POP` here authorizes only the synchronous view seed. It does not stand in for the active restoration lifecycle; `NavigationScrollRestoration` and `useScrollRestorationLoadMore` still own completion, cancellation, timeout, and page growth. Keep `useScrollRestorationLoadMore(paged)` for expired/missing snapshots and positions deeper than the warm snapshot.
+
+- [ ] **Step 2: Add the same explicit POP policy to My Issues**
+
+In `MyIssuesPage.tsx`, import `useLocation` and `useNavigationType`, then add:
+
+```tsx
+import { useLocation, useNavigationType } from "react-router";
+```
+
+```tsx
+const navigationType = useNavigationType();
+const location = useLocation();
+const viewCacheKey = useMemo(
+ () =>
+ JSON.stringify([
+ "my-issues",
+ serializeSearchParams(searchParams),
+ orderBy,
+ ]),
+ [orderBy, searchParams]
+);
+```
+
+Pass it to `usePagedData`:
+
+```tsx
+const paged = usePagedData<Issue>({
+ sessionKey: "bb.issue-table.my-issues",
+ cacheKey: viewCacheKey,
+ cacheRestoreToken: navigationType === "POP" ? location.key : undefined,
+ fetchList: fetchIssueList,
+});
+```
+
+Both pages already use URL param `q` through `useURLSearchParam({ param: "q", ... })`; the serialized search text therefore drives both the backend filter and `IssueListPanel` highlight state. No route/query-key change is needed for the E2E token.
+
+- [ ] **Step 3: Mark each issue row as a semantic anchor**
+
+In `IssueListItem`, change the outer row to:
+
+```tsx
+<div
+ data-slot="issue-list-item"
+ data-testid="issue-list-item"
+ data-scroll-restoration-anchor={issue.name}
+ className="flex items-start gap-x-2 px-4 py-3 cursor-pointer border-b border-block-border transition-colors last:border-b-0 hover:bg-control-bg/60"
+ onClick={onRowClick}
+>
+```
+
+The resource name is stable, unique within the list, and independent of translated title text or sort position.
+
+- [ ] **Step 4: Run focused tests and type-check the integration**
+
+```bash
+pnpm --dir frontend exec vitest run src/react/router/NavigationScrollRestoration.test.tsx src/react/hooks/pagedDataCache.test.ts src/react/hooks/usePagedData.test.tsx
+pnpm --dir frontend type-check
+```
+
+Expected: all focused tests pass and TypeScript accepts both opt-in call sites; the other `usePagedData` call sites remain unchanged because both `cacheKey` and `cacheRestoreToken` are optional. A normal nav-link PUSH to Issues fetches instead of painting a potentially stale snapshot.
+
+- [ ] **Step 5: Inspect the issue-list integration**
+
+Run `git diff --check` and keep the Issue integration uncommitted and unstaged.
+
+---
+
+## Task 6: Enforce one dashboard route-level vertical scroll owner
+
+**Files:**
+
+- Modify: `frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx`
+- Modify: `frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx`
+
+**Interfaces:**
+
+- Consumes: the dashboard ancestor carrying `data-scroll-restoration-id={MAIN_SCROLL_RESTORATION_ID}`.
+- Produces: no new exported API; plan detail delegates vertical scrolling and sticky state to that ancestor.
+
+- [ ] **Step 1: Write the failing plan-detail ownership test**
+
+Import the main restoration id in `ProjectPlanDetailPage.test.tsx`:
+
+```tsx
+import { MAIN_SCROLL_RESTORATION_ID } from "@/react/router/NavigationScrollRestoration";
+```
+
+Add this test near the start of the `ProjectPlanDetailPage` suite:
+
+```tsx
+it("uses the dashboard main pane as its vertical scroll owner", async () => {
+ mocks.usePlanDetailPage.mockReturnValue(buildPage());
+
+ await act(async () => {
+ root.render(
+ <div data-scroll-restoration-id={MAIN_SCROLL_RESTORATION_ID}>
+ <ProjectPlanDetailPage
+ planId="create"
+ projectId="foo"
+ specId="spec-1"
+ />
+ </div>
+ );
+ await Promise.resolve();
+ });
+
+ const scrollHost = container.querySelector<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ const pageHost = container.querySelector<HTMLElement>(
+ '[data-testid="plan-detail-page"]'
+ );
+ const header = pageHost?.querySelector("header");
+ if (!scrollHost || !pageHost || !header) {
+ throw new Error("Missing plan-detail scroll test elements");
+ }
+
+ const pageHostClasses = pageHost.className.split(/\s+/);
+ expect(pageHostClasses).toContain("min-h-full");
+ expect(pageHostClasses).toContain("overflow-x-clip");
+ expect(pageHostClasses).not.toContain("h-full");
+ expect(pageHostClasses).not.toContain("overflow-x-hidden");
+
+ act(() => {
+ scrollHost.scrollTop = 1;
+ scrollHost.dispatchEvent(new Event("scroll"));
+ });
+ expect(header.className).toContain("border-b");
+});
+```
+
+Run:
+
+```bash
+pnpm --dir frontend exec vitest run src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx
+```
+
+Expected: the test fails because the page host still has `h-full overflow-x-hidden`, lacks the test id, and listens to its own `scrollTop`.
+
+- [ ] **Step 2: Listen to the registered dashboard main pane**
+
+Import `MAIN_SCROLL_RESTORATION_ID` in `ProjectPlanDetailPage.tsx`:
+
+```tsx
+import { MAIN_SCROLL_RESTORATION_ID } from "@/react/router/NavigationScrollRestoration";
+```
+
+Replace the current `pageHost` scroll effect with:
+
+```tsx
+const [pageHost, setPageHost] = useState<HTMLDivElement | null>(null);
+// The sticky title row is positioned inside the dashboard's registered main
+// pane, so its divider follows that pane's scroll state.
+const [headerStuck, setHeaderStuck] = useState(false);
+useEffect(() => {
+ if (!pageHost) return;
+ const scrollHost = pageHost.closest<HTMLElement>(
+ `[data-scroll-restoration-id="${MAIN_SCROLL_RESTORATION_ID}"]`
+ );
+ if (!scrollHost) return;
+
+ const onScroll = () => setHeaderStuck(scrollHost.scrollTop > 0);
+ onScroll();
+ scrollHost.addEventListener("scroll", onScroll, { passive: true });
+ return () => scrollHost.removeEventListener("scroll", onScroll);
+}, [pageHost]);
+```
+
+- [ ] **Step 3: Stop the page host from creating an implicit y scroller**
+
+Change the page host to:
+
+```tsx
+<div
+ ref={setPageHost}
+ data-testid="plan-detail-page"
+ className="relative min-h-full overflow-x-clip bg-gray-50"
+>
+```
+
+Update the sticky-header comment to describe `#bb-layout-main` as the scroll container. `overflow-x-clip` clips horizontal paint without causing `overflow-y: auto`; `overflow-x-hidden` does cause an implicit vertical scrolling box and must not remain. `min-h-full` gives the page a one-viewport minimum while allowing its box and `bg-gray-50` painting area to grow with long content; keeping `h-full` would leave below-fold content overflowing a one-viewport background box.
+
+- [ ] **Step 4: Run the plan-detail and restoration tests**
+
+```bash
+pnpm --dir frontend exec vitest run src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx src/react/router/NavigationScrollRestoration.test.tsx
+```
+
+Expected: both suites pass. The sticky divider reacts to the outer main pane, and list-to-detail navigation no longer changes scroll ownership.
+
+- [ ] **Step 5: Verify below-fold background and sticky behavior in a browser**
+
+Run the local frontend/backend or use the Playwright environment, then open a plan detail containing more than one viewport of expanded content:
+
+1. At the top, confirm `#bb-layout-main.scrollTop === 0` and `window.scrollY === 0`.
+2. Scroll past the first viewport and confirm `#bb-layout-main.scrollTop > 0` while `window.scrollY` remains `0`.
+3. Confirm the gray page background continues behind below-fold content instead of switching to the parent background.
+4. Confirm the plan title header remains sticky at the main-pane top and gains its bottom border while scrolled.
+
+Expected: one vertical scrollbar on `#bb-layout-main`, continuous gray background for the full plan, and no plan-detail inner scrollbar.
+
+- [ ] **Step 6: Inspect the single-owner fix**
+
+Run `git diff --check` and keep the layout changes uncommitted and unstaged.
+
+---
+
+## Task 7: Add dashboard browser regression coverage, including the banner
+
+**Files:**
+
+- Create: `frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts`
+
+**Interfaces:**
+
+- Consumes: `data-testid="issue-list-item"`, `#bb-layout-main`, real project issue routes, and the workspace external-URL banner.
+- Produces: serial browser regression coverage for POP restoration with and without wrapped banner geometry.
+
+- [ ] **Step 1: Create owned issue fixtures and reusable position helpers**
+
+Create the E2E file with the following complete structure:
+
+```ts
+import {
+ expect,
+ test,
+ type BrowserContext,
+ type Locator,
+ type Page,
+} from "@playwright/test";
+import { BytebaseApiClient } from "../framework/api-client";
+import { loadTestEnv, type TestEnv } from "../framework/env";
+
+test.setTimeout(240_000);
+
+const ISSUE_COUNT = 18;
+let env: TestEnv & { api: BytebaseApiClient };
+let sharedContext: BrowserContext;
+let page: Page;
+let listUrl: string;
+let originalExternalUrl = "";
+
+type SavedViewport = {
+ scrollTop: number;
+ anchorOffset: number;
+};
+
+const readViewport = (row: Locator): Promise<SavedViewport> =>
+ row.evaluate((element) => {
+ const main = document.querySelector<HTMLElement>("#bb-layout-main");
+ if (!main) throw new Error("Missing #bb-layout-main");
+ return {
+ scrollTop: main.scrollTop,
+ anchorOffset:
+ element.getBoundingClientRect().top -
+ main.getBoundingClientRect().top,
+ };
+ });
+
+async function expectBackRestored(): Promise<void> {
+ await page.goto(listUrl);
+ const rows = page.getByTestId("issue-list-item");
+ await expect(rows).toHaveCount(ISSUE_COUNT, { timeout: 20_000 });
+
+ const target = rows.last();
+ await target.scrollIntoViewIfNeeded();
+ const before = await readViewport(target);
+ expect(before.scrollTop).toBeGreaterThan(100);
+
+ await target.click();
+ await expect(page).toHaveURL(/\/projects\/[^/]+\/plans\//, {
+ timeout: 20_000,
+ });
+ await page.goBack();
+ await expect(page).toHaveURL(listUrl);
+ await expect(target).toBeVisible({ timeout: 20_000 });
+
+ await expect
+ .poll(async () => {
+ const after = await readViewport(target);
+ return Math.abs(after.scrollTop - before.scrollTop);
+ })
+ .toBeLessThanOrEqual(2);
+ await expect
+ .poll(async () => {
+ const after = await readViewport(target);
+ return Math.abs(after.anchorOffset - before.anchorOffset);
+ })
+ .toBeLessThanOrEqual(2);
+ expect(await page.evaluate(() => window.scrollY)).toBe(0);
+}
+
+test.beforeAll(async ({ browser }) => {
+ env = loadTestEnv();
+ await env.api.login(env.adminEmail, env.adminPassword);
+ const projectId = env.project.split("/").pop()!;
+ const stamp = Date.now();
+ const searchToken = `scroll-restoration-${stamp}`;
+ listUrl = `${env.baseURL}/projects/${projectId}/issues?q=${encodeURIComponent(
+ searchToken
+ )}`;
+
+ const setting = await env.api.getSetting("WORKSPACE_PROFILE");
+ originalExternalUrl =
+ (setting?.value as { workspaceProfile?: { externalUrl?: string } })
+ ?.workspaceProfile?.externalUrl ?? "";
+
+ const sheet = await env.api.createSheet(env.project, "SELECT 1;");
+ for (let i = 0; i < ISSUE_COUNT; i++) {
+ const title = `${searchToken} issue ${i}`;
+ const plan = await env.api.createPlan(env.project, title, [
+ {
+ id: `scroll-restoration-${stamp}-${i}`,
+ targets: [env.database],
+ sheet,
+ },
+ ]);
+ const repeatedDescription = Array.from(
+ { length: (i % 4) + 1 },
+ () => `${searchToken} variable-height content`
+ ).join("\n");
+ await env.api.createIssue(
+ env.project,
+ title,
+ plan.name,
+ repeatedDescription
+ );
+ }
+
+ sharedContext = await browser.newContext({
+ storageState: ".auth/state.json",
+ // Below Tailwind's sm breakpoint, the banner CTA moves onto its own row.
+ viewport: { width: 600, height: 720 },
+ });
+ page = await sharedContext.newPage();
+});
+
+test.afterAll(async () => {
+ await env.api.setWorkspaceExternalUrl(originalExternalUrl).catch(() => {});
+ await sharedContext?.close();
+});
+
+test.describe("dashboard scroll restoration", () => {
+ test.describe.configure({ mode: "serial" });
+
+ test("restores the nested main pane without a banner", async () => {
+ await env.api.setWorkspaceExternalUrl(env.baseURL);
+ await page.goto(listUrl);
+ await expect(
+ page.getByRole("link", { name: /Configure now/i })
+ ).toHaveCount(0);
+ await expectBackRestored();
+ });
+
+ test("restores the nested main pane below a wrapped banner", async () => {
+ await env.api.setWorkspaceExternalUrl("");
+ await page.goto(listUrl);
+ await expect(
+ page.getByRole("link", { name: /Configure now/i }).first()
+ ).toBeVisible({ timeout: 10_000 });
+ await expectBackRestored();
+ });
+});
+```
+
+The project page reads this exact `q` parameter through `useURLSearchParam`, so the query token both scopes the backend result to owned rows and activates description highlighting. Descriptions of different lengths exercise semantic-anchor correction. The test asserts both coordinate and row-relative position; coordinate alone would miss a variable-height drift. It also asserts `window.scrollY === 0`, locking the nested-scroller architecture.
+
+`ISSUE_COUNT` intentionally remains below the default page size of 50. This E2E suite owns the cross-layer browser contract—Router POP, real list/detail DOM, nested main scroller, semantic row offset, and banner geometry—without creating more than 50 plans and issues. Task 4's focused hook test owns the multi-page snapshot and cached-token continuation contract; Task 1/2 own cold page-growth behavior. Do not inflate this browser suite solely to duplicate those deterministic unit tests.
+
+- [ ] **Step 2: Run the E2E spec**
+
+Follow `frontend/tests/e2e/README.md` prerequisites: build the embedded frontend/server, provide the enterprise test license, and let the setup project create `.auth/state.json` and `.e2e-env.json`. Then run:
+
+```bash
+cd frontend
+pnpm exec playwright test scroll-restoration/dashboard-scroll-restoration.spec.ts
+```
+
+Expected: 3 tests pass in serial mode. There are no arbitrary sleeps; all waits are tied to URLs, rows, banner visibility, or measured position convergence.
+
+- [ ] **Step 3: Inspect the browser coverage**
+
+Run `git diff --check` and keep the E2E coverage uncommitted and unstaged.
+
+---
+
+## Task 8: Connect Project Plans to the generic paginated-view contract
+
+**Files:**
+
+- Create: `frontend/src/react/pages/project/ProjectPlanDashboardPage.test.tsx`
+- Modify: `frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx`
+- Modify: `frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts`
+
+**Interfaces:**
+
+- Consumes: resource-agnostic `usePagedData({ cacheKey, cacheRestoreToken, fetchList })`, `useScrollRestorationLoadMore(paged)`, `useURLSearchParam`, and `data-scroll-restoration-anchor`.
+- Produces: a filter-stable Project Plans view whose loaded pages and semantic row position restore on POP exactly like Project Issues.
+
+- [ ] **Step 1: Write failing Plans integration tests**
+
+Render `ProjectPlanDashboardPage` inside a memory router with `usePagedData` mocked only at its public boundary. Assert the page passes a project/filter-aware key and the current POP history key:
+
+```tsx
+expect(mockUsePagedData).toHaveBeenCalledWith(
+ expect.objectContaining({
+ cacheKey: expect.stringContaining("project-plans"),
+ cacheRestoreToken: "default",
+ })
+);
+```
+
+Render one Plan and assert its existing table row exposes the generic semantic contract:
+
+```tsx
+expect(
+ container.querySelector(
+ '[data-scroll-restoration-anchor="projects/foo/plans/1"]'
+ )
+).not.toBeNull();
+```
+
+Start the router at `?q=state:DELETED` and assert the view key contains the serialized URL-owned filter rather than the component default.
+
+- [ ] **Step 2: Run the Plans test and verify RED**
+
+```bash
+pnpm --dir frontend exec vitest run \
+ src/react/pages/project/ProjectPlanDashboardPage.test.tsx
+```
+
+Expected: the cache-token and row-anchor assertions fail because Plans has not opted into the generic contract.
+
+- [ ] **Step 3: Make the Plan filter URL-owned and opt into generic restoration**
+
+Use the shared Advanced Search parser/serializer and the same page-level wiring already used by Issues:
+
+```tsx
+const [searchParams, setSearchParams] = useURLSearchParam({
+ param: "q",
+ parse: parsePlanSearchParams,
+ serialize: serializeAdvancedSearch,
+ defaultValue: defaultSearchParams,
+});
+const viewCacheKey = JSON.stringify([
+ "project-plans",
+ projectName,
+ serializeAdvancedSearch(searchParams),
+]);
+const paged = usePagedData<Plan>({
+ sessionKey: `bb.${projectName}.plan-table`,
+ cacheKey: viewCacheKey,
+ cacheRestoreToken:
+ navigationType === "POP" ? location.key : undefined,
+ fetchList: fetchPlanList,
+});
+```
+
+Do not put Plan-specific behavior inside `usePagedData`, `pagedDataCache`, or `NavigationScrollRestoration`.
+
+- [ ] **Step 4: Mark every Plan row with its stable resource name**
+
+```tsx
+<TableRow
+ data-testid="plan-list-item"
+ data-scroll-restoration-anchor={plan.name}
+ ...
+>
+```
+
+- [ ] **Step 5: Run the Plans and generic restoration suites**
+
+```bash
+pnpm --dir frontend exec vitest run \
+ src/react/pages/project/ProjectPlanDashboardPage.test.tsx \
+ src/react/hooks/usePagedData.test.tsx \
+ src/react/router/NavigationScrollRestoration.test.tsx
+```
+
+Expected: all pass; generic hook/router tests remain resource-neutral.
+
+- [ ] **Step 6: Extend browser coverage to Project Plans**
+
+Reuse the owned Plans already created by the scroll-restoration E2E fixture. Navigate to the Project Plans URL with its URL-backed `q`, load more than one page through the real footer, click the last `plan-list-item`, go Back, and assert both `#bb-layout-main.scrollTop` and the Plan row's viewport-relative offset converge while `window.scrollY` remains `0`.
+
+---
+
+## Task 9: Run the complete frontend verification gates
+
+**Files:** validation only; review any formatter changes before keeping them.
+
+**Interfaces:**
+
+- Consumes: all production and test changes from Tasks 1–8.
+- Produces: formatter, static-check, type-check, unit-test, E2E, and diff evidence required before completion.
+
+- [ ] **Step 1: Run focused unit tests once more**
+
+```bash
+pnpm --dir frontend exec vitest run \
+ src/react/router/NavigationScrollRestoration.test.tsx \
+ src/react/hooks/pagedDataCache.test.ts \
+ src/react/hooks/usePagedData.test.tsx \
+ src/react/pages/project/ProjectPlanDashboardPage.test.tsx \
+ src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx
+```
+
+Expected: all focused tests pass.
+
+- [ ] **Step 2: Run the repository-required frontend fixer**
+
+```bash
+pnpm --dir frontend fix
+```
+
+Expected: exits successfully. Inspect `git diff` and keep only formatting/import-order changes in the files covered by this plan.
+
+- [ ] **Step 3: Run the CI-equivalent frontend check**
+
+```bash
+pnpm --dir frontend check
+```
+
+Expected: Biome, UUID, i18n, layering, and locale-sort checks all pass.
+
+- [ ] **Step 4: Run TypeScript and all Vitest suites**
+
+```bash
+pnpm --dir frontend type-check
+pnpm --dir frontend test
+```
+
+Expected: TypeScript build passes and all frontend unit tests pass.
+
+- [ ] **Step 5: Re-run the browser regression after formatting**
+
+```bash
+cd frontend
+pnpm exec playwright test scroll-restoration/dashboard-scroll-restoration.spec.ts
+```
+
+Expected: both Issue banner variants and the paginated Plans case pass.
+
+- [ ] **Step 6: Inspect the final diff and whitespace**
+
+```bash
+git status --short
+git diff --check
+git diff --stat
+```
+
+Expected:
+
+- No backend, proto, SQL Editor, dependency, locale, or generated-file changes.
+- `git diff --check` produces no output.
+- The dashboard shells still expose the banner and header outside `#bb-layout-main`.
+- Every added test fails for the intended reason before its implementation step and passes afterward.
+
+---
+
+## Acceptance checklist
+
+- [ ] Browser Back from detail restores both Project Issues and Project Plans to their prior `#bb-layout-main.scrollTop`.
+- [ ] The same Issue or Plan row returns to the same viewport-relative offset when row heights differ.
+- [ ] Previously loaded pages paint on the first warm POP render; the UI does not replay Load More page-by-page on a cache hit.
+- [ ] PUSH/REPLACE mounts never skip their list request merely because the same view key exists in cache.
+- [ ] Cache reads and POP hydrations do not extend the five-minute absolute expiry.
+- [ ] An expired/missing cache still uses `useScrollRestorationLoadMore` until the coordinate is reachable.
+- [ ] Filter and order variants do not share cached rows.
+- [ ] My Issues and project Issues have independent cache namespaces.
+- [ ] Project Plans uses an independent cache namespace and retains its URL-backed filter across remounts.
+- [ ] A workspace banner, including a wrapped/narrow variant, does not change the restored row offset.
+- [ ] The dashboard header and banner do not scroll with route content.
+- [ ] `window.scrollY` remains `0` throughout the dashboard flow.
+- [ ] Plan detail does not create a second route-level vertical scroller.
+- [ ] SQL Editor behavior is unchanged and untested by this delivery.
diff --git a/frontend/src/react/components/IssueTable.test.tsx b/frontend/src/react/components/IssueTable.test.tsx
index a5826951ff..cedbd1547b 100644
--- a/frontend/src/react/components/IssueTable.test.tsx
+++ b/frontend/src/react/components/IssueTable.test.tsx
@@ -1,7 +1,12 @@
+import { create } from "@bufbuild/protobuf";
import { fireEvent, render, screen } from "@testing-library/react";
import { describe, expect, test, vi } from "vitest";
+import {
+ IssueSchema,
+ IssueStatus,
+} from "@/types/proto-es/v1/issue_service_pb";
import { emptySearchParams } from "./AdvancedSearch";
-import { IssueSearchBar, PresetButtons } from "./IssueTable";
+import { IssueListItem, IssueSearchBar, PresetButtons } from "./IssueTable";
vi.mock("@/react/hooks/useAppState", () => ({
useCurrentUser: () => ({ email: "[email protected]" }),
@@ -101,3 +106,56 @@ describe("PresetButtons", () => {
expect(onParamsChange).toHaveBeenCalled();
});
});
+
+describe("IssueListItem", () => {
+ const issue = create(IssueSchema, {
+ name: "projects/foo/issues/1",
+ title: "Issue 1",
+ creator: "users/[email protected]",
+ status: IssueStatus.OPEN,
+ });
+
+ test("marks normal row and title-link navigation for restoration", () => {
+ const onOpenIssue = vi.fn();
+ const { rerender } = render(
+ <IssueListItem
+ issue={issue}
+ selected={false}
+ onToggleSelection={vi.fn()}
+ onOpenIssue={onOpenIssue}
+ />
+ );
+
+ fireEvent.click(screen.getByTestId("issue-list-item"));
+ expect(onOpenIssue).toHaveBeenCalledOnce();
+
+ onOpenIssue.mockClear();
+ rerender(
+ <IssueListItem
+ issue={issue}
+ selected={false}
+ onToggleSelection={vi.fn()}
+ onOpenIssue={onOpenIssue}
+ />
+ );
+ fireEvent.click(screen.getByRole("link", { name: "Issue 1" }));
+ expect(onOpenIssue).toHaveBeenCalledOnce();
+ });
+
+ test("does not mark modified title-link navigation", () => {
+ const onOpenIssue = vi.fn();
+ render(
+ <IssueListItem
+ issue={issue}
+ selected={false}
+ onToggleSelection={vi.fn()}
+ onOpenIssue={onOpenIssue}
+ />
+ );
+
+ fireEvent.click(screen.getByRole("link", { name: "Issue 1" }), {
+ ctrlKey: true,
+ });
+ expect(onOpenIssue).not.toHaveBeenCalled();
+ });
+});
diff --git a/frontend/src/react/components/IssueTable.tsx b/frontend/src/react/components/IssueTable.tsx
index 64a9c7d591..3b2b1a32d5 100644
--- a/frontend/src/react/components/IssueTable.tsx
+++ b/frontend/src/react/components/IssueTable.tsx
@@ -330,6 +330,7 @@ export function IssueListPanel({
issues,
selectedNames,
onToggleSelection,
+ onOpenIssue,
showProject,
}: {
params: SearchParams;
@@ -338,6 +339,7 @@ export function IssueListPanel({
issues: Issue[];
selectedNames: Set<string>;
onToggleSelection: (name: string) => void;
+ onOpenIssue?: () => void;
showProject?: boolean;
}) {
const { t } = useTranslation();
@@ -360,6 +362,7 @@ export function IssueListPanel({
issue={issue}
selected={selectedNames.has(issue.name)}
onToggleSelection={onToggleSelection}
+ onOpenIssue={onOpenIssue}
highlightText={params.query}
showProject={showProject}
/>
@@ -621,6 +624,7 @@ export const IssueListItem = memo(function IssueListItem({
issue,
selected,
onToggleSelection,
+ onOpenIssue,
highlightText = "",
showProject = false,
}: {
@@ -628,6 +632,7 @@ export const IssueListItem = memo(function IssueListItem({
selected: boolean;
/** Called with the issue's name; pass a stable callback from the parent. */
onToggleSelection: (name: string) => void;
+ onOpenIssue?: () => void;
highlightText?: string;
showProject?: boolean;
}) {
@@ -656,10 +661,26 @@ export const IssueListItem = memo(function IssueListItem({
if (e.ctrlKey || e.metaKey) {
window.open(issueUrl, "_blank");
} else {
+ onOpenIssue?.();
router.push(issueUrl);
}
},
- [issueUrl]
+ [issueUrl, onOpenIssue]
+ );
+ const onTitleClick = useCallback(
+ (e: React.MouseEvent) => {
+ e.stopPropagation();
+ if (
+ !e.metaKey &&
+ !e.ctrlKey &&
+ !e.shiftKey &&
+ !e.altKey &&
+ e.button === 0
+ ) {
+ onOpenIssue?.();
+ }
+ },
+ [onOpenIssue]
);
// Labels
@@ -688,6 +709,8 @@ export const IssueListItem = memo(function IssueListItem({
return (
<div
data-slot="issue-list-item"
+ data-testid="issue-list-item"
+ data-scroll-restoration-anchor={issue.name}
className="flex items-start gap-x-2 px-4 py-3 cursor-pointer border-b border-block-border transition-colors last:border-b-0 hover:bg-control-bg/60"
onClick={onRowClick}
>
@@ -715,7 +738,7 @@ export const IssueListItem = memo(function IssueListItem({
<RouterLink
to={issueUrl}
className="font-medium text-main text-base hover:underline min-w-0 block"
- onClick={(e) => e.stopPropagation()}
+ onClick={onTitleClick}
>
<EllipsisText text={issue.title}>
<HighlightLabelText
@@ -728,7 +751,7 @@ export const IssueListItem = memo(function IssueListItem({
<RouterLink
to={issueUrl}
className="font-medium text-base truncate hover:underline italic text-control-placeholder"
- onClick={(e) => e.stopPropagation()}
+ onClick={onTitleClick}
>
{t("common.untitled")}
</RouterLink>
diff --git a/frontend/src/react/components/database/DatabaseTable.tsx b/frontend/src/react/components/database/DatabaseTable.tsx
index 286e47c9d5..2ccde3d579 100644
--- a/frontend/src/react/components/database/DatabaseTable.tsx
+++ b/frontend/src/react/components/database/DatabaseTable.tsx
@@ -166,6 +166,7 @@ export function DatabaseTable({
dataList: databases,
hasMore: !selectOnRowClick && hasMore,
isFetchingMore,
+ isLoading: loading,
loadMore,
});
diff --git a/frontend/src/react/components/ui/column-resize-handle.tsx b/frontend/src/react/components/ui/column-resize-handle.tsx
index 4f86a578c6..fe782bf149 100644
--- a/frontend/src/react/components/ui/column-resize-handle.tsx
+++ b/frontend/src/react/components/ui/column-resize-handle.tsx
@@ -16,13 +16,13 @@ export function ColumnResizeHandle({
return (
<div
className={cn(
- "group absolute right-[-6px] top-0 z-10 h-full w-3 cursor-col-resize",
+ "group absolute right-0 top-0 z-10 h-full w-3 cursor-col-resize",
className
)}
onMouseDown={onMouseDown}
onClick={(e) => e.stopPropagation()}
>
- <span className="pointer-events-none absolute left-1/2 top-1/4 h-1/2 w-0.5 -translate-x-1/2 rounded-full bg-control-bg-hover transition-colors group-hover:bg-accent/60 group-active:bg-accent" />
+ <span className="pointer-events-none absolute right-0 top-1/4 h-1/2 w-0.5 rounded-full bg-control-bg-hover transition-colors group-hover:bg-accent/60 group-active:bg-accent" />
</div>
);
}
diff --git a/frontend/src/react/components/ui/table.test.tsx b/frontend/src/react/components/ui/table.test.tsx
index d1d7581984..d631cca54c 100644
--- a/frontend/src/react/components/ui/table.test.tsx
+++ b/frontend/src/react/components/ui/table.test.tsx
@@ -51,12 +51,14 @@ describe("table primitives", () => {
expect(content.props.children).toBe("No data");
});
- test("ColumnResizeHandle uses a raised 12px hitbox around a 2px visual bar", () => {
+ test("ColumnResizeHandle keeps its hitbox inside the header edge", () => {
const element = ColumnResizeHandle({ onMouseDown: () => {} });
- expect(element.props.className).toContain("right-[-6px]");
+ expect(element.props.className).toContain("right-0");
+ expect(element.props.className).not.toContain("right-[-6px]");
expect(element.props.className).toContain("w-3");
expect(element.props.className).toContain("z-10");
+ expect(element.props.children.props.className).toContain("right-0");
expect(element.props.children.props.className).toContain("w-0.5");
});
});
diff --git a/frontend/src/react/hooks/pagedDataCache.test.ts b/frontend/src/react/hooks/pagedDataCache.test.ts
new file mode 100644
index 0000000000..5d82bff4f7
--- /dev/null
+++ b/frontend/src/react/hooks/pagedDataCache.test.ts
@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import {
+ clearPagedDataCache,
+ invalidatePagedDataCacheScope,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "./pagedDataCache";
+
+describe("pagedDataCache", () => {
+ afterEach(() => {
+ clearPagedDataCache();
+ vi.useRealTimers();
+ });
+
+ test("returns an isolated copy of a cached view", () => {
+ writePagedDataCache("issues", {
+ dataList: [{ name: "issues/1" }],
+ hasMore: true,
+ nextPageToken: "page-2",
+ });
+
+ const first = readPagedDataCache<{ name: string }>("issues");
+ first?.dataList.push({ name: "issues/local-only" });
+
+ expect(readPagedDataCache("issues")).toEqual({
+ dataList: [{ name: "issues/1" }],
+ hasMore: true,
+ nextPageToken: "page-2",
+ });
+ });
+
+ test("expires five minutes after write even when reads refresh LRU order", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-20T00:00:00Z"));
+ writePagedDataCache("issues", {
+ dataList: [{ name: "issues/1" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+
+ vi.advanceTimersByTime(4 * 60 * 1000);
+ expect(readPagedDataCache("issues")).toBeDefined();
+
+ vi.advanceTimersByTime(60 * 1000 + 1);
+
+ expect(readPagedDataCache("issues")).toBeUndefined();
+ });
+
+ test("evicts the least recently used view after twenty entries", () => {
+ for (let i = 0; i < 20; i++) {
+ writePagedDataCache(`issues-${i}`, {
+ dataList: [{ name: `issues/${i}` }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+ }
+ expect(readPagedDataCache("issues-0")).toBeDefined();
+
+ writePagedDataCache("issues-20", {
+ dataList: [{ name: "issues/20" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+
+ expect(readPagedDataCache("issues-1")).toBeUndefined();
+ expect(readPagedDataCache("issues-0")).toBeDefined();
+ });
+
+ test("invalidates only snapshots in the requested scope", () => {
+ writePagedDataCache(
+ "project-a-active-plans",
+ {
+ dataList: [{ name: "projects/a/plans/1" }],
+ hasMore: false,
+ nextPageToken: "",
+ },
+ "project-a-plans"
+ );
+ writePagedDataCache(
+ "project-a-closed-plans",
+ {
+ dataList: [{ name: "projects/a/plans/2" }],
+ hasMore: false,
+ nextPageToken: "",
+ },
+ "project-a-plans"
+ );
+ writePagedDataCache(
+ "project-a-issues",
+ {
+ dataList: [{ name: "projects/a/issues/1" }],
+ hasMore: false,
+ nextPageToken: "",
+ },
+ "project-a-issues"
+ );
+
+ invalidatePagedDataCacheScope("project-a-plans");
+
+ expect(readPagedDataCache("project-a-active-plans")).toBeUndefined();
+ expect(readPagedDataCache("project-a-closed-plans")).toBeUndefined();
+ expect(readPagedDataCache("project-a-issues")).toBeDefined();
+ });
+});
diff --git a/frontend/src/react/hooks/pagedDataCache.ts b/frontend/src/react/hooks/pagedDataCache.ts
new file mode 100644
index 0000000000..845e6179a6
--- /dev/null
+++ b/frontend/src/react/hooks/pagedDataCache.ts
@@ -0,0 +1,77 @@
+export type PagedDataCacheSnapshot<T> = {
+ dataList: T[];
+ hasMore: boolean;
+ nextPageToken: string;
+};
+
+type StoredSnapshot<T> = PagedDataCacheSnapshot<T> & {
+ cachedAt: number;
+ cacheScope?: string;
+};
+
+const MAX_ENTRIES = 20;
+const MAX_AGE_MS = 5 * 60 * 1000;
+const cache = new Map<string, StoredSnapshot<unknown>>();
+
+// List arrays are copied so consumers cannot change membership/order in the
+// stored view. Items remain shared under the app's immutable proto convention.
+const cloneSnapshot = <T>(
+ snapshot: PagedDataCacheSnapshot<T>
+): PagedDataCacheSnapshot<T> => ({
+ dataList: [...snapshot.dataList],
+ hasMore: snapshot.hasMore,
+ nextPageToken: snapshot.nextPageToken,
+});
+
+export function readPagedDataCache<T>(
+ key: string | undefined
+): PagedDataCacheSnapshot<T> | undefined {
+ if (!key) return undefined;
+ const stored = cache.get(key) as StoredSnapshot<T> | undefined;
+ if (!stored) return undefined;
+ if (Date.now() - stored.cachedAt > MAX_AGE_MS) {
+ cache.delete(key);
+ return undefined;
+ }
+
+ // Refresh Map insertion order for LRU eviction without extending expiry.
+ cache.delete(key);
+ cache.set(key, stored as StoredSnapshot<unknown>);
+ return cloneSnapshot(stored);
+}
+
+export function writePagedDataCache<T>(
+ key: string | undefined,
+ snapshot: PagedDataCacheSnapshot<T>,
+ cacheScope?: string
+): void {
+ if (!key) return;
+ cache.delete(key);
+ cache.set(key, {
+ ...cloneSnapshot(snapshot),
+ cachedAt: Date.now(),
+ cacheScope,
+ } as StoredSnapshot<unknown>);
+
+ while (cache.size > MAX_ENTRIES) {
+ const oldestKey = cache.keys().next().value as string | undefined;
+ if (!oldestKey) break;
+ cache.delete(oldestKey);
+ }
+}
+
+export function deletePagedDataCache(key: string | undefined): void {
+ if (key) cache.delete(key);
+}
+
+export function invalidatePagedDataCacheScope(scope: string): void {
+ for (const [key, snapshot] of cache) {
+ if (snapshot.cacheScope === scope) {
+ cache.delete(key);
+ }
+ }
+}
+
+export function clearPagedDataCache(): void {
+ cache.clear();
+}
diff --git a/frontend/src/react/hooks/usePagedData.test.tsx b/frontend/src/react/hooks/usePagedData.test.tsx
index e14c46d93e..9a6a455560 100644
--- a/frontend/src/react/hooks/usePagedData.test.tsx
+++ b/frontend/src/react/hooks/usePagedData.test.tsx
@@ -1,11 +1,19 @@
-import { act } from "react";
+import { act, StrictMode } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, describe, expect, test, vi } from "vitest";
+import {
+ clearPagedDataCache,
+ invalidatePagedDataCacheScope,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "./pagedDataCache";
import { PagedTableFooter, usePagedData } from "./usePagedData";
+const pageSizeState = vi.hoisted(() => ({ value: 50 }));
+
vi.mock("@/react/hooks/useSessionPageSize", () => ({
getPageSizeOptions: () => [50, 100],
- useSessionPageSize: () => [50, vi.fn()],
+ useSessionPageSize: () => [pageSizeState.value, vi.fn()],
}));
(
@@ -36,13 +44,46 @@ function Harness({ fetchList }: { fetchList: FetchList }) {
return <div data-state="data">{paged.dataList[0].name}</div>;
}
+function CacheHarness({
+ cacheKey,
+ cacheScope,
+ cacheRestoreToken,
+ fetchList,
+}: {
+ cacheKey: string;
+ cacheScope?: string;
+ cacheRestoreToken?: string;
+ fetchList: FetchList;
+}) {
+ const paged = usePagedData<Item>({
+ sessionKey: "test-cached-paged-data",
+ cacheKey,
+ cacheScope,
+ cacheRestoreToken,
+ fetchList,
+ });
+
+ return (
+ <div>
+ <div data-state={paged.isLoading ? "loading" : "ready"}>
+ {paged.dataList.map((item) => item.name).join(",")}
+ </div>
+ <button type="button" onClick={paged.loadMore}>
+ load more
+ </button>
+ </div>
+ );
+}
+
describe("usePagedData", () => {
let root: Root | undefined;
let container: HTMLDivElement | undefined;
afterEach(() => {
+ pageSizeState.value = 50;
vi.useRealTimers();
sessionStorage.clear();
+ clearPagedDataCache();
act(() => {
root?.unmount();
});
@@ -88,6 +129,326 @@ describe("usePagedData", () => {
"items/1"
);
});
+
+ test("restores every loaded page and cached token for history POP", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi
+ .fn<FetchList>()
+ .mockResolvedValueOnce({
+ list: [{ name: "items/1" }],
+ nextPageToken: "page-2",
+ })
+ .mockResolvedValueOnce({
+ list: [{ name: "items/2" }],
+ nextPageToken: "page-3",
+ });
+
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+ await act(async () => {
+ container!.querySelector("button")?.click();
+ await Promise.resolve();
+ });
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/1,items/2"
+ );
+
+ act(() => root?.unmount());
+ root = createRoot(container);
+ const resumedFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/3" }],
+ }));
+
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={resumedFetch}
+ />
+ );
+ });
+ expect(
+ container.querySelector("[data-state]")?.getAttribute("data-state")
+ ).toBe("ready");
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/1,items/2"
+ );
+ expect(resumedFetch).not.toHaveBeenCalled();
+
+ await act(async () => {
+ container!.querySelector("button")?.click();
+ await Promise.resolve();
+ });
+ expect(resumedFetch).toHaveBeenCalledWith({
+ pageSize: 50,
+ pageToken: "page-3",
+ });
+ });
+
+ test("does not refresh a hydrated history view during Strict Mode effect replay", async () => {
+ vi.useFakeTimers();
+ writePagedDataCache("issues:page-size=50", {
+ dataList: [{ name: "items/cached" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const fetchList = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/refreshed" }],
+ }));
+
+ await act(async () => {
+ root!.render(
+ <StrictMode>
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={fetchList}
+ />
+ </StrictMode>
+ );
+ await Promise.resolve();
+ });
+
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/cached"
+ );
+ expect(fetchList).not.toHaveBeenCalled();
+
+ await act(async () => {
+ vi.advanceTimersByTime(300);
+ await Promise.resolve();
+ });
+
+ expect(fetchList).not.toHaveBeenCalled();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/cached"
+ );
+ });
+
+ test("fetches current data for a push-style remount", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/cached" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+
+ act(() => root?.unmount());
+ root = createRoot(container);
+ const currentFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/current" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={currentFetch} />
+ );
+ await Promise.resolve();
+ });
+
+ expect(currentFetch).toHaveBeenCalledOnce();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/current"
+ );
+ });
+
+ test("persists the cache scope used for later invalidation", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const fetchList = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/1" }],
+ }));
+
+ await act(async () => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheScope="project-a-issues"
+ fetchList={fetchList}
+ />
+ );
+ await Promise.resolve();
+ });
+ expect(readPagedDataCache("issues:page-size=50")).toBeDefined();
+
+ invalidatePagedDataCacheScope("project-a-issues");
+
+ expect(readPagedDataCache("issues:page-size=50")).toBeUndefined();
+ });
+
+ test("restores an entry again after the mounted page visits another view", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const fetchList = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/entry-1" }],
+ }));
+
+ await act(async () => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={fetchList}
+ />
+ );
+ await Promise.resolve();
+ });
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/entry-1"
+ );
+
+ act(() => {
+ root!.render(<CacheHarness cacheKey="plans" fetchList={fetchList} />);
+ });
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={fetchList}
+ />
+ );
+ });
+
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/entry-1"
+ );
+ expect(fetchList).toHaveBeenCalledOnce();
+ });
+
+ test("consumes cache restoration once per history entry", async () => {
+ vi.useFakeTimers();
+ writePagedDataCache("issues:page-size=50", {
+ dataList: [{ name: "items/cached-50" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+ writePagedDataCache("issues:page-size=100", {
+ dataList: [{ name: "items/cached-100" }],
+ hasMore: false,
+ nextPageToken: "",
+ });
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const fetchList = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/current-100" }],
+ }));
+
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={fetchList}
+ />
+ );
+ });
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/cached-50"
+ );
+
+ pageSizeState.value = 100;
+ await act(async () => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={fetchList}
+ />
+ );
+ await Promise.resolve();
+ });
+ expect(container.querySelector("[data-state]")?.textContent).not.toBe(
+ "items/cached-100"
+ );
+
+ await act(async () => {
+ vi.advanceTimersByTime(300);
+ await Promise.resolve();
+ });
+ expect(fetchList).toHaveBeenCalledWith({ pageSize: 100, pageToken: "" });
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/current-100"
+ );
+ });
+
+ test("does not extend absolute expiry when a history view is hydrated", async () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-20T00:00:00Z"));
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ const initialFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/cached" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness cacheKey="issues" fetchList={initialFetch} />
+ );
+ await Promise.resolve();
+ });
+ act(() => root?.unmount());
+
+ act(() => vi.advanceTimersByTime(4 * 60 * 1000));
+ root = createRoot(container);
+ const warmFetch = vi.fn<FetchList>(async () => ({ list: [] }));
+ act(() => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={warmFetch}
+ />
+ );
+ });
+ expect(warmFetch).not.toHaveBeenCalled();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/cached"
+ );
+ act(() => root?.unmount());
+
+ act(() => vi.advanceTimersByTime(60 * 1000 + 1));
+ root = createRoot(container);
+ const expiredFetch = vi.fn<FetchList>(async () => ({
+ list: [{ name: "items/current" }],
+ }));
+ await act(async () => {
+ root!.render(
+ <CacheHarness
+ cacheKey="issues"
+ cacheRestoreToken="entry-1"
+ fetchList={expiredFetch}
+ />
+ );
+ await Promise.resolve();
+ });
+
+ expect(expiredFetch).toHaveBeenCalledOnce();
+ expect(container.querySelector("[data-state]")?.textContent).toBe(
+ "items/current"
+ );
+ });
});
describe("PagedTableFooter", () => {
diff --git a/frontend/src/react/hooks/usePagedData.tsx b/frontend/src/react/hooks/usePagedData.tsx
index a7a6725ec3..1fd0874569 100644
--- a/frontend/src/react/hooks/usePagedData.tsx
+++ b/frontend/src/react/hooks/usePagedData.tsx
@@ -1,4 +1,11 @@
-import { useCallback, useEffect, useReducer, useRef } from "react";
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useReducer,
+ useRef,
+ useState,
+} from "react";
import { useTranslation } from "react-i18next";
import { Button } from "@/react/components/ui/button";
import {
@@ -12,6 +19,12 @@ import {
getPageSizeOptions,
useSessionPageSize,
} from "@/react/hooks/useSessionPageSize";
+import {
+ deletePagedDataCache,
+ type PagedDataCacheSnapshot,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "./pagedDataCache";
// ============================================================
// usePagedData hook
@@ -34,29 +47,41 @@ export type PagedDataResult<T> = {
type FetchMode = "refresh" | "append";
type PagedDataState<T> = {
+ cacheKey?: string;
+ cacheWriteState: "clean" | "dirty";
dataList: T[];
status: "idle" | "loading" | "ready" | "loadingMore";
hasMore: boolean;
};
type PagedDataAction<T> =
- | { type: "fetch-start"; mode: FetchMode }
+ | {
+ type: "restore-cache";
+ cacheKey?: string;
+ snapshot?: PagedDataCacheSnapshot<T>;
+ }
+ | { type: "fetch-start"; mode: FetchMode; cacheKey?: string }
| {
type: "fetch-success";
mode: FetchMode;
+ cacheKey?: string;
list: T[];
hasMore: boolean;
}
| { type: "fetch-error" }
| { type: "update-cache"; items: T[] }
- | { type: "remove-cache"; item: T };
+ | { type: "remove-cache"; item: T }
+ | { type: "cache-persisted"; cacheKey?: string };
-const initialPagedDataState = <
- T extends { name: string },
->(): PagedDataState<T> => ({
- dataList: [],
- status: "idle",
- hasMore: false,
+const stateFromSnapshot = <T extends { name: string }>(
+ cacheKey: string | undefined,
+ snapshot?: PagedDataCacheSnapshot<T>
+): PagedDataState<T> => ({
+ cacheKey,
+ cacheWriteState: "clean",
+ dataList: snapshot?.dataList ?? [],
+ status: snapshot ? "ready" : "idle",
+ hasMore: snapshot?.hasMore ?? false,
});
const pagedDataReducer = <T extends { name: string }>(
@@ -64,13 +89,18 @@ const pagedDataReducer = <T extends { name: string }>(
action: PagedDataAction<T>
): PagedDataState<T> => {
switch (action.type) {
+ case "restore-cache":
+ return stateFromSnapshot(action.cacheKey, action.snapshot);
case "fetch-start":
return {
...state,
+ cacheKey: action.cacheKey,
status: action.mode === "refresh" ? "loading" : "loadingMore",
};
case "fetch-success":
return {
+ cacheKey: action.cacheKey,
+ cacheWriteState: "dirty",
dataList:
action.mode === "refresh"
? action.list
@@ -81,6 +111,7 @@ const pagedDataReducer = <T extends { name: string }>(
case "fetch-error":
return {
...state,
+ cacheWriteState: "clean",
status: "ready",
};
case "update-cache": {
@@ -95,25 +126,37 @@ const pagedDataReducer = <T extends { name: string }>(
}
return {
...state,
+ cacheWriteState: "dirty",
dataList,
};
}
case "remove-cache":
return {
...state,
+ cacheWriteState: "dirty",
dataList: state.dataList.filter(
(data) => data.name !== action.item.name
),
};
+ case "cache-persisted":
+ return action.cacheKey === state.cacheKey
+ ? { ...state, cacheWriteState: "clean" }
+ : state;
}
};
export function usePagedData<T extends { name: string }>({
sessionKey,
+ cacheKey,
+ cacheScope,
+ cacheRestoreToken,
fetchList,
enabled = true,
}: {
sessionKey: string;
+ cacheKey?: string;
+ cacheScope?: string;
+ cacheRestoreToken?: string;
fetchList: (params: {
pageSize: number;
pageToken: string;
@@ -123,15 +166,32 @@ export function usePagedData<T extends { name: string }>({
const [pageSize, setPageSize] = useSessionPageSize(sessionKey);
const pageSizeOptions = getPageSizeOptions();
+ const resolvedCacheKey = cacheKey
+ ? `${cacheKey}:page-size=${pageSize}`
+ : undefined;
+ const [initialCache] = useState(() => {
+ const snapshot = cacheRestoreToken
+ ? readPagedDataCache<T>(resolvedCacheKey)
+ : undefined;
+ return {
+ key: resolvedCacheKey,
+ cacheRestoreToken,
+ snapshot,
+ };
+ });
const [state, dispatch] = useReducer(
pagedDataReducer<T>,
- undefined,
- initialPagedDataState<T>
+ initialCache,
+ ({ key, snapshot }) => stateFromSnapshot(key, snapshot)
);
const abortRef = useRef<AbortController | null>(null);
const fetchIdRef = useRef(0);
- const nextPageTokenRef = useRef("");
+ const nextPageTokenRef = useRef(initialCache.snapshot?.nextPageToken ?? "");
+ const activeCacheKeyRef = useRef(initialCache.key);
+ const activeCacheRestoreTokenRef = useRef(initialCache.cacheRestoreToken);
+ const consumedCacheRestoreTokenRef = useRef(initialCache.cacheRestoreToken);
+ const skipNextFetchRef = useRef(Boolean(initialCache.snapshot));
const doFetch = useCallback(
async (isRefresh: boolean) => {
@@ -141,7 +201,8 @@ export function usePagedData<T extends { name: string }>({
abortRef.current = controller;
const mode: FetchMode = isRefresh ? "refresh" : "append";
- dispatch({ type: "fetch-start", mode });
+ const activeCacheKey = activeCacheKeyRef.current;
+ dispatch({ type: "fetch-start", mode, cacheKey: activeCacheKey });
try {
const token = isRefresh ? "" : nextPageTokenRef.current;
@@ -152,6 +213,7 @@ export function usePagedData<T extends { name: string }>({
dispatch({
type: "fetch-success",
mode,
+ cacheKey: activeCacheKey,
list: result.list,
hasMore: Boolean(result.nextPageToken),
});
@@ -173,6 +235,7 @@ export function usePagedData<T extends { name: string }>({
}, [doFetch, state.hasMore, state.status]);
const refresh = useCallback(() => {
+ deletePagedDataCache(activeCacheKeyRef.current);
doFetch(true);
}, [doFetch]);
@@ -184,10 +247,67 @@ export function usePagedData<T extends { name: string }>({
dispatch({ type: "remove-cache", item });
}, []);
+ useLayoutEffect(() => {
+ if (
+ activeCacheKeyRef.current === resolvedCacheKey &&
+ activeCacheRestoreTokenRef.current === cacheRestoreToken
+ ) {
+ return;
+ }
+ fetchIdRef.current++;
+ abortRef.current?.abort();
+ activeCacheKeyRef.current = resolvedCacheKey;
+ activeCacheRestoreTokenRef.current = cacheRestoreToken;
+
+ const shouldRestore =
+ cacheRestoreToken !== undefined &&
+ consumedCacheRestoreTokenRef.current !== cacheRestoreToken;
+ consumedCacheRestoreTokenRef.current = cacheRestoreToken;
+ const snapshot = shouldRestore
+ ? readPagedDataCache<T>(resolvedCacheKey)
+ : undefined;
+ nextPageTokenRef.current = snapshot?.nextPageToken ?? "";
+ skipNextFetchRef.current = Boolean(snapshot);
+ dispatch({
+ type: "restore-cache",
+ cacheKey: resolvedCacheKey,
+ snapshot,
+ });
+ }, [cacheRestoreToken, resolvedCacheKey]);
+
+ useEffect(() => {
+ if (
+ !state.cacheKey ||
+ state.cacheWriteState !== "dirty" ||
+ state.status !== "ready" ||
+ state.cacheKey !== resolvedCacheKey
+ ) {
+ return;
+ }
+ writePagedDataCache(
+ state.cacheKey,
+ {
+ dataList: state.dataList,
+ hasMore: state.hasMore,
+ nextPageToken: nextPageTokenRef.current,
+ },
+ cacheScope
+ );
+ dispatch({ type: "cache-persisted", cacheKey: state.cacheKey });
+ }, [cacheScope, resolvedCacheKey, state]);
+
// Fetch on mount and when fetchList/pageSize changes (handles search text reactivity)
const isFirstLoad = useRef(true);
useEffect(() => {
if (!enabled) return;
+ if (skipNextFetchRef.current) {
+ isFirstLoad.current = false;
+ // Keep the guard through React Strict Mode's immediate effect replay.
+ const timer = window.setTimeout(() => {
+ skipNextFetchRef.current = false;
+ });
+ return () => window.clearTimeout(timer);
+ }
if (isFirstLoad.current) {
isFirstLoad.current = false;
doFetch(true);
@@ -195,10 +315,14 @@ export function usePagedData<T extends { name: string }>({
}
fetchIdRef.current++;
abortRef.current?.abort();
- dispatch({ type: "fetch-start", mode: "refresh" });
+ dispatch({
+ type: "fetch-start",
+ mode: "refresh",
+ cacheKey: activeCacheKeyRef.current,
+ });
const timer = setTimeout(() => doFetch(true), 300);
return () => clearTimeout(timer);
- }, [doFetch, enabled]);
+ }, [cacheRestoreToken, doFetch, enabled, resolvedCacheKey]);
useEffect(() => {
return () => {
diff --git a/frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx b/frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx
index b7a71847fa..d85e386d18 100644
--- a/frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx
+++ b/frontend/src/react/pages/project/ProjectIssueDashboardPage.tsx
@@ -1,5 +1,6 @@
import { useCallback, useEffect, useMemo, useState } from "react";
import { useTranslation } from "react-i18next";
+import { useLocation } from "react-router";
import type { SearchParams } from "@/react/components/AdvancedSearch";
import {
BatchActionBar,
@@ -18,7 +19,11 @@ import { useCurrentUser } from "@/react/hooks/useAppState";
import { PagedTableFooter, usePagedData } from "@/react/hooks/usePagedData";
import { useURLSearchParam } from "@/react/hooks/useURLSearchParam";
import { refreshIssueList } from "@/react/lib/issue/issueListRefresh";
-import { useScrollRestorationLoadMore } from "@/react/router/NavigationScrollRestoration";
+import {
+ markScrollRestorationEntry,
+ useScrollRestorationKey,
+ useScrollRestorationLoadMore,
+} from "@/react/router/NavigationScrollRestoration";
import { useAppStore } from "@/react/stores/app";
import { projectNamePrefix } from "@/store/modules/v1/common";
import { ApprovalStatus } from "@/types/proto-es/v1/common_pb";
@@ -31,6 +36,7 @@ import {
mergeSearchParams,
type SearchScope as VueSearchScope,
} from "@/utils";
+import { projectIssuesPagedDataCacheScope } from "./pagedDataCacheScope";
const serializeSearchParams = (params: SearchParams): string =>
buildSearchTextBySearchParams({
@@ -44,6 +50,8 @@ export function ProjectIssueDashboardPage({
projectId: string;
}) {
const { t } = useTranslation();
+ const location = useLocation();
+ const scrollRestorationKey = useScrollRestorationKey();
const batchGetOrFetchUsers = useAppStore(
(state) => state.batchGetOrFetchUsers
);
@@ -97,6 +105,16 @@ export function ProjectIssueDashboardPage({
param: "order",
defaultValue: "",
});
+ const viewCacheKey = useMemo(
+ () =>
+ JSON.stringify([
+ "project-issues",
+ projectName,
+ serializeSearchParams(searchParams),
+ orderBy,
+ ]),
+ [orderBy, projectName, searchParams]
+ );
// Issue filter
const issueFilter = useMemo(() => {
@@ -121,6 +139,9 @@ export function ProjectIssueDashboardPage({
const paged = usePagedData<Issue>({
sessionKey: "bb.issue-table.project-issues",
+ cacheKey: viewCacheKey,
+ cacheScope: projectIssuesPagedDataCacheScope(projectId),
+ cacheRestoreToken: scrollRestorationKey,
fetchList: fetchIssueList,
});
useScrollRestorationLoadMore(paged);
@@ -162,6 +183,10 @@ export function ProjectIssueDashboardPage({
return next;
});
}, []);
+ const handleOpenIssue = useCallback(
+ () => markScrollRestorationEntry(location),
+ [location]
+ );
const toggleSelectAll = useCallback(() => {
setSelectedNames((prev) => {
@@ -206,6 +231,7 @@ export function ProjectIssueDashboardPage({
issues={paged.dataList}
selectedNames={selectedNames}
onToggleSelection={toggleSelection}
+ onOpenIssue={handleOpenIssue}
/>
{paged.dataList.length > 0 && (
<ProjectPageFooter className="px-2">
diff --git a/frontend/src/react/pages/project/ProjectPlanDashboardPage.test.tsx b/frontend/src/react/pages/project/ProjectPlanDashboardPage.test.tsx
new file mode 100644
index 0000000000..0c28b8dd87
--- /dev/null
+++ b/frontend/src/react/pages/project/ProjectPlanDashboardPage.test.tsx
@@ -0,0 +1,288 @@
+import { act, createElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { MemoryRouter } from "react-router";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { State } from "@/types/proto-es/v1/common_pb";
+import type { Plan } from "@/types/proto-es/v1/plan_service_pb";
+import { ProjectPlanDashboardPage } from "./ProjectPlanDashboardPage";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const plan = {
+ name: "projects/foo/plans/1",
+ title: "Plan 1",
+ state: State.ACTIVE,
+ creator: "users/[email protected]",
+ issue: "",
+ hasRollout: false,
+ specs: [],
+ rolloutStageSummaries: [],
+} as unknown as Plan;
+
+const mocks = vi.hoisted(() => ({
+ batchGetOrFetchUsers: vi.fn(async () => []),
+ listUsers: vi.fn(async () => ({ users: [] })),
+ markScrollRestorationEntry: vi.fn(),
+ routerPush: vi.fn(),
+ scrollRestorationKey: undefined as string | undefined,
+ usePagedData: vi.fn(),
+}));
+
+vi.mock("react-i18next", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("react-i18next")>()),
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@/react/components/AdvancedSearch", () => ({
+ AdvancedSearch: () => createElement("div"),
+}));
+
+vi.mock("@/react/components/DatabaseGroupTable", () => ({
+ DatabaseGroupTable: () => null,
+}));
+
+vi.mock("@/react/components/database", () => ({
+ DatabaseTable: () => null,
+}));
+
+vi.mock("@/react/components/HumanizeTs", () => ({
+ HumanizeTs: () => createElement("span"),
+}));
+
+vi.mock("@/react/components/PermissionGuard", () => ({
+ PermissionGuard: ({ children }: { children: ReactNode }) => children,
+ usePermissionCheck: () => [true, false],
+}));
+
+vi.mock("@/react/components/ProjectPageLayout", () => ({
+ ProjectPageContent: ({ children }: { children: ReactNode }) =>
+ createElement("div", {}, children),
+ ProjectPageFooter: ({ children }: { children: ReactNode }) =>
+ createElement("footer", {}, children),
+ ProjectPageInfo: () => null,
+ ProjectPageLayout: ({ children }: { children: ReactNode }) =>
+ createElement("div", {}, children),
+}));
+
+vi.mock("@/react/components/TaskStatusIcon", () => ({
+ TaskStatusIcon: () => null,
+}));
+
+vi.mock("@/react/components/ui/badge", () => ({
+ Badge: ({ children }: { children: ReactNode }) =>
+ createElement("span", {}, children),
+}));
+
+vi.mock("@/react/components/ui/button", () => ({
+ Button: ({ children, ...props }: { children: ReactNode }) =>
+ createElement("button", props, children),
+}));
+
+vi.mock("@/react/components/ui/search-input", () => ({
+ SearchInput: () => createElement("input"),
+}));
+
+vi.mock("@/react/components/ui/sheet", () => ({
+ Sheet: ({ children }: { children: ReactNode }) =>
+ createElement("div", {}, children),
+ SheetBody: ({ children }: { children: ReactNode }) =>
+ createElement("div", {}, children),
+ SheetContent: ({ children }: { children: ReactNode }) =>
+ createElement("div", {}, children),
+ SheetFooter: ({ children }: { children: ReactNode }) =>
+ createElement("footer", {}, children),
+ SheetHeader: ({ children }: { children: ReactNode }) =>
+ createElement("header", {}, children),
+ SheetTitle: ({ children }: { children: ReactNode }) =>
+ createElement("h2", {}, children),
+}));
+
+vi.mock("@/react/components/ui/table", () => ({
+ Table: ({ children, ...props }: { children: ReactNode }) =>
+ createElement("table", props, children),
+ TableBody: ({ children }: { children: ReactNode }) =>
+ createElement("tbody", {}, children),
+ TableCell: ({ children }: { children?: ReactNode }) =>
+ createElement("td", {}, children),
+ TableHead: ({ children }: { children?: ReactNode }) =>
+ createElement("th", {}, children),
+ TableHeader: ({ children }: { children: ReactNode }) =>
+ createElement("thead", {}, children),
+ TableRow: ({ children, ...props }: { children?: ReactNode }) =>
+ createElement("tr", props, children),
+}));
+
+vi.mock("@/react/hooks/useAppState", () => ({
+ useCurrentUser: () => ({
+ email: "[email protected]",
+ name: "users/[email protected]",
+ }),
+}));
+
+vi.mock("@/react/hooks/useColumnWidths", () => ({
+ useColumnWidths: (columns: { defaultWidth: number }[]) => ({
+ widths: columns.map((column) => column.defaultWidth),
+ totalWidth: columns.reduce((sum, column) => sum + column.defaultWidth, 0),
+ onResizeStart: vi.fn(),
+ setWidths: vi.fn(),
+ }),
+}));
+
+vi.mock("@/react/hooks/useMediaQuery", () => ({
+ useMediaQuery: () => false,
+}));
+
+vi.mock("@/react/hooks/usePagedData", () => ({
+ PagedTableFooter: () => null,
+ usePagedData: mocks.usePagedData,
+}));
+
+vi.mock("@/react/hooks/useProjectByName", () => ({
+ useProjectByName: (name: string) => ({ name }),
+}));
+
+vi.mock("@/react/router", () => ({
+ router: {
+ push: mocks.routerPush,
+ resolve: () => ({ fullPath: "/projects/foo/plans/1" }),
+ },
+}));
+
+vi.mock("@/react/router/NavigationScrollRestoration", () => ({
+ markScrollRestorationEntry: mocks.markScrollRestorationEntry,
+ useScrollRestorationKey: () => mocks.scrollRestorationKey,
+ useScrollRestorationLoadMore: () => undefined,
+}));
+
+vi.mock("@/react/stores/app", () => {
+ const storeState = {
+ projectsByName: {},
+ listUsers: mocks.listUsers,
+ batchGetOrFetchUsers: mocks.batchGetOrFetchUsers,
+ environmentList: [],
+ getUserByIdentifier: () => undefined,
+ };
+ const useAppStore = (selector: (state: typeof storeState) => unknown) =>
+ selector(storeState);
+ return {
+ useAppStore: Object.assign(useAppStore, {
+ getState: () => ({
+ batchGetOrFetchDatabases: vi.fn(async () => []),
+ listPlans: vi.fn(async () => ({ plans: [], nextPageToken: "" })),
+ }),
+ }),
+ };
+});
+
+describe("ProjectPlanDashboardPage scroll restoration", () => {
+ let container: HTMLDivElement;
+ let root: Root;
+
+ beforeEach(() => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ mocks.usePagedData.mockReset();
+ mocks.scrollRestorationKey = undefined;
+ mocks.usePagedData.mockReturnValue({
+ dataList: [plan],
+ hasMore: true,
+ isFetchingMore: false,
+ isLoading: false,
+ loadMore: vi.fn(),
+ onPageSizeChange: vi.fn(),
+ pageSize: 50,
+ pageSizeOptions: [50, 100],
+ refresh: vi.fn(),
+ removeCache: vi.fn(),
+ updateCache: vi.fn(),
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+ vi.clearAllMocks();
+ });
+
+ test("does not restore paged data for a generic POP navigation", () => {
+ act(() => {
+ root.render(
+ <MemoryRouter
+ initialEntries={[
+ {
+ pathname: "/projects/foo/plans",
+ search: "?q=state%3ADELETED",
+ key: "plans-entry",
+ },
+ ]}
+ >
+ <ProjectPlanDashboardPage projectId="foo" />
+ </MemoryRouter>
+ );
+ });
+
+ const options = mocks.usePagedData.mock.lastCall?.[0] as
+ | { cacheKey?: string; cacheRestoreToken?: string }
+ | undefined;
+ expect(options?.cacheRestoreToken).toBeUndefined();
+ expect(options?.cacheKey).toContain("project-plans");
+ expect(options?.cacheKey).toContain("state:DELETED");
+ });
+
+ test("uses the item-click restoration key for paged data", () => {
+ mocks.scrollRestorationKey = "plans-entry";
+ act(() => {
+ root.render(
+ <MemoryRouter>
+ <ProjectPlanDashboardPage projectId="foo" />
+ </MemoryRouter>
+ );
+ });
+
+ const options = mocks.usePagedData.mock.lastCall?.[0] as
+ | { cacheRestoreToken?: string }
+ | undefined;
+ expect(options?.cacheRestoreToken).toBe("plans-entry");
+ });
+
+ test("marks the list entry before opening a Plan row", () => {
+ act(() => {
+ root.render(
+ <MemoryRouter>
+ <ProjectPlanDashboardPage projectId="foo" />
+ </MemoryRouter>
+ );
+ });
+
+ const row = container.querySelector<HTMLElement>(
+ '[data-testid="plan-list-item"]'
+ );
+ expect(row).not.toBeNull();
+ act(() => row?.click());
+
+ expect(mocks.markScrollRestorationEntry).toHaveBeenCalledOnce();
+ expect(mocks.routerPush).toHaveBeenCalledWith("/projects/foo/plans/1");
+ expect(
+ mocks.markScrollRestorationEntry.mock.invocationCallOrder[0]
+ ).toBeLessThan(mocks.routerPush.mock.invocationCallOrder[0]);
+ });
+
+ test("exposes every Plan row as a semantic restoration anchor", () => {
+ act(() => {
+ root.render(
+ <MemoryRouter>
+ <ProjectPlanDashboardPage projectId="foo" />
+ </MemoryRouter>
+ );
+ });
+
+ expect(
+ container.querySelector(
+ '[data-scroll-restoration-anchor="projects/foo/plans/1"]'
+ )
+ ).not.toBeNull();
+ });
+});
diff --git a/frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx b/frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx
index 9f3527f0fa..507bc93c4a 100644
--- a/frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx
+++ b/frontend/src/react/pages/project/ProjectPlanDashboardPage.tsx
@@ -7,6 +7,7 @@ import {
} from "lucide-react";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
+import { useLocation } from "react-router";
import { v4 as uuidv4 } from "uuid";
import {
AdvancedSearch,
@@ -53,6 +54,11 @@ import { useEscapeKey } from "@/react/hooks/useEscapeKey";
import { useMediaQuery } from "@/react/hooks/useMediaQuery";
import { PagedTableFooter, usePagedData } from "@/react/hooks/usePagedData";
import { useProjectByName } from "@/react/hooks/useProjectByName";
+import {
+ createAdvancedSearchParser,
+ serializeAdvancedSearch,
+ useURLSearchParam,
+} from "@/react/hooks/useURLSearchParam";
import { applyPlanTitleToQuery } from "@/react/lib/plan/title";
import { cn } from "@/react/lib/utils";
import { router } from "@/react/router";
@@ -60,7 +66,11 @@ import {
PROJECT_V1_ROUTE_PLAN_DETAIL,
PROJECT_V1_ROUTE_PLAN_DETAIL_SPEC_DETAIL,
} from "@/react/router/handles";
-import { useScrollRestorationLoadMore } from "@/react/router/NavigationScrollRestoration";
+import {
+ markScrollRestorationEntry,
+ useScrollRestorationKey,
+ useScrollRestorationLoadMore,
+} from "@/react/router/NavigationScrollRestoration";
import { useAppStore } from "@/react/stores/app";
import { buildPlanFindBySearchParams } from "@/react/stores/app/plan";
import { pushNotification } from "@/store";
@@ -90,6 +100,7 @@ import {
extractStageUID,
getStageStatusFromCounts,
} from "@/utils/v1/issue/rollout";
+import { projectPlansPagedDataCacheScope } from "./pagedDataCacheScope";
import { isReleaseBackedPlan } from "./plan-detail/utils/spec";
import {
getPlanDraftState,
@@ -101,9 +112,16 @@ import {
// Below Tailwind's `sm` breakpoint (640px) we switch the plan list and the
// database picker to their compact mobile layouts.
const MOBILE_MEDIA_QUERY = "(max-width: 639px)";
+const parsePlanSearchParams = createAdvancedSearchParser(["state", "creator"]);
export function ProjectPlanDashboardPage({ projectId }: { projectId: string }) {
const { t } = useTranslation();
+ const location = useLocation();
+ const scrollRestorationKey = useScrollRestorationKey();
+ const handleOpenPlan = useCallback(
+ () => markScrollRestorationEntry(location),
+ [location]
+ );
const projectsByName = useAppStore((s) => s.projectsByName);
const listUsers = useAppStore((state) => state.listUsers);
const batchGetOrFetchUsers = useAppStore(
@@ -118,25 +136,28 @@ export function ProjectPlanDashboardPage({ projectId }: { projectId: string }) {
const [showAddSpecDrawer, setShowAddSpecDrawer] = useState(false);
// Search
- const defaultSearchParams = useCallback(
- (): SearchParams => ({
+ const defaultSearchParams = useMemo<SearchParams>(
+ () => ({
query: "",
scopes: [{ id: "state", value: "ACTIVE" }],
}),
[]
);
-
- const [searchParams, setSearchParams] =
- useState<SearchParams>(defaultSearchParams);
-
- const didMountRef = useRef(false);
- useEffect(() => {
- if (!didMountRef.current) {
- didMountRef.current = true;
- return;
- }
- setSearchParams(defaultSearchParams());
- }, [defaultSearchParams, projectId]);
+ const [searchParams, setSearchParams] = useURLSearchParam({
+ param: "q",
+ parse: parsePlanSearchParams,
+ serialize: serializeAdvancedSearch,
+ defaultValue: defaultSearchParams,
+ });
+ const viewCacheKey = useMemo(
+ () =>
+ JSON.stringify([
+ "project-plans",
+ projectName,
+ serializeAdvancedSearch(searchParams),
+ ]),
+ [projectName, searchParams]
+ );
// Scope options
const scopeOptions: ScopeOption[] = useMemo(
@@ -220,6 +241,9 @@ export function ProjectPlanDashboardPage({ projectId }: { projectId: string }) {
const paged = usePagedData<Plan>({
sessionKey: `bb.${projectName}.plan-table`,
+ cacheKey: viewCacheKey,
+ cacheScope: projectPlansPagedDataCacheScope(projectId),
+ cacheRestoreToken: scrollRestorationKey,
fetchList: fetchPlanList,
});
useScrollRestorationLoadMore(paged);
@@ -328,7 +352,11 @@ export function ProjectPlanDashboardPage({ projectId }: { projectId: string }) {
{t("common.no-data")}
</div>
) : (
- <PlanTable plans={paged.dataList} projectId={projectId} />
+ <PlanTable
+ plans={paged.dataList}
+ projectId={projectId}
+ onOpenPlan={handleOpenPlan}
+ />
)}
{paged.dataList.length > 0 && (
@@ -377,7 +405,15 @@ interface PlanRowContext {
draftState: PlanDraftState;
}
-function PlanTable({ plans, projectId }: { plans: Plan[]; projectId: string }) {
+function PlanTable({
+ plans,
+ projectId,
+ onOpenPlan,
+}: {
+ plans: Plan[];
+ projectId: string;
+ onOpenPlan: () => void;
+}) {
const { t } = useTranslation();
const isMobile = useMediaQuery(MOBILE_MEDIA_QUERY);
// Subscribe so stage cells re-render when the environment cache loads.
@@ -550,6 +586,7 @@ function PlanTable({ plans, projectId }: { plans: Plan[]; projectId: string }) {
plan={plan}
projectId={projectId}
columns={columns}
+ onOpenPlan={onOpenPlan}
/>
))}
</TableBody>
@@ -566,10 +603,12 @@ function PlanRow({
plan,
projectId,
columns,
+ onOpenPlan,
}: Readonly<{
plan: Plan;
projectId: string;
columns: PlanColumn[];
+ onOpenPlan: () => void;
}>) {
const { t } = useTranslation();
@@ -605,10 +644,11 @@ function PlanRow({
if (e.ctrlKey || e.metaKey) {
window.open(planUrl, "_blank");
} else {
+ onOpenPlan();
router.push(planUrl);
}
},
- [planUrl]
+ [onOpenPlan, planUrl]
);
// Approval status
@@ -642,6 +682,8 @@ function PlanRow({
return (
<TableRow
+ data-testid="plan-list-item"
+ data-scroll-restoration-anchor={plan.name}
className={cn("cursor-pointer", isDeleted && "opacity-60")}
onClick={onRowClick}
>
diff --git a/frontend/src/react/pages/project/issue-detail/hooks/useIssueDetailPage.ts b/frontend/src/react/pages/project/issue-detail/hooks/useIssueDetailPage.ts
index 8643e3cd5c..8fa00a9e6b 100644
--- a/frontend/src/react/pages/project/issue-detail/hooks/useIssueDetailPage.ts
+++ b/frontend/src/react/pages/project/issue-detail/hooks/useIssueDetailPage.ts
@@ -37,6 +37,7 @@ import {
} from "@/types/proto-es/v1/rollout_service_pb";
import { UNKNOWN_PLAN_NAME, unknownPlan } from "@/types/v1/issue/plan";
import { getRolloutFromPlan, minmax, setDocumentTitle } from "@/utils";
+import { invalidateProjectPagedDataCacheIfChanged } from "../../pagedDataCacheScope";
import type { ProjectIssueDetailPageProps } from "../types";
import {
type IssueDetailType,
@@ -309,6 +310,19 @@ export const useIssueDetailPage = ({
const patchState = useCallback(
(patch: Partial<IssueDetailPageSnapshot>) => {
+ const previous = latestSnapshotRef.current;
+ invalidateProjectPagedDataCacheIfChanged(
+ previous.projectId,
+ "plans",
+ previous.plan,
+ patch.plan
+ );
+ invalidateProjectPagedDataCacheIfChanged(
+ previous.projectId,
+ "issues",
+ previous.issue,
+ patch.issue
+ );
setSnapshot((prev) => {
const next = applyDerivedState({ ...prev, ...patch });
return isSameSnapshot(prev, next) ? prev : next;
diff --git a/frontend/src/react/pages/project/pagedDataCacheScope.test.ts b/frontend/src/react/pages/project/pagedDataCacheScope.test.ts
new file mode 100644
index 0000000000..ea3403f139
--- /dev/null
+++ b/frontend/src/react/pages/project/pagedDataCacheScope.test.ts
@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, test } from "vitest";
+import {
+ clearPagedDataCache,
+ readPagedDataCache,
+ writePagedDataCache,
+} from "@/react/hooks/pagedDataCache";
+import {
+ invalidateProjectPagedDataCacheIfChanged,
+ projectIssuesPagedDataCacheScope,
+ projectPlansPagedDataCacheScope,
+} from "./pagedDataCacheScope";
+
+describe("project paged data cache scopes", () => {
+ beforeEach(clearPagedDataCache);
+
+ test("keeps resource types and projects isolated", () => {
+ expect(projectPlansPagedDataCacheScope("a")).not.toBe(
+ projectIssuesPagedDataCacheScope("a")
+ );
+ expect(projectPlansPagedDataCacheScope("a")).not.toBe(
+ projectPlansPagedDataCacheScope("b")
+ );
+ });
+
+ test("returns a stable scope", () => {
+ expect(projectPlansPagedDataCacheScope("a")).toBe(
+ projectPlansPagedDataCacheScope("a")
+ );
+ });
+
+ test("invalidates only the changed resource scope", () => {
+ writePagedDataCache(
+ "plans",
+ { dataList: ["plan"], hasMore: false, nextPageToken: "" },
+ projectPlansPagedDataCacheScope("a")
+ );
+ writePagedDataCache(
+ "issues",
+ { dataList: ["issue"], hasMore: false, nextPageToken: "" },
+ projectIssuesPagedDataCacheScope("a")
+ );
+
+ invalidateProjectPagedDataCacheIfChanged(
+ "a",
+ "plans",
+ { name: "projects/a/plans/1", updateTime: { seconds: 1n, nanos: 0 } },
+ { name: "projects/a/plans/1", updateTime: { seconds: 2n, nanos: 0 } }
+ );
+
+ expect(readPagedDataCache("plans")).toBeUndefined();
+ expect(readPagedDataCache("issues")?.dataList).toEqual(["issue"]);
+ });
+
+ test("keeps the cache for initial or unchanged resources", () => {
+ writePagedDataCache(
+ "plans",
+ { dataList: ["plan"], hasMore: false, nextPageToken: "" },
+ projectPlansPagedDataCacheScope("a")
+ );
+
+ invalidateProjectPagedDataCacheIfChanged("a", "plans", undefined, {
+ name: "projects/a/plans/1",
+ updateTime: { seconds: 1n, nanos: 0 },
+ });
+ invalidateProjectPagedDataCacheIfChanged(
+ "a",
+ "plans",
+ { name: "projects/a/plans/1", updateTime: { seconds: 1n, nanos: 0 } },
+ { name: "projects/a/plans/1", updateTime: { seconds: 1n, nanos: 0 } }
+ );
+
+ expect(readPagedDataCache("plans")?.dataList).toEqual(["plan"]);
+ });
+
+ test("keeps the cache when the detail route changes resources", () => {
+ writePagedDataCache(
+ "plans",
+ { dataList: ["plan"], hasMore: false, nextPageToken: "" },
+ projectPlansPagedDataCacheScope("a")
+ );
+
+ invalidateProjectPagedDataCacheIfChanged(
+ "a",
+ "plans",
+ { name: "projects/a/plans/1", updateTime: { seconds: 1n, nanos: 0 } },
+ { name: "projects/b/plans/2", updateTime: { seconds: 2n, nanos: 0 } }
+ );
+
+ expect(readPagedDataCache("plans")?.dataList).toEqual(["plan"]);
+ });
+});
diff --git a/frontend/src/react/pages/project/pagedDataCacheScope.ts b/frontend/src/react/pages/project/pagedDataCacheScope.ts
new file mode 100644
index 0000000000..5137926366
--- /dev/null
+++ b/frontend/src/react/pages/project/pagedDataCacheScope.ts
@@ -0,0 +1,45 @@
+import { invalidatePagedDataCacheScope } from "@/react/hooks/pagedDataCache";
+
+type VersionedResource = {
+ name: string;
+ updateTime?: {
+ seconds: bigint;
+ nanos: number;
+ };
+};
+
+const projectPagedDataCacheScope = (
+ resource: "issues" | "plans",
+ projectId: string
+): string => `projects/${projectId}/${resource}`;
+
+export const projectIssuesPagedDataCacheScope = (projectId: string): string =>
+ projectPagedDataCacheScope("issues", projectId);
+
+export const projectPlansPagedDataCacheScope = (projectId: string): string =>
+ projectPagedDataCacheScope("plans", projectId);
+
+export const invalidateProjectPagedDataCacheIfChanged = (
+ projectId: string,
+ resource: "issues" | "plans",
+ previous: VersionedResource | undefined,
+ next: VersionedResource | undefined
+): void => {
+ const previousTime = previous?.updateTime;
+ const nextTime = next?.updateTime;
+ if (
+ previous?.name !== next?.name ||
+ !previousTime ||
+ !nextTime ||
+ (previousTime.seconds === nextTime.seconds &&
+ previousTime.nanos === nextTime.nanos)
+ ) {
+ return;
+ }
+
+ invalidatePagedDataCacheScope(
+ resource === "plans"
+ ? projectPlansPagedDataCacheScope(projectId)
+ : projectIssuesPagedDataCacheScope(projectId)
+ );
+};
diff --git a/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx b/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx
index 275a79163b..f00f899c82 100644
--- a/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx
+++ b/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.test.tsx
@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
import { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MAIN_SCROLL_RESTORATION_ID } from "@/react/router/NavigationScrollRestoration";
import { State } from "@/types/proto-es/v1/common_pb";
import type { PlanDetailPageState } from "./shell/hooks/types";
@@ -169,6 +170,46 @@ const selectedSpecIdText = () =>
container.querySelector('[data-testid="selected-spec-id"]')?.textContent;
describe("ProjectPlanDetailPage", () => {
+ it("uses the dashboard main pane as its vertical scroll owner", async () => {
+ mocks.usePlanDetailPage.mockReturnValue(buildPage());
+
+ await act(async () => {
+ root.render(
+ <div data-scroll-restoration-id={MAIN_SCROLL_RESTORATION_ID}>
+ <ProjectPlanDetailPage
+ planId="create"
+ projectId="foo"
+ specId="spec-1"
+ />
+ </div>
+ );
+ await Promise.resolve();
+ });
+
+ const scrollHost = container.querySelector<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ const pageHost = container.querySelector<HTMLElement>(
+ '[data-testid="plan-detail-page"]'
+ );
+ const header = pageHost?.querySelector("header");
+ if (!scrollHost || !pageHost || !header) {
+ throw new Error("Missing plan-detail scroll test elements");
+ }
+
+ const pageHostClasses = pageHost.className.split(/\s+/);
+ expect(pageHostClasses).toContain("min-h-full");
+ expect(pageHostClasses).toContain("overflow-x-clip");
+ expect(pageHostClasses).not.toContain("h-full");
+ expect(pageHostClasses).not.toContain("overflow-x-hidden");
+
+ act(() => {
+ scrollHost.scrollTop = 1;
+ scrollHost.dispatchEvent(new Event("scroll"));
+ });
+ expect(header.className).toContain("border-b");
+ });
+
it("keeps local spec selection on creating plans with a stale route spec id", async () => {
mocks.usePlanDetailPage.mockReturnValue(buildPage());
diff --git a/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx b/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx
index 38e98191ca..c53f124e5f 100644
--- a/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx
+++ b/frontend/src/react/pages/project/plan-detail/ProjectPlanDetailPage.tsx
@@ -11,6 +11,7 @@ import {
import { Badge } from "@/react/components/ui/badge";
import { Button } from "@/react/components/ui/button";
import { cn } from "@/react/lib/utils";
+import { MAIN_SCROLL_RESTORATION_ID } from "@/react/router/NavigationScrollRestoration";
import { IssueStatus } from "@/types/proto-es/v1/issue_service_pb";
import { Task_Status } from "@/types/proto-es/v1/rollout_service_pb";
import { getRolloutStatus } from "@/utils";
@@ -71,14 +72,18 @@ function ProjectPlanDetailPageInner({
const [pageHost, setPageHost] = useState<HTMLDivElement | null>(null);
// The sticky title row only shows its bottom border once content scrolls
// under it (GitHub issue-header pattern) — flat at the top, separated when
- // stuck. pageHost is the scroll container.
+ // stuck. The dashboard main pane owns vertical scrolling.
const [headerStuck, setHeaderStuck] = useState(false);
useEffect(() => {
if (!pageHost) return;
- const onScroll = () => setHeaderStuck(pageHost.scrollTop > 0);
+ const scrollHost = pageHost.closest<HTMLElement>(
+ `[data-scroll-restoration-id="${MAIN_SCROLL_RESTORATION_ID}"]`
+ );
+ if (!scrollHost) return;
+ const onScroll = () => setHeaderStuck(scrollHost.scrollTop > 0);
onScroll();
- pageHost.addEventListener("scroll", onScroll, { passive: true });
- return () => pageHost.removeEventListener("scroll", onScroll);
+ scrollHost.addEventListener("scroll", onScroll, { passive: true });
+ return () => scrollHost.removeEventListener("scroll", onScroll);
}, [pageHost]);
const [selectedSpecId, setSelectedSpecId] = useState(specId ?? "");
const page = usePlanDetailPage({
@@ -239,7 +244,8 @@ function ProjectPlanDetailPageInner({
<PlanDetailProvider value={page}>
<div
ref={setPageHost}
- className="relative h-full overflow-x-hidden bg-gray-50"
+ data-testid="plan-detail-page"
+ className="relative min-h-full overflow-x-clip bg-gray-50"
>
<div
className={cn(
@@ -248,10 +254,10 @@ function ProjectPlanDetailPageInner({
)}
>
{/* Only the title/action row is sticky (GitHub issue-header pattern);
- the description + metadata below scroll away beneath it. pageHost
- (overflow-x-hidden → overflow-y auto) is the scroll container, so
- top-0 pins to it; z-20 keeps it above the phase rail nodes (z-10).
- The border appears only when stuck, so the row is flat at the top. */}
+ the description + metadata below scroll away beneath it. The
+ dashboard main pane is the scroll container, so top-0 pins to it;
+ z-20 keeps it above the phase rail nodes (z-10). The border appears
+ only when stuck, so the row is flat at the top. */}
<header
className={cn(
"sticky top-0 z-20 shrink-0 bg-white",
diff --git a/frontend/src/react/pages/project/plan-detail/shell/hooks/usePlanDetailPage.ts b/frontend/src/react/pages/project/plan-detail/shell/hooks/usePlanDetailPage.ts
index 41fd68cb0a..13e39c4d02 100644
--- a/frontend/src/react/pages/project/plan-detail/shell/hooks/usePlanDetailPage.ts
+++ b/frontend/src/react/pages/project/plan-detail/shell/hooks/usePlanDetailPage.ts
@@ -36,6 +36,7 @@ import { unknownProject } from "@/types/v1/project";
import { unknownUser } from "@/types/v1/user";
import { setDocumentTitle } from "@/utils";
import { isTaskActivelyTransitioning } from "@/utils/v1/issue/rollout";
+import { invalidateProjectPagedDataCacheIfChanged } from "../../../pagedDataCacheScope";
import type { PlanDetailPhase } from "../../shared/stores/types";
import { usePlanDetailStoreApi } from "../../shared/stores/usePlanDetailStore";
import { getPlanCheckSummary } from "../../utils/phaseSummary";
@@ -246,6 +247,18 @@ export const usePlanDetailPage = ({
const patchState = useCallback(
(patch: Partial<PlanDetailPageSnapshot>) => {
const prevSnapshot = latestSnapshotRef.current;
+ invalidateProjectPagedDataCacheIfChanged(
+ prevSnapshot.projectId,
+ "plans",
+ prevSnapshot.plan,
+ patch.plan
+ );
+ invalidateProjectPagedDataCacheIfChanged(
+ prevSnapshot.projectId,
+ "issues",
+ prevSnapshot.issue,
+ patch.issue
+ );
// Seed the shared rollout store from this (already staleness-guarded)
// patch, and adopt the store's identity-preserved instance so the deploy
// view and the log viewer read the exact same rollout object.
diff --git a/frontend/src/react/pages/settings/InstancesPage.tsx b/frontend/src/react/pages/settings/InstancesPage.tsx
index a004758ef1..0885ffa5ab 100644
--- a/frontend/src/react/pages/settings/InstancesPage.tsx
+++ b/frontend/src/react/pages/settings/InstancesPage.tsx
@@ -703,6 +703,7 @@ export function InstancesPage() {
dataList: instances,
hasMore,
isFetchingMore,
+ isLoading: loading,
loadMore,
});
diff --git a/frontend/src/react/pages/settings/ProjectsPage.tsx b/frontend/src/react/pages/settings/ProjectsPage.tsx
index 65016dd157..98bc9c72bc 100644
--- a/frontend/src/react/pages/settings/ProjectsPage.tsx
+++ b/frontend/src/react/pages/settings/ProjectsPage.tsx
@@ -439,6 +439,7 @@ export function ProjectsPage() {
dataList: projects,
hasMore,
isFetchingMore,
+ isLoading: loading,
loadMore,
});
diff --git a/frontend/src/react/pages/workspace/MyIssuesPage.tsx b/frontend/src/react/pages/workspace/MyIssuesPage.tsx
index e13756eb9d..d07170bb4a 100644
--- a/frontend/src/react/pages/workspace/MyIssuesPage.tsx
+++ b/frontend/src/react/pages/workspace/MyIssuesPage.tsx
@@ -1,4 +1,5 @@
import { useCallback, useEffect, useMemo, useState } from "react";
+import { useLocation } from "react-router";
import type { SearchParams } from "@/react/components/AdvancedSearch";
import {
BatchActionBar,
@@ -16,7 +17,11 @@ import { useCurrentUser } from "@/react/hooks/useAppState";
import { PagedTableFooter, usePagedData } from "@/react/hooks/usePagedData";
import { useURLSearchParam } from "@/react/hooks/useURLSearchParam";
import { refreshIssueList } from "@/react/lib/issue/issueListRefresh";
-import { useScrollRestorationLoadMore } from "@/react/router/NavigationScrollRestoration";
+import {
+ markScrollRestorationEntry,
+ useScrollRestorationKey,
+ useScrollRestorationLoadMore,
+} from "@/react/router/NavigationScrollRestoration";
import { useAppStore } from "@/react/stores/app";
import { ApprovalStatus } from "@/types/proto-es/v1/common_pb";
import type { Issue } from "@/types/proto-es/v1/issue_service_pb";
@@ -33,6 +38,8 @@ const serializeSearchParams = (params: SearchParams): string =>
buildSearchTextBySearchParams(params);
export function MyIssuesPage() {
+ const location = useLocation();
+ const scrollRestorationKey = useScrollRestorationKey();
const batchGetOrFetchUsers = useAppStore(
(state) => state.batchGetOrFetchUsers
);
@@ -63,6 +70,15 @@ export function MyIssuesPage() {
param: "order",
defaultValue: "",
});
+ const viewCacheKey = useMemo(
+ () =>
+ JSON.stringify([
+ "my-issues",
+ serializeSearchParams(searchParams),
+ orderBy,
+ ]),
+ [orderBy, searchParams]
+ );
// Issue filter
const issueFilter = useMemo(() => {
@@ -87,6 +103,8 @@ export function MyIssuesPage() {
const paged = usePagedData<Issue>({
sessionKey: "bb.issue-table.my-issues",
+ cacheKey: viewCacheKey,
+ cacheRestoreToken: scrollRestorationKey,
fetchList: fetchIssueList,
});
useScrollRestorationLoadMore(paged);
@@ -128,6 +146,10 @@ export function MyIssuesPage() {
return next;
});
}, []);
+ const handleOpenIssue = useCallback(
+ () => markScrollRestorationEntry(location),
+ [location]
+ );
const toggleSelectAll = useCallback(() => {
setSelectedNames((prev) => {
@@ -169,6 +191,7 @@ export function MyIssuesPage() {
issues={paged.dataList}
selectedNames={selectedNames}
onToggleSelection={toggleSelection}
+ onOpenIssue={handleOpenIssue}
showProject
/>
{paged.dataList.length > 0 && (
diff --git a/frontend/src/react/router/NavigationScrollRestoration.test.tsx b/frontend/src/react/router/NavigationScrollRestoration.test.tsx
index 1b65a62340..76ba7f402c 100644
--- a/frontend/src/react/router/NavigationScrollRestoration.test.tsx
+++ b/frontend/src/react/router/NavigationScrollRestoration.test.tsx
@@ -1,4 +1,4 @@
-import { act, useState } from "react";
+import { act, useLayoutEffect, useRef, useState } from "react";
import { createRoot } from "react-dom/client";
import { createMemoryRouter, Outlet } from "react-router";
import { RouterProvider } from "react-router/dom";
@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
import { setAppRouter } from "./navigation";
import {
MAIN_SCROLL_RESTORATION_ID,
+ markScrollRestorationEntry,
NavigationScrollRestoration,
useScrollRestorationLoadMore,
} from "./NavigationScrollRestoration";
@@ -14,13 +15,14 @@ import {
globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
).IS_REACT_ACT_ENVIRONMENT = true;
-function TestShell() {
+function TestShell({ routeInsidePanel = true }: { routeInsidePanel?: boolean }) {
return (
<NavigationScrollRestoration>
<div data-scroll-restoration-id={MAIN_SCROLL_RESTORATION_ID}>
<div data-scroll-restoration-id="panel">
- <Outlet />
+ {routeInsidePanel ? <Outlet /> : null}
</div>
+ {routeInsidePanel ? null : <Outlet />}
</div>
</NavigationScrollRestoration>
);
@@ -33,6 +35,17 @@ function makeScrollable(element: HTMLElement): void {
scrollHeight: { configurable: true, value: 1000 },
scrollWidth: { configurable: true, value: 1000 },
});
+ element.getBoundingClientRect = () => ({
+ x: 0,
+ y: 0,
+ top: 0,
+ bottom: 200,
+ left: 0,
+ right: 200,
+ width: 200,
+ height: 200,
+ toJSON: () => ({}),
+ });
}
function recordScroll(element: HTMLElement, top: number, left = 0): void {
@@ -41,15 +54,89 @@ function recordScroll(element: HTMLElement, top: number, left = 0): void {
element.dispatchEvent(new Event("scroll"));
}
-async function renderRouter(firstElement = <div>First</div>) {
+function RouteScrollMetrics({
+ scrollHeight,
+ resetScrollTop = false,
+}: {
+ scrollHeight: number;
+ resetScrollTop?: boolean;
+}) {
+ useLayoutEffect(() => {
+ const main = document.querySelector<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ if (!main) throw new Error("Missing main scroll target");
+ Object.defineProperty(main, "scrollHeight", {
+ configurable: true,
+ value: scrollHeight,
+ });
+ if (resetScrollTop) main.scrollTop = 0;
+ }, [resetScrollTop, scrollHeight]);
+
+ return null;
+}
+
+function AnchorPage({
+ anchorTop,
+ scrollHeight,
+}: {
+ anchorTop: () => number;
+ scrollHeight?: () => number;
+}) {
+ const anchorRef = useRef<HTMLDivElement>(null);
+
+ useLayoutEffect(() => {
+ const anchor = anchorRef.current;
+ const main = anchor?.closest<HTMLElement>(
+ `[data-scroll-restoration-id='${MAIN_SCROLL_RESTORATION_ID}']`
+ );
+ if (!anchor || !main) throw new Error("Missing anchor test elements");
+ if (scrollHeight) {
+ Object.defineProperty(main, "scrollHeight", {
+ configurable: true,
+ value: scrollHeight(),
+ });
+ }
+
+ anchor.getBoundingClientRect = () => {
+ const top = anchorTop() - main.scrollTop;
+ return {
+ x: 0,
+ y: top,
+ top,
+ bottom: top + 40,
+ left: 0,
+ right: 200,
+ width: 200,
+ height: 40,
+ toJSON: () => ({}),
+ };
+ };
+ }, [anchorTop, scrollHeight]);
+
+ return (
+ <div
+ ref={anchorRef}
+ data-scroll-restoration-anchor="issues/anchor"
+ >
+ Anchor
+ </div>
+ );
+}
+
+async function renderRouter(
+ firstElement = <div>First</div>,
+ secondElement = <div>Second</div>,
+ { routeInsidePanel = true }: { routeInsidePanel?: boolean } = {}
+) {
const router = createMemoryRouter(
[
{
path: "/",
- element: <TestShell />,
+ element: <TestShell routeInsidePanel={routeInsidePanel} />,
children: [
{ path: "first", element: firstElement },
- { path: "second", element: <div>Second</div> },
+ { path: "second", element: secondElement },
],
},
],
@@ -101,21 +188,35 @@ afterEach(() => {
});
describe("NavigationScrollRestoration", () => {
- test("restores every scroll target on Back and Forward", async () => {
+ test("does not restore an unmarked POP navigation", async () => {
+ const { main, router, unmount } = await renderRouter();
+
+ recordScroll(main, 240);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+ expect(main.scrollTop).toBe(0);
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(0);
+ unmount();
+ });
+
+ test("restores every scroll target after an item click", async () => {
const { main, panel, router, unmount } = await renderRouter();
recordScroll(main, 240, 30);
recordScroll(panel, 120, 10);
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
expect(main.scrollTop).toBe(0);
expect(panel.scrollTop).toBe(0);
- recordScroll(main, 360, 40);
- recordScroll(panel, 180, 20);
-
await act(async () => {
await router.navigate(-1);
});
@@ -124,14 +225,6 @@ describe("NavigationScrollRestoration", () => {
expect(panel.scrollTop).toBe(120);
expect(panel.scrollLeft).toBe(10);
- await act(async () => {
- await router.navigate(1);
- });
- expect(main.scrollTop).toBe(360);
- expect(main.scrollLeft).toBe(40);
- expect(panel.scrollTop).toBe(180);
- expect(panel.scrollLeft).toBe(20);
-
unmount();
});
@@ -139,6 +232,7 @@ describe("NavigationScrollRestoration", () => {
const { main, router, unmount } = await renderRouter();
main.scrollTop = 240;
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -150,11 +244,33 @@ describe("NavigationScrollRestoration", () => {
unmount();
});
+ test("does not overwrite the outgoing position after destination layout commits", async () => {
+ const { main, router, unmount } = await renderRouter(
+ <RouteScrollMetrics scrollHeight={1000} />,
+ <RouteScrollMetrics scrollHeight={200} resetScrollTop />
+ );
+
+ main.scrollTop = 640;
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+ expect(main.scrollTop).toBe(0);
+
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(640);
+ unmount();
+ });
+
test("restores after repeated Push and Back navigations", async () => {
const { main, router, unmount } = await renderRouter();
recordScroll(main, 240);
for (let i = 0; i < 3; i++) {
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -179,6 +295,7 @@ describe("NavigationScrollRestoration", () => {
});
expect(main.scrollTop).toBe(240);
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -197,6 +314,7 @@ describe("NavigationScrollRestoration", () => {
useScrollRestorationLoadMore({
hasMore: true,
isFetchingMore: false,
+ isLoading: false,
dataList: [],
loadMore: onLoadMore,
});
@@ -205,6 +323,7 @@ describe("NavigationScrollRestoration", () => {
const { main, router, unmount } = await renderRouter(<PagedPage />);
recordScroll(main, 700);
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -230,6 +349,7 @@ describe("NavigationScrollRestoration", () => {
useScrollRestorationLoadMore({
hasMore: true,
isFetchingMore: false,
+ isLoading: false,
dataList,
loadMore: onLoadMore,
});
@@ -238,6 +358,7 @@ describe("NavigationScrollRestoration", () => {
const { main, router, unmount } = await renderRouter(<PagedPage />);
recordScroll(main, 700);
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -273,6 +394,7 @@ describe("NavigationScrollRestoration", () => {
useScrollRestorationLoadMore({
hasMore: true,
isFetchingMore,
+ isLoading: false,
dataList,
loadMore: () => {
onLoadMore();
@@ -284,6 +406,7 @@ describe("NavigationScrollRestoration", () => {
const { main, router, unmount } = await renderRouter(<PagedPage />);
recordScroll(main, 700);
+ markScrollRestorationEntry(router.state.location);
await act(async () => {
await router.navigate("/second");
});
@@ -304,4 +427,278 @@ describe("NavigationScrollRestoration", () => {
expect(onLoadMore).toHaveBeenCalledTimes(2);
unmount();
});
+
+ test("keeps the same semantic anchor offset when row geometry changes", async () => {
+ let anchorTop = 400;
+ const { main, router, unmount } = await renderRouter(
+ <AnchorPage anchorTop={() => anchorTop} />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+
+ recordScroll(main, 380);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ anchorTop = 460;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(440);
+ unmount();
+ });
+
+ test("uses the semantic anchor when the old coordinate is no longer reachable", async () => {
+ let anchorTop = 620;
+ let scrollHeight = 1000;
+ const { main, router, unmount } = await renderRouter(
+ <AnchorPage
+ anchorTop={() => anchorTop}
+ scrollHeight={() => scrollHeight}
+ />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+
+ recordScroll(main, 600);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ anchorTop = 350;
+ scrollHeight = 550;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(330);
+ unmount();
+ });
+
+ test("grows paged content when a saved anchor is not loaded yet", async () => {
+ const onLoadMore = vi.fn();
+ let showAnchor = true;
+ const PagedAnchorPage = () => {
+ useScrollRestorationLoadMore({
+ hasMore: true,
+ isFetchingMore: false,
+ isLoading: false,
+ dataList: [{}],
+ loadMore: onLoadMore,
+ });
+ return showAnchor ? (
+ <AnchorPage anchorTop={() => 320} />
+ ) : (
+ <div>First page</div>
+ );
+ };
+ const { main, router, unmount } = await renderRouter(
+ <PagedAnchorPage />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+
+ recordScroll(main, 300);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ showAnchor = false;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ const restoredScrollTop = main.scrollTop;
+ unmount();
+
+ expect(restoredScrollTop).toBe(300);
+ expect(onLoadMore).toHaveBeenCalledOnce();
+ });
+
+ test("keeps restoring while an anchor correction is temporarily clamped", async () => {
+ vi.useFakeTimers();
+ let anchorTop = 320;
+ let scrollHeight = 1000;
+ const { main, router, unmount } = await renderRouter(
+ <AnchorPage
+ anchorTop={() => anchorTop}
+ scrollHeight={() => scrollHeight}
+ />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+ let scrollTop = 0;
+ let maxScrollTop = 800;
+ Object.defineProperty(main, "scrollTop", {
+ configurable: true,
+ get: () => scrollTop,
+ set: (value: number) => {
+ scrollTop = Math.max(0, Math.min(value, maxScrollTop));
+ },
+ });
+
+ recordScroll(main, 300);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ anchorTop = 500;
+ scrollHeight = 650;
+ maxScrollTop = 450;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+ expect(main.scrollTop).toBe(450);
+
+ Object.defineProperty(main, "scrollHeight", {
+ configurable: true,
+ value: 800,
+ });
+ maxScrollTop = 600;
+ act(() => vi.advanceTimersByTime(100));
+
+ expect(main.scrollTop).toBe(480);
+ unmount();
+ });
+
+ test("grows paged content while an anchor correction is clamped", async () => {
+ vi.useFakeTimers();
+ const onLoadMore = vi.fn();
+ let finishPage: (() => void) | undefined;
+ let anchorTop = 320;
+ let scrollHeight = 1000;
+ const PagedAnchorPage = () => {
+ const [dataList, setDataList] = useState<unknown[]>([]);
+ const [hasMore, setHasMore] = useState(true);
+ const [isFetchingMore, setIsFetchingMore] = useState(false);
+ finishPage = () => {
+ setDataList([{}]);
+ setHasMore(false);
+ setIsFetchingMore(false);
+ };
+ useScrollRestorationLoadMore({
+ hasMore,
+ isFetchingMore,
+ isLoading: false,
+ dataList,
+ loadMore: () => {
+ onLoadMore();
+ setIsFetchingMore(true);
+ },
+ });
+ return (
+ <AnchorPage
+ anchorTop={() => anchorTop}
+ scrollHeight={() => scrollHeight}
+ />
+ );
+ };
+ const { main, router, unmount } = await renderRouter(
+ <PagedAnchorPage />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+ let scrollTop = 0;
+ let maxScrollTop = 800;
+ Object.defineProperty(main, "scrollTop", {
+ configurable: true,
+ get: () => scrollTop,
+ set: (value: number) => {
+ scrollTop = Math.max(0, Math.min(value, maxScrollTop));
+ },
+ });
+
+ recordScroll(main, 300);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ anchorTop = 500;
+ scrollHeight = 650;
+ maxScrollTop = 450;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(450);
+ expect(onLoadMore).toHaveBeenCalledOnce();
+
+ Object.defineProperty(main, "scrollHeight", {
+ configurable: true,
+ value: 800,
+ });
+ maxScrollTop = 600;
+ act(() => finishPage?.());
+
+ expect(main.scrollTop).toBe(480);
+ expect(vi.getTimerCount()).toBe(0);
+ unmount();
+ });
+
+ test("accepts the best clamped anchor when paged content cannot grow", async () => {
+ vi.useFakeTimers();
+ let anchorTop = 320;
+ let scrollHeight = 1000;
+ const PagedAnchorPage = () => {
+ useScrollRestorationLoadMore({
+ hasMore: false,
+ isFetchingMore: false,
+ isLoading: false,
+ dataList: [],
+ loadMore: vi.fn(),
+ });
+ return (
+ <AnchorPage
+ anchorTop={() => anchorTop}
+ scrollHeight={() => scrollHeight}
+ />
+ );
+ };
+ const { main, router, unmount } = await renderRouter(
+ <PagedAnchorPage />,
+ <div>Second</div>,
+ { routeInsidePanel: false }
+ );
+ let scrollTop = 0;
+ let maxScrollTop = 800;
+ Object.defineProperty(main, "scrollTop", {
+ configurable: true,
+ get: () => scrollTop,
+ set: (value: number) => {
+ scrollTop = Math.max(0, Math.min(value, maxScrollTop));
+ },
+ });
+
+ recordScroll(main, 300);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ });
+
+ anchorTop = 500;
+ scrollHeight = 650;
+ maxScrollTop = 450;
+ await act(async () => {
+ await router.navigate(-1);
+ });
+ expect(main.scrollTop).toBe(450);
+ expect(vi.getTimerCount()).toBe(0);
+
+ recordScroll(main, 200);
+ markScrollRestorationEntry(router.state.location);
+ await act(async () => {
+ await router.navigate("/second");
+ await router.navigate(-1);
+ });
+
+ expect(main.scrollTop).toBe(200);
+ unmount();
+ });
});
diff --git a/frontend/src/react/router/NavigationScrollRestoration.tsx b/frontend/src/react/router/NavigationScrollRestoration.tsx
index b979a4e6f0..c9324a3eb0 100644
--- a/frontend/src/react/router/NavigationScrollRestoration.tsx
+++ b/frontend/src/react/router/NavigationScrollRestoration.tsx
@@ -21,6 +21,7 @@ const RESTORE_MAX_TIMEOUT_MS = 5 * 60 * 1000;
const WINDOW_TARGET_ID = "window";
const CUSTOM_TARGET_PREFIX = "custom:";
const TARGET_ATTRIBUTE = "data-scroll-restoration-id";
+const ANCHOR_ATTRIBUTE = "data-scroll-restoration-anchor";
/** The `data-scroll-restoration-id` value carried by the main layout pane. */
export const MAIN_SCROLL_RESTORATION_ID = "main";
const SCROLL_KEYS = new Set([
@@ -32,10 +33,17 @@ const SCROLL_KEYS = new Set([
"PageUp",
" ",
]);
+const restorableLocationKeys = new Set<string>();
+
+type ScrollAnchor = {
+ key: string;
+ offset: number;
+};
type ScrollPosition = {
x: number;
y: number;
+ anchor?: ScrollAnchor;
};
type SavedPositions = Record<string, Record<string, ScrollPosition>>;
@@ -49,12 +57,16 @@ type ActiveRestoration = {
type PendingRestore = {
cancel: () => void;
keepAlive: () => void;
+ needsGrowth: () => boolean;
+ settle: () => void;
setBusy: (busy: boolean) => void;
};
type ScrollRestorationContextValue = {
positions: Record<string, ScrollPosition>;
keepAlive: (id: string) => void;
+ needsGrowth: (id: string) => boolean;
+ settle: (id: string) => void;
setBusy: (id: string, busy: boolean) => void;
};
@@ -73,6 +85,21 @@ function locationStorageKey(location: Location): string {
return `default:${location.pathname}${location.search}${location.hash}`;
}
+export function markScrollRestorationEntry(location: Location): void {
+ restorableLocationKeys.add(locationStorageKey(location));
+}
+
+export function useScrollRestorationKey(): string | undefined {
+ const location = useLocation();
+ const navigationType = useNavigationType();
+ return useMemo(() => {
+ const key = locationStorageKey(location);
+ return navigationType === "POP" && restorableLocationKeys.has(key)
+ ? key
+ : undefined;
+ }, [location, navigationType]);
+}
+
function loadSavedPositions(): SavedPositions {
try {
const saved = sessionStorage.getItem(STORAGE_KEY);
@@ -159,11 +186,45 @@ function collectTargets(): Map<string, ScrollTarget> {
return targets;
}
-function readPosition(target: ScrollTarget): ScrollPosition {
- if (isWindowTarget(target)) {
- return { x: window.scrollX, y: window.scrollY };
+function anchorBelongsToTarget(
+ anchor: HTMLElement,
+ target: ScrollTarget
+): boolean {
+ const owner = anchor.closest<HTMLElement>(`[${TARGET_ATTRIBUTE}]`);
+ return isWindowTarget(target) ? owner === null : owner === target;
+}
+
+function readAnchor(target: ScrollTarget): ScrollAnchor | undefined {
+ const root: ParentNode = isWindowTarget(target) ? document : target;
+ const viewportTop = isWindowTarget(target)
+ ? 0
+ : target.getBoundingClientRect().top;
+ const viewportBottom = isWindowTarget(target)
+ ? window.innerHeight
+ : target.getBoundingClientRect().bottom;
+
+ for (const anchor of root.querySelectorAll<HTMLElement>(
+ `[${ANCHOR_ATTRIBUTE}]`
+ )) {
+ if (!anchorBelongsToTarget(anchor, target)) continue;
+ const key = anchor.getAttribute(ANCHOR_ATTRIBUTE);
+ const rect = anchor.getBoundingClientRect();
+ if (key && rect.bottom > viewportTop && rect.top < viewportBottom) {
+ return { key, offset: rect.top - viewportTop };
+ }
}
- return { x: target.scrollLeft, y: target.scrollTop };
+ return undefined;
+}
+
+function readPosition(
+ target: ScrollTarget,
+ includeAnchor = false
+): ScrollPosition {
+ const coordinate = isWindowTarget(target)
+ ? { x: window.scrollX, y: window.scrollY }
+ : { x: target.scrollLeft, y: target.scrollTop };
+ const anchor = includeAnchor ? readAnchor(target) : undefined;
+ return anchor ? { ...coordinate, anchor } : coordinate;
}
function scrollRange(target: ScrollTarget): ScrollPosition {
@@ -209,6 +270,40 @@ function applyPosition(
};
}
+function applyAnchor(
+ target: ScrollTarget,
+ anchor: ScrollAnchor
+): "missing" | "pending" | "reached" {
+ const root: ParentNode = isWindowTarget(target) ? document : target;
+ const element = Array.from(
+ root.querySelectorAll<HTMLElement>(`[${ANCHOR_ATTRIBUTE}]`)
+ ).find(
+ (candidate) =>
+ candidate.getAttribute(ANCHOR_ATTRIBUTE) === anchor.key &&
+ anchorBelongsToTarget(candidate, target)
+ );
+ if (!element) return "missing";
+
+ const viewportTop = isWindowTarget(target)
+ ? 0
+ : target.getBoundingClientRect().top;
+ const delta =
+ element.getBoundingClientRect().top - viewportTop - anchor.offset;
+ if (Math.abs(delta) < 1) return "reached";
+
+ if (isWindowTarget(target)) {
+ window.scrollTo(window.scrollX, window.scrollY + delta);
+ } else {
+ target.scrollTop += delta;
+ }
+ const restoredViewportTop = isWindowTarget(target)
+ ? 0
+ : target.getBoundingClientRect().top;
+ const remainingDelta =
+ element.getBoundingClientRect().top - restoredViewportTop - anchor.offset;
+ return Math.abs(remainingDelta) < 1 ? "reached" : "pending";
+}
+
function restoreWhenReady(
id: string,
position: ScrollPosition,
@@ -223,6 +318,7 @@ function restoreWhenReady(
let resizeObserver: ResizeObserver | undefined;
let observedTarget: ScrollTarget | null = null;
let lastRange: ScrollPosition | undefined;
+ let growthNeeded = true;
const stop = () => {
if (stopped) return;
@@ -273,7 +369,12 @@ function restoreWhenReady(
lastRange = undefined;
}
const { range, reached } = applyPosition(observedTarget, position);
- if (reached) {
+ const anchorState = position.anchor
+ ? applyAnchor(observedTarget, position.anchor)
+ : "missing";
+ growthNeeded =
+ !reached || (position.anchor !== undefined && anchorState !== "reached");
+ if (anchorState === "reached" || (!position.anchor && reached)) {
stop();
return;
}
@@ -283,6 +384,11 @@ function restoreWhenReady(
lastRange = range;
};
+ const settle = () => {
+ attempt();
+ stop();
+ };
+
attempt();
if (!stopped) {
animationFrameId = window.requestAnimationFrame(attempt);
@@ -293,6 +399,8 @@ function restoreWhenReady(
return {
cancel: stop,
keepAlive,
+ needsGrowth: () => growthNeeded,
+ settle,
setBusy: (value) => {
busy = value;
keepAlive();
@@ -331,12 +439,12 @@ type NavigationScrollRestorationProps = {
export function useScrollRestorationLoadMore(
paged: Pick<
PagedDataResult<unknown>,
- "hasMore" | "isFetchingMore" | "dataList" | "loadMore"
+ "hasMore" | "isFetchingMore" | "isLoading" | "dataList" | "loadMore"
>,
/** The value of `data-scroll-restoration-id`; omit for the main layout pane. */
restorationId: string = MAIN_SCROLL_RESTORATION_ID
): void {
- const { hasMore, isFetchingMore, dataList, loadMore } = paged;
+ const { hasMore, isFetchingMore, isLoading, dataList, loadMore } = paged;
const restoration = useContext(ScrollRestorationContext);
const id = customTargetId(restorationId);
// Depend on the primitive: the saved-position record is replaced on every
@@ -346,20 +454,25 @@ export function useScrollRestorationLoadMore(
useEffect(() => {
if (requestedY === undefined) return;
- restoration?.setBusy(id, isFetchingMore);
+ restoration?.setBusy(id, isLoading || isFetchingMore);
return () => restoration?.setBusy(id, false);
- }, [id, isFetchingMore, requestedY, restoration]);
+ }, [id, isFetchingMore, isLoading, requestedY, restoration]);
useEffect(() => {
- if (requestedY === undefined || !hasMore || isFetchingMore) return;
+ if (requestedY === undefined || isLoading || isFetchingMore) return;
const target = findTarget(id);
- if (!target || scrollRange(target).y >= requestedY) return;
- restoration?.keepAlive(id);
- loadMore();
+ if (!target) return;
+ if (hasMore && restoration?.needsGrowth(id)) {
+ restoration?.keepAlive(id);
+ loadMore();
+ return;
+ }
+ restoration?.settle(id);
}, [
hasMore,
id,
isFetchingMore,
+ isLoading,
itemCount,
loadMore,
requestedY,
@@ -407,6 +520,16 @@ export function NavigationScrollRestoration({
[pendingRestores]
);
+ const restorationNeedsGrowth = useCallback(
+ (id: string) => pendingRestores.get(id)?.needsGrowth() === true,
+ [pendingRestores]
+ );
+
+ const settleRestoration = useCallback(
+ (id: string) => pendingRestores.get(id)?.settle(),
+ [pendingRestores]
+ );
+
const setRestorationBusy = useCallback(
(id: string, busy: boolean) => pendingRestores.get(id)?.setBusy(busy),
[pendingRestores]
@@ -434,7 +557,8 @@ export function NavigationScrollRestoration({
const key = locationKey ?? currentLocationKeyRef.current;
for (const [id, target] of collectTargets()) {
if (pendingRestores.has(id)) continue;
- savePosition(savedPositions, key, id, readPosition(target));
+ const position = readPosition(target, true);
+ savePosition(savedPositions, key, id, position);
}
},
[pendingRestores, savedPositions]
@@ -495,9 +619,6 @@ export function NavigationScrollRestoration({
useLayoutEffect(() => {
const previousLocationKey = currentLocationKeyRef.current;
- if (previousLocationKey !== locationKey) {
- recordAllTargets(previousLocationKey);
- }
cancelPendingRestores();
currentLocationKeyRef.current = locationKey;
const savedForLocation = savedPositions[locationKey];
@@ -507,7 +628,12 @@ export function NavigationScrollRestoration({
copyPositions(savedPositions, previousLocationKey, locationKey);
}
- if (navigationType === "POP" && savedForLocation) {
+ if (
+ navigationType === "POP" &&
+ savedForLocation &&
+ restorableLocationKeys.has(locationKey)
+ ) {
+ restorableLocationKeys.delete(locationKey);
const currentTargets = collectTargets();
const targetIds = new Set([
...currentTargets.keys(),
@@ -553,7 +679,6 @@ export function NavigationScrollRestoration({
locationKey,
navigationType,
pendingRestores,
- recordAllTargets,
savedPositions,
]);
@@ -563,10 +688,19 @@ export function NavigationScrollRestoration({
? {
positions: activeRestoration.positions,
keepAlive: keepRestorationAlive,
+ needsGrowth: restorationNeedsGrowth,
+ settle: settleRestoration,
setBusy: setRestorationBusy,
}
: undefined,
- [activeRestoration, keepRestorationAlive, locationKey, setRestorationBusy]
+ [
+ activeRestoration,
+ keepRestorationAlive,
+ locationKey,
+ restorationNeedsGrowth,
+ setRestorationBusy,
+ settleRestoration,
+ ]
);
return (
diff --git a/frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts b/frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts
new file mode 100644
index 0000000000..b0f99ab829
--- /dev/null
+++ b/frontend/tests/e2e/scroll-restoration/dashboard-scroll-restoration.spec.ts
@@ -0,0 +1,187 @@
+import {
+ expect,
+ test,
+ type BrowserContext,
+ type Locator,
+ type Page,
+} from "@playwright/test";
+import { BytebaseApiClient } from "../framework/api-client";
+import { loadTestEnv, type TestEnv } from "../framework/env";
+
+test.setTimeout(240_000);
+
+const ISSUE_COUNT = 18;
+const PLAN_COUNT = 55;
+let env: TestEnv & { api: BytebaseApiClient };
+let sharedContext: BrowserContext;
+let page: Page;
+let issueListUrl: string;
+let planListUrl: string;
+let originalExternalUrl = "";
+
+type SavedViewport = {
+ scrollTop: number;
+ anchorOffset: number;
+};
+
+const readViewport = (row: Locator): Promise<SavedViewport> =>
+ row.evaluate((element) => {
+ const main = document.querySelector<HTMLElement>("#bb-layout-main");
+ if (!main) throw new Error("Missing #bb-layout-main");
+ return {
+ scrollTop: main.scrollTop,
+ anchorOffset:
+ element.getBoundingClientRect().top - main.getBoundingClientRect().top,
+ };
+ });
+
+async function loadAllRows(rows: Locator, expectedCount: number): Promise<void> {
+ while ((await rows.count()) < expectedCount) {
+ const previousCount = await rows.count();
+ await page.getByRole("button", { name: /Load more/i }).click();
+ await expect
+ .poll(() => rows.count())
+ .toBeGreaterThan(previousCount);
+ }
+ await expect(rows).toHaveCount(expectedCount);
+}
+
+async function expectBackRestored({
+ detailUrlPattern,
+ listUrl,
+ rowTestId,
+ rowCount,
+}: {
+ detailUrlPattern: RegExp;
+ listUrl: string;
+ rowTestId: "issue-list-item" | "plan-list-item";
+ rowCount: number;
+}): Promise<void> {
+ await page.goto(listUrl);
+ const rows = page.getByTestId(rowTestId);
+ await expect(rows.first()).toBeVisible({ timeout: 20_000 });
+ await loadAllRows(rows, rowCount);
+
+ const target = rows.last();
+ await target.scrollIntoViewIfNeeded();
+ const before = await readViewport(target);
+ expect(before.scrollTop).toBeGreaterThan(100);
+
+ await target.click();
+ await expect(page).toHaveURL(detailUrlPattern, { timeout: 20_000 });
+ await page.goBack();
+ await expect(page).toHaveURL(listUrl);
+ await expect(rows).toHaveCount(rowCount, { timeout: 20_000 });
+ await expect(target).toBeVisible({ timeout: 20_000 });
+
+ await expect
+ .poll(async () => {
+ const after = await readViewport(target);
+ return Math.abs(after.scrollTop - before.scrollTop);
+ })
+ .toBeLessThanOrEqual(2);
+ await expect
+ .poll(async () => {
+ const after = await readViewport(target);
+ return Math.abs(after.anchorOffset - before.anchorOffset);
+ })
+ .toBeLessThanOrEqual(2);
+ expect(await page.evaluate(() => window.scrollY)).toBe(0);
+}
+
+test.beforeAll(async ({ browser }) => {
+ env = loadTestEnv();
+ await env.api.login(env.adminEmail, env.adminPassword);
+ const projectId = env.project.split("/").pop()!;
+ const stamp = Date.now();
+ const searchToken = `scroll-restoration-${stamp}`;
+ issueListUrl = `${env.baseURL}/projects/${projectId}/issues?q=${encodeURIComponent(
+ searchToken
+ )}`;
+ planListUrl = `${env.baseURL}/projects/${projectId}/plans?q=${encodeURIComponent(
+ searchToken
+ )}`;
+
+ const setting = await env.api.getSetting("WORKSPACE_PROFILE");
+ originalExternalUrl =
+ (setting?.value as { workspaceProfile?: { externalUrl?: string } })
+ ?.workspaceProfile?.externalUrl ?? "";
+
+ const sheet = await env.api.createSheet(env.project, "SELECT 1;");
+ for (let i = 0; i < PLAN_COUNT; i++) {
+ const title = `${searchToken} issue ${i}`;
+ const plan = await env.api.createPlan(env.project, title, [
+ {
+ id: `scroll-restoration-${stamp}-${i}`,
+ targets: [env.database],
+ sheet,
+ },
+ ]);
+ const repeatedDescription = Array.from(
+ { length: (i % 4) + 1 },
+ () => `${searchToken} variable-height content`
+ ).join("\n");
+ if (i < ISSUE_COUNT) {
+ await env.api.createIssue(
+ env.project,
+ title,
+ plan.name,
+ repeatedDescription
+ );
+ }
+ }
+
+ sharedContext = await browser.newContext({
+ storageState: ".auth/state.json",
+ // Below Tailwind's sm breakpoint, the banner CTA moves onto its own row.
+ viewport: { width: 600, height: 720 },
+ });
+ page = await sharedContext.newPage();
+});
+
+test.afterAll(async () => {
+ await env.api.setWorkspaceExternalUrl(originalExternalUrl).catch(() => {});
+ await sharedContext?.close();
+});
+
+test.describe("dashboard scroll restoration", () => {
+ test.describe.configure({ mode: "serial" });
+
+ test("restores the nested main pane without a banner", async () => {
+ await env.api.setWorkspaceExternalUrl(env.baseURL);
+ await page.goto(issueListUrl);
+ await expect(
+ page.getByRole("link", { name: /Configure now/i })
+ ).toHaveCount(0);
+ await expectBackRestored({
+ detailUrlPattern: /\/projects\/[^/]+\/plans\//,
+ listUrl: issueListUrl,
+ rowTestId: "issue-list-item",
+ rowCount: ISSUE_COUNT,
+ });
+ });
+
+ test("restores every loaded page in the paginated Plans view", async () => {
+ await env.api.setWorkspaceExternalUrl(env.baseURL);
+ await expectBackRestored({
+ detailUrlPattern: /\/projects\/[^/]+\/plans\//,
+ listUrl: planListUrl,
+ rowTestId: "plan-list-item",
+ rowCount: PLAN_COUNT,
+ });
+ });
+
+ test("restores the nested main pane below a wrapped banner", async () => {
+ await env.api.setWorkspaceExternalUrl("");
+ await page.goto(issueListUrl);
+ await expect(
+ page.getByRole("link", { name: /Configure now/i }).first()
+ ).toBeVisible({ timeout: 10_000 });
+ await expectBackRestored({
+ detailUrlPattern: /\/projects\/[^/]+\/plans\//,
+ listUrl: issueListUrl,
+ rowTestId: "issue-list-item",
+ rowCount: ISSUE_COUNT,
+ });
+ });
+});