fix(web): bound scroll restoration cache by collapsing keys to pathname

[junmo-kim]

Problem

After navigating through several sessions, the browser console shows:

QuotaExceededError: Failed to execute 'setItem' on 'Storage':
Setting the value of 'tsr-scroll-restoration-v1_3' exceeded the quota.

This blocks the React commit and requires a hard reload to recover. Fixes #611.

The root cause is that TanStack Router's default getScrollRestorationKey returns location.state.__TSR_key, a unique string generated for every history entry. Each navigation creates a new cache entry, so the sessionStorage value grows without bound until it exhausts the ~5 MB limit.

(Note: the linked issue mentions localStorage; the actual storage is sessionStorage. Same Web Storage quota applies, so the symptom is identical.)

Solution

Pass a getScrollRestorationKey function to createRouter that collapses the key to location.pathname. This reduces cache growth from O(every navigation) to O(distinct pathnames visited), which keeps a typical session comfortably under the quota.

Trade-offs

Revisiting the same pathname (e.g. switching back to a session) now restores the last scroll position for that route — generally nicer UX than always starting at the top. URLs that differ only in search params share a single cache entry, so per-query scroll positions are no longer tracked. In particular, on /sessions/$sessionId/file?path=..., switching between files within a session no longer remembers a per-file scroll position; the diff view always opens at the top.

Tests

• bun run typecheck: clean.
• bun run test:web: 60 files / 417 tests passed.
• Manually verified in an isolated hub + Vite stack: with the default key, 7 navigations produced 15 cache entries (random __TSR_key strings); with the pathname key, 28+ navigations across 5 sessions produced 6 entries (one per distinct pathname). Filling sessionStorage to the quota beforehand no longer throws on subsequent navigation.

Follow-up

A boot-time size guard (clearing the key when the existing cache already exceeds a threshold) would help users whose sessionStorage is already at quota before this fix is deployed. A per-route key scheme that keeps query params for routes whose identity is search-param-defined (e.g. the file diff view) would restore per-file scroll memory. Both are out of scope for this PR.

[github-actions]

Findings

• [Major] Search-param routes now share one scroll bucket — /sessions/$sessionId/file uses ?path=... as the file identity (web/src/router.tsx:578, web/src/routes/sessions/file.tsx:407), but the new key returns only location.pathname. After visiting/scrolled file A, opening/scrolled file B, then using browser Back to file A, TanStack restores the shared /sessions/<id>/file bucket instead of file A's position. That regresses scroll restoration for file/diff navigation while fixing the quota issue. web/src/router.tsx:673
  Suggested fix:

  getScrollRestorationKey: (location) => {
      const search = location.search as { path?: unknown; tab?: unknown; machineId?: unknown }
      if (location.pathname.endsWith('/file') && typeof search.path === 'string') {
          return `${location.pathname}?path=${search.path}`
      }
      if (location.pathname.endsWith('/files') && search.tab === 'directories') {
          return `${location.pathname}?tab=directories`
      }
      return location.pathname
  },

  Keep the quota fix by pairing the semantic keys above with a capped/LRU scroll cache or quota-safe storage pruning, rather than collapsing every search-param route to the same content bucket.

Questions

• None.

Summary

• Review mode: initial
• One issue found: the cache key is bounded, but it also merges distinct file-route contents that are differentiated only by search params.

Testing

• Not run (automation; review-only, PR code not executed).

HAPI Bot

[github-actions]

Findings

• [Major] File scroll keys merge staged and unstaged diffs — /sessions/$sessionId/file carries staged through search validation and uses it in the diff query (web/src/router.tsx:573, web/src/routes/sessions/file.tsx:416), but the new key only includes path. Opening the staged and unstaged views for the same file now writes both scroll positions to the same bucket, so Back/Forward can restore the other diff's position.
  Suggested fix:

  if (FILE_ROUTE.test(location.pathname) && typeof search.path === 'string') {
      const stagedSuffix = search.staged === true ? '&staged=true' : ''
      return `${location.pathname}?path=${search.path}${stagedSuffix}`
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The prior file-path finding is mostly addressed, but the file route still merges staged and unstaged diff identities for the same path.

Testing

• Not run (automation; review-only, PR code not executed).

HAPI Bot

[github-actions]

Findings

• [Minor] /browse scroll state is shared across machine-scoped views — /browse validates machineId from search and passes it into WorkspaceBrowser, so different machines can render completely different directory lists for the same pathname (web/src/router.tsx:486, web/src/router.tsx:633). The new fallback key stores all of those scroll positions under /browse, so opening one machine's browser can restore the scroll offset from another machine's workspace list.
  Suggested fix:

  const search = location.search as { path?: unknown; staged?: unknown; tab?: unknown; machineId?: unknown }
  if (location.pathname === '/browse' && typeof search.machineId === 'string') {
      return `${location.pathname}?machineId=${search.machineId}`
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The prior staged/unstaged file diff collision is fixed. Remaining risk is one search-scoped route still falling through to the pathname-only bucket.

Testing

• Not run (automation; review-only, PR code not executed).

HAPI Bot

[github-actions]

Findings

• None.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• No issues found in the updated diff. The prior /browse machine-scoped scroll key issue is addressed, and the new guard/key tests cover the reviewed edge cases. Residual risk: the guard depends on TanStack Router's internal tsr-scroll-restoration-v1_3 storage key, so a future router upgrade could require updating that constant.

Testing

• Not run (automation; review-only, PR code not executed).

HAPI Bot