fix(web): TanStack scroll restoration fills sessionStorage and can crash the SPA

[heavygee]

Summary

Under load (long sessions, many navigations, heavy scroll targets), sessionStorage.setItem for TanStack Router key tsr-scroll-restoration-v1_3 can throw QuotaExceededError / DOMException-shaped quota errors. That bubbles into React and can take down the full UI with:

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

HAPI already wraps sessionStorage.setItem in web/src/lib/scrollStorageGuard.ts (see #611), but a prune-only recovery is insufficient: TanStack keeps the full scroll map in memory; trimming the JSON written to disk does not shrink the in-RAM cache, so the next persist can throw again immediately.

Proposed direction (implemented in PR)

• PR: fix(web): reset scroll restoration when sessionStorage quota hits #707
• On persist failure for the scroll restoration key (after prune+retry fails, or invalid JSON), clear storage and reset TanStack scrollRestorationCache when guarding real window.sessionStorage (unit tests use a mock Storage and skip the library reset).
• Treat any write failure on that key as recoverable for the scroll cache (not only instanceof Error quota shapes).

Follow-up optional hardening: bump @tanstack/react-router / @tanstack/router-core when upstream wraps setItem in try/catch (belt and suspenders).

Suggested verification

1. From a checkout that includes the merged fix: cd web && bun run test src/lib/scrollStorageGuard.test.ts && bun run typecheck
2. Manual: long session chat, scroll, navigate until storage is stressed; confirm no uncaught setItem / no white-screen error boundary.

[github-actions]

Confirmed in the current tree: HAPI installs a TanStack scroll restoration storage guard, but the guard is storage-only today. It catches quota-shaped errors for tsr-scroll-restoration-v1_3, prunes the serialized JSON to 50 newest entries, retries once, and removes the storage key if parsing or retry fails. I did not find any current code that resets TanStack Router's in-memory scrollRestorationCache, so the reported prune-only limitation is still a real gap in this codebase.

Relevant code:

• web/src/main.tsx:38 - installs installScrollRestorationGuard() during app bootstrap.
• web/src/router.tsx:714 - enables TanStack Router scrollRestoration.
• web/src/router.tsx:715 - uses HAPI's custom getScrollRestorationKey.
• web/src/lib/scrollRestorationKey.ts:9 - documents that TanStack's default history-entry key can grow without bound.
• web/src/lib/scrollStorageGuard.ts:41 - wraps sessionStorage.setItem.
• web/src/lib/scrollStorageGuard.ts:46 - only handles the TanStack scroll key when the thrown value matches isQuotaError.
• web/src/lib/scrollStorageGuard.ts:54 - prunes to the newest 50 entries before retry.
• web/src/lib/scrollStorageGuard.ts:62 - invalid JSON removes the storage key.
• web/src/lib/scrollStorageGuard.ts:66 - retry failure removes the storage key.
• web/src/lib/scrollStorageGuard.ts:82 - quota detection currently requires err instanceof Error with quota error names.
• web/src/lib/scrollStorageGuard.test.ts:54 - test coverage verifies prune-and-retry behavior.
• web/src/lib/scrollStorageGuard.test.ts:88 - test coverage verifies key removal when the retried write still throws.

---

HAPI Bot