fix(web): recover route errors on scope change

vehicle-data-platform/docs/frontend-production-readiness.md

@@ -2,6 +2,20 @@
 
 This document records verified risks, the production controls that address them, and the next evidence to collect. It is intentionally operational: a passing build alone is not proof that the browser application is production-ready.
 
+## 2026-07-16: search-scope route error recovery
+
+The route boundary correctly isolated render failures, but its error state outlived search-parameter navigation inside the same pathname. If one alert, history or mileage scope triggered a render exception, correcting the filter or following a same-module link changed the URL while leaving the previous fallback permanently mounted. The operator had to reload the entire application or leave the module even when the next scope was valid.
+
+An errored boundary now resets only when the complete route key changes. It retries the child tree for the new pathname/search scope, while a healthy boundary continues preserving local component state across ordinary filter changes. This avoids the coarse solution of keying the whole page by every search parameter, which would remount healthy pages and discard drafts or interaction state.
+
+React documents Error Boundaries as the mechanism that replaces a crashed subtree with fallback UI and describes keys as the identity boundary for intentional state reset during navigation. The implementation applies the same identity principle conditionally to error state instead of resetting every healthy navigation:
+
+- <https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary>
+- <https://react.dev/learn/preserving-and-resetting-state>
+- <https://react.dev/reference/react/Suspense#resetting-suspense-boundaries-on-navigation>
+
+Regression coverage first renders an invalid `/alerts` search scope into the recovery page, changes only the search parameter, then proves that the error disappears and the valid scope mounts exactly once. The existing test still proves healthy search changes retain local state and do not remount.
+
 ## 2026-07-16: route-scoped mutation memory
 
 The global QueryClient previously left TanStack Query's mutation garbage-collection policy at its default. Completed writes therefore remained in the Mutation Cache after their page unmounted. Most variables are small, but the vehicle-profile synchronization workflow closes over as many as 500 parsed CSV records and performs a dry run followed by an apply mutation. Repeated administration sessions could retain several completed result graphs and their closures for minutes after leaving the page.