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.

[randomdevpete]

Held for a closer look, and taken off the critical path — nothing is blocked behind it now. Three things to settle before this lands.

1. The stale-read trade. useRequiredRoute's docblock records that without the Navigation API an external history.pushState can leave the read one render stale, so the assertion throws where useRoute would render stale values. Turning a soft staleness into a thrown error is the worse failure of the two, and it fires only in the environments least able to avoid it. Worth a closer look at whether there is a better mechanism. Also worth checking against #99/#120's design record, which states Firefox 147 and Safari 26.2 ship the Navigation API — this comment says they don't, so one of the two is out of date.

2. The comments break the project's rules in several places. Root cause is not this branch: CLAUDE.md points at docs/coding-style.md, which has never existed in the repo, so there were no rules here to follow. Filed separately; this branch gets a comment pass once that document exists.

3. DESIGN-NOTES.md. Questioned on value — it is not user-facing (not rendered by the docs site, not in the published tarball, referenced from one code comment) and restates what the commits already say. Filed separately, with promoting the parts that teach something into a design-principles page on the site as the option to weigh.

Rebased onto current master along the way, so this is reviewable as it stands.