feat(jarl): 685 — requireMatch / useRequiredRoute, a checked assertion for a route read known to match

[randomdevpete]

What

• requireMatch(route, name?) in jarl-atoms: narrows a RouteReturn<T> to the new exported MatchedRoute<T> (Extract<RouteReturn<T>, { match: true }>), throwing "<name> does not match the current location" otherwise.
• useRequiredRoute(routeAtom, name?) in jarl-react: the React form — useRoute for a route atom whose match is guaranteed by where the component renders.
• isActive now returns the shared MatchedRoute<T> predicate type instead of hand-writing the same Extract.
• DataGridApp.tsx's defaults/defaultFilter fallback — real code that existed only to satisfy the type checker — is gone from both rowsAtom and the component, replaced by requireMatch/useRequiredRoute.

Why not a derived "this chain always matches" type

Full write-up in packages/jarl-atoms/DESIGN-NOTES.md. Three reasons, in order of how hard they kill it:

1. It doesn't cover the case that motivated it. DataGridApp roots on createRootAtom({ basePath: "/demos/data-grid" }), and stripBasePath reports match: false outside that prefix — so a sound derivation has to call the chain partial. What actually guarantees the match is the <Route on={dataGridDemoRoute}> in App.tsx: knowledge that lives above the atoms and can't be recovered from them.
2. The provable class is nearly empty. Every path route can miss by construction, so a chain would only qualify if it binds nothing off the path at all.
3. transformRouteAtom can't report its own totality without changing how Return is inferred for every existing caller.

A manual alwaysMatches: true flag was rejected too, on soundness — it asserts what nothing checks, so a wrong guarantee surfaces as undefined field access far from the claim. requireMatch is the same caller-made assertion, but checked: right where it's wrong, it throws instead of silently going stale.

The one-render-stale hazard

Without the Navigation API (Firefox/Safari today, and jsdom), locationAtom falls back to listening on popstate, which stays silent for a history.pushState made outside jarl. A route read can therefore be one render stale after such a call. Where the old RouteReturn.values ?? fallback pattern just rendered stale-but-plausible data through that window, useRequiredRoute turns it into a thrown error mid-render.

Verdict: acceptable as designed, not worth softening. Ticket 778 (this PR's base) switches locationAtom's subscription to the Navigation API's currententrychange event wherever it's available, and that event fires for every same-document navigation regardless of what triggered it, including a pushState made outside jarl — so on any browser with the Navigation API (Chrome, Edge) the window is closed entirely, not just narrowed. The exposure is real only on Firefox/Safari/jsdom, and even there it's bounded to exactly one render.

Making useRequiredRoute swallow one stale frame (return the previous match instead of throwing) was considered and rejected: it can't distinguish "stale because of an external pushState" from "stale because this component is genuinely rendering somewhere its route no longer matches," which is precisely the invariant this hook exists to check. Softening it here would silently defeat the same soundness argument that ruled out alwaysMatches: true. Documented instead — the useRequiredRoute docblock now states the hazard and the mitigation (navigate through jarl) directly.

Notes

• Not breaking: requireMatch, useRequiredRoute and the exported MatchedRoute<T> type are pure additions; isActive's changed return-type annotation (MatchedRoute<T> in place of the hand-written Extract<...>) is the same structural type, not a behavioural or type change for callers. Two feat commits, minor bump, no !.
• No style-guide exceptions taken in this diff.
• Stacked on feat(jarl-atoms): 778 — veto any navigation with navigationGuardAtom #99 (task-778-no-navigation-blocking-api), itself on feat(atoms)!: 675 — one asyncRouteAtom API for async route data #98 (task-675-...) — base this PR against task-778-no-navigation-blocking-api, not the default branch.

Closes ticket 685.