fix(web): #707 scroll guard still throws uncaught QuotaExceededError (setItem unwrap race)

[heavygee]

Summary

PR #707 (Fixes #708) is merged but insufficient. Uncaught QuotaExceededError on tsr-scroll-restoration-v1_3 still occurs in production on the current web bundle, tripping React's error boundary during normal session chat use.

This is a follow-up to the scroll-restoration quota chain:

Item	Link	What it did
Original report	#611	sessionStorage quota exhaustion on TanStack scroll key crashes SPA
Pathname key collapse	#632	getScrollRestorationKey → pathname to slow cache growth
In-memory cache gap	#708	Prune-only guard left TanStack RAM cache oversized
Merged fix	#707	Hard-reset + sync in-memory cache via scrollRestorationCache.set

The #707 fix introduced a temporary unwrap of sessionStorage.setItem that creates a race: TanStack can call scrollRestorationCache.set (which calls native setItem) while the guard is bypassed.

---

Evidence (production, not stale cache)

Observed on https://hapi.tail9944ee.ts.net after driver rebuild serving bundle index-BoTBCCy9.js (bundle contains __hapiScrollRestorationGuard — guard is installed).

Console log excerpt (session chat, 2026-05-27):

Uncaught QuotaExceededError: Failed to execute 'setItem' on 'Storage':
Setting the value of 'tsr-scroll-restoration-v1_3' exceeded the quota.
    at Object.set (index-BoTBCCy9.js:10:94081)
    at s (index-BoTBCCy9.js:10:95765)
    ...
setTimeout
scroll

Second occurrence (caught by error boundary / React DevTools hook):

QuotaExceededError: ... 'tsr-scroll-restoration-v1_3' ...
    at Object.set (index-BoTBCCy9.js:10:94081)
    at Object.fn (index-BoTBCCy9.js:10:96489)
    at Set.forEach
    at lR.emit
    at ref

Interpretation of stacks:

1. Object.set = TanStack scrollRestorationCache.set in @tanstack/router-core/src/scroll-restoration.ts (line 71: safeSessionStorage.setItem(storageKey, JSON.stringify(state))).
2. setTimeout → scroll = throttled document scroll listener in setupScrollRestoration (100ms throttle).
3. emit → ref = router onRendered subscriber also calling scrollRestorationCache.set to mark location seen.

These paths call scrollRestorationCache.set directly, not only through the wrapped sessionStorage.setItem entry point.

HAR capture confirms the same JS bundle (index-BoTBCCy9.js) was loaded for the failing session URL.

---

Root cause

web/src/lib/scrollStorageGuard.ts — writeScrollRestorationCache():

function writeScrollRestorationCache(storage, originalSetItem, updater) {
    const guardedSetItem = storage.setItem
    storage.setItem = originalSetItem   // <-- temporarily removes guard
    try {
        scrollRestorationCache?.set(updater)
    } finally {
        storage.setItem = guardedSetItem
    }
}

Called from:

• Successful prune path (wrappedSetItem, after trimmed write succeeds)
• Hard-reset path (hardResetScrollRestorationPersistedState)

Problem: While storage.setItem === originalSetItem, any concurrent TanStack scroll write (scrollRestorationCache.set from throttled scroll handler or onRendered) hits unwrapped native setItem. On quota exhaustion that throw is uncaught — it never enters wrappedSetItem's recovery logic.

The existing unit test hard reset calls scrollRestorationCache through unwrapped setItem documents that unwrap is intentional for in-memory sync, but there is no protection against concurrent TanStack writes during the unwrap window.

Additional unit test added locally (not yet upstream):

exposes unwrap window where concurrent TanStack scroll writes can throw uncaught — simulates TanStack calling setItem while writeScrollRestorationCache has unwrapped; demonstrates uncaught throw path.

---

Why #707 manual test plan item was never satisfied

PR #707 test plan included:

Manual: long session chat, scroll, navigate until storage is stressed; confirm no uncaught setItem / no white-screen error boundary

That step was unchecked at merge. Playwright stress tests against local + production hub with artificial sessionStorage fill often pass (guard handles wrapped-path recovery), but the race is intermittent and matches real operator profiles with accumulated storage + active scrolling during recovery.

---

Suggested fix directions (for follow-up PR)

Do not temporarily assign storage.setItem = originalSetItem. Options (pick one, verify with tests):

1. Patch scrollRestorationCache.set directly — update in-memory state without persisting, then persist once through the wrapped setItem (or call originalSetItem only from inside wrappedSetItem where recovery already handles failures).

2. Re-entrant lock / depth counter — if guard recovery is in progress, route all scrollRestorationCache.set persistence through wrappedSetItem even when syncing RAM (never expose native setItem on the shared sessionStorage object).

3. Upstream belt-and-suspenders — Upgrade @tanstack/react-router — upstream already has built-in scroll-restoration quota fix #683 tracks upgrading @tanstack/react-router; upstream may wrap setItem in try/catch, but HAPI should not rely on that alone given the unwrap race.

4. Reduce concurrent writers — optional: disable or debounce scroll restoration persist while hard-reset runs (harder to reason about; prefer fixing unwrap).

---

Reproduction / verification checklist for fix PR

# Unit tests (extend scrollStorageGuard.test.ts)
cd web && bun run test src/lib/scrollStorageGuard.test.ts

# Playwright stress (repo root; uses system Chrome on Linux)
HAPI_URL=https://your-hub HAPI_ACCESS_TOKEN=... \
  node scripts/dev/scroll-quota-repro-playwright.mjs \
  --session <session-id> --fill-mb 4.5

# Must add: concurrent-write race test (see test name above)
# Must pass: no pageerror/console QuotaExceededError on tsr-scroll-restoration-v1_3

Manual (required): Long-lived browser profile with stressed sessionStorage, session chat open, scroll + navigate while storage near quota — confirm zero uncaught QuotaExceededError and no React error boundary.

---

Related

• Web: QuotaExceededError on tsr-scroll-restoration-v1_3 after accumulating many session/file routes #611 — original quota crash
• fix(web): bound scroll restoration cache by collapsing keys to pathname #632 — pathname scroll key (reduces growth, does not fix guard race)
• fix(web): TanStack scroll restoration fills sessionStorage and can crash the SPA #708 — in-memory cache not reset by prune-only guard
• fix(web): reset scroll restoration when sessionStorage quota hits #707 — merged fix (insufficient — this issue)
• Upgrade @tanstack/react-router — upstream already has built-in scroll-restoration quota fix #683 — router upgrade (optional additional hardening)

Files

• web/src/lib/scrollStorageGuard.ts — bug location (writeScrollRestorationCache)
• web/src/main.tsx — installScrollRestorationGuard() at bootstrap (guard IS installed; not a boot-order bug)
• node_modules/@tanstack/router-core/src/scroll-restoration.ts — TanStack persist + scroll listeners
• web/src/lib/scrollStorageGuard.test.ts — existing + proposed race test

[github-actions]

Confirmed from current source: the unwrap window described here exists.

writeScrollRestorationCache() saves the guarded setter, assigns storage.setItem = originalSetItem, calls scrollRestorationCache?.set(updater), then restores the guarded setter in finally. That helper is reached from both the successful prune sync path and the hard-reset path, so a TanStack write during that interval would use the native setter rather than the guard.

The app does install the guard during web bootstrap, so this is not a missing-install path in the current source. The existing test suite also documents the current unwrap behavior with hard reset calls scrollRestorationCache through unwrapped setItem.

No additional info needed from the report; the next useful step is a follow-up fix that removes the temporary storage.setItem = originalSetItem exposure and adds a regression test for a concurrent/direct TanStack cache write during recovery.

Relevant code:

• web/src/lib/scrollStorageGuard.ts:21 - writeScrollRestorationCache() temporarily restores the native setItem while calling scrollRestorationCache?.set.
• web/src/lib/scrollStorageGuard.ts:52 - hard reset calls writeScrollRestorationCache() for real sessionStorage.
• web/src/lib/scrollStorageGuard.ts:117 - prune retry writes trimmed state, then syncs TanStack memory via writeScrollRestorationCache().
• web/src/lib/scrollStorageGuard.test.ts:185 - existing test asserts the hard-reset cache sync observes an unwrapped setter.
• web/src/main.tsx:38 - installScrollRestorationGuard() is called during bootstrap.
• web/src/lib/scrollRestorationKey.ts:19 - pathname-based scroll restoration key is present separately from this guard.

---

HAPI Bot

[heavygee]

Verification report (heavygee / operator stack)

This comment documents how we confirmed the #707 regression described in this issue, validated the #717 fix, and deployed it for live testing before merge.

Root cause confirmed

• Upstream main (fix(web): reset scroll restoration when sessionStorage quota hits #707 merged) still uses writeScrollRestorationCache() which temporarily assigns sessionStorage.setItem = originalSetItem while calling scrollRestorationCache.set.
• Production stacks on index-BoTBCCy9.js showed uncaught QuotaExceededError on tsr-scroll-restoration-v1_3 from TanStack's direct scrollRestorationCache.set path (scroll throttle / router onRendered) — matching the analysis in this issue and the HAPI bot comment above.

Fix (PR #717)

#717

• Removed temporary setItem unwrap entirely.
• Patches scrollRestorationCache.set at bootstrap to update in-memory state and persist only through the guarded sessionStorage.setItem wrapper.
• Adds recoveryDepth guard to prevent nested hard-reset loops.
• 14 unit tests in scrollStorageGuard.test.ts.

How we confirmed the issue (positive + negative)

Step	What	Result
1. Positive unit repro	scrollStorageGuard.legacy-regression.test.ts — embeds exact #707 writeScrollRestorationCache unwrap pattern	Legacy path throws QuotaExceededError through native setItem (guard bypassed). #717 pattern survives via guarded setter.
2. A/B browser harness	Three local hubs serving different bundles: :3008 pre-#707, :3007 upstream/main (#707), :3006 PR #717 fix	Playwright fills sessionStorage to quota (~5 MB), seeds oversized scroll map, scrolls/navigates. All builds survive automated race in harness (intermittent in prod — see #716).
3. Storage stress	scripts/dev/scroll-quota-repro-playwright.mjs — fills storage, seeds 250+ scroll routes, burst writes	Fixed build prunes scroll key (e.g. 250 routes → 2 routes / ~305 bytes). Zero uncaught quota errors on scroll key.
4. Live deploy	hapi-use-worktree → issue708 worktree (39f20af), web rebuilt (index-DJoNOil2.js), hub+runner restarted on :3006 / tailnet	Operator manual testing: no recurrence of white-screen QuotaExceededError under normal session chat use (post-#707 failure mode).

Scripts added locally (follow-up for CI / other agent)

Worktree-only (not yet in PR #717 — intended for Playwright CI gate):

• scripts/dev/scroll-quota-repro-playwright.mjs — storage fill + scroll stress
• scripts/dev/scroll-quota-prove-positive.mjs — positive repro harness (legacy unwrap simulation + async writes)
• scripts/dev/scroll-quota-ab-compare.mjs — side-by-side fixed vs upstream-main
• web/src/lib/scrollStorageGuard.legacy-regression.test.ts — definitive positive/negative unit pair

Status

• PR fix(web): scroll guard setItem unwrap race (#716) #717: OPEN, CI green (test + pr-review)
• Issue fix(web): #707 scroll guard still throws uncaught QuotaExceededError (setItem unwrap race) #716: addressed by fix(web): scroll guard setItem unwrap race (#716) #717; awaiting merge
• Operator stack: currently on fix worktree until hapi-use-driver restores daily driver soup

Recommended merge checklist

• Merge fix(web): scroll guard setItem unwrap race (#716) #717
• Add legacy-regression.test.ts + Playwright scripts to repo (CI gate)
• Manual long-profile stress test per original fix(web): reset scroll restoration when sessionStorage quota hits #707 test plan (unchecked at fix(web): reset scroll restoration when sessionStorage quota hits #707 merge — root cause of prod miss)