Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.mdnew file mode 100644index 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.tsxindex 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.tsxindex 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 (<divdata-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({<RouterLinkto={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({<RouterLinkto={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.tsxindex 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.tsxindex 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 (<divclassName={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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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 filterconst 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.tsxnew file mode 100644index 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.tsxindex 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 optionsconst 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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}><divref={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"><divclassName={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. */}<headerclassName={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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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 filterconst 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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,+ });+ });+});