@native-router/core 1.4.1 → 1.6.0

package/README.md

@@ -27,6 +27,18 @@ const unlisten = listen(router, (view) => {
 });
 ```
 
+`viewStack` is the SPA-navigation counterpart of the browser's [bfcache](https://web.dev/articles/bfcache). The browser snapshots whole documents so cross-document back/forward restores instantly; the router snapshots resolved views so same-document back/forward (`pushState`/POP) does too. The two layers are complementary and never overlap: a same-document navigation never enters the bfcache, and a bfcache restore does not fire `popstate`. Together with your data layer they stack as **bfcache > viewStack > queryCache**, outermost first — any restore short-circuits every inner layer with zero requests, so freshness is compensated at the edges (e.g. refetch-on-focus in the query layer).
+
+Snapshots can outlive their validity — after a logout or an account switch, the previous account's resolved views are exactly what a back POP must not restore. `invalidate(router)` drops every snapshot at once: the currently rendered view is untouched (no re-resolve, no re-render), and the next back/forward re-runs the guards and loaders of the landed entry through the same lazy path as out-of-window entries.
+
+```ts
+import {invalidate} from '@native-router/core';
+
+// After the session identity changed: keep rendering the current view,
+// but never restore a snapshot of the previous account on back/forward.
+invalidate(router);
+```
+
 ### Survives a refresh
 
 The session stack is serialized into `history.state` as a bounded tail window (`maxStackDepth`, default 100) and restored on `create`. Warm the window once after a refresh with `initHistoryStack`, and every in-window back/forward renders from cache with zero requests. Entries outside the window fall back to a single lazy re-resolve.
@@ -57,8 +69,9 @@ commit(router, entry.task, entry.location); // commit like a click
 - Framework-agnostic: bring your own `resolveView`, the view type (`V`) is yours — a string, a vdom, anything
 - Route matching via path-to-regexp: declaration order, layout routes without `path`, index/fallback children with `path: ''`, strict trailing slashes, case-sensitive, nested params merged deep over shallow
 - Route guards: static `redirect` and async `beforeLoad` on every route level, run shallow → deep; more than 10 chained redirects reject with `RedirectLoopError`
-- Cancelable async navigation: a new resolve supersedes the in-flight one (`currentGuard`); `cancel()` aborts it; a history POP cancels it too. A superseded or cancelled `navigate()` promise **never settles** — don't `await` a navigation that might be superseded
+- Cancelable async navigation: a new resolve supersedes the in-flight one (`currentGuard`); `cancel()` aborts it; a history POP cancels it too. A superseded or cancelled `navigate()` promise **never settles** — don't `await` a navigation that might be superseded. Superseding or cancelling also aborts the chain's `AbortSignal`: guards (`beforeLoad` ctx) and view loaders (`ResolveViewContext`) receive it as `ctx.signal`, so their in-flight requests stop instead of only having results dropped; `preload` resolutions are shared and therefore never aborted
 - Navigation API: `navigate`, `refresh`, `go`/`forward`/`back`, `commit`/`commitReplace`, `createHref`, `getParams`, `match`, `toLocation`, `resolve`, `resolveTo`
+- `invalidate(router)`: drop the session view snapshots in one call — the current view stays rendered (no re-resolve, no re-render) and the next back/forward re-resolves through the guards; the typical call site is right after a logout/account switch, so a POP cannot render the previous account's data or bypass guards that already ran
 - Search validation via [Standard Schema](https://standardschema.dev): a `search` schema on any route level (zod/valibot/arktype, no hard dependency), parsed with `parseSearch`/`parseSearchSync`; failures throw `SearchError`
 - `preload(router, to, {ttl})`: resolve a target through the guards ahead of time, sharing one task across concurrent callers (in-flight dedup) with a TTL, default 30s; consumed entries are dropped on commit
 - `errorHandler` hook turns resolve failures into fallback views

package/dist/index.cjs

@@ -75,6 +75,10 @@ const DEFAULT_PRELOAD_TTL = 30_000;
  *   `history index - baseIndex`; entries whose slot falls outside the
  *   memory window re-resolve lazily when landed on.
  * - `preloadCache`: router-level cache of {@link preload} results.
+ * - `resolvingController`: the in-flight chain's AbortController. It is
+ *   aborted(supersede/cancel) only while the chain is in flight; a
+ *   settled chain's controller is left alone so its contexts never
+ *   report `aborted` for a navigation that actually committed.
  */
 
 /**
@@ -108,8 +112,15 @@ function create(routes, history, resolveView, options) {
     resolveView,
     history: instanceHistory,
     locationStack,
-    // The view stack is window-relative, so it is exactly as long as the
-    // location window and stays bounded by maxStackDepth with it.
+    // The view stack is the SPA-navigation counterpart of the browser's
+    // bfcache — a resolved-view snapshot per history entry, restored with
+    // zero requests on POP. It is window-relative, so it is exactly as
+    // long as the location window and stays bounded by maxStackDepth
+    // with it; invalidate() drops these snapshots.
+    //
+    // viewStack 是 SPA 内导航对应的 bfcache——每个 history 条目一份已解析
+    // 视图快照，POP 时零请求还原。它按窗口相对位置存放，与 location 窗口
+    // 等长、随 maxStackDepth 一同封顶；invalidate() 丢弃这些快照。
     viewStack: new Array(locationStack.length).fill(null),
     baseIndex,
     preloadCache: new Map(),
@@ -274,7 +285,10 @@ function resolve(router, location) {
   } = router;
   return (matched ? resolveView(matched, {
     router,
-    location
+    location,
+    // One-shot resolves(warm-up, direct calls) are never superseded
+    // or cancelled: their loaders get a signal that never aborts.
+    signal: new AbortController().signal
   }) : Promise.reject(new NotFoundError(location.pathname))).catch(errorHandler);
 }
 
@@ -301,22 +315,37 @@ function resolveTo(router, to, state) {
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-async function resolveEntry(router, location) {
+async function resolveEntry(router, location, opts) {
   const {
     resolveView,
     errorHandler
   } = router;
+  // The chain owner(navigate/refresh) passes its controller's signal;
+  // standalone resolutions get one more controller whose signal never
+  // aborts, so downstream consumers always observe a real signal.
+  const {
+    signal = new AbortController().signal
+  } = opts ?? {};
   for (let redirects = 0;; redirects++) {
     if (redirects > MAX_REDIRECTS) {
       throw new RedirectLoopError(location.pathname);
@@ -340,7 +369,8 @@ async function resolveEntry(router, location) {
       await route.beforeLoad?.({
         router,
         location,
-        params: mergeMatchedParams(matched, i)
+        params: mergeMatchedParams(matched, i),
+        signal
       }));
       if (target) {
         location = toLocation(router, target, location.state);
@@ -354,7 +384,8 @@ async function resolveEntry(router, location) {
       location,
       task: resolveView(matched, {
         router,
-        location
+        location,
+        signal
       }).catch(errorHandler)
     };
   }
@@ -460,12 +491,12 @@ function commit(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function pushEntry(router, entryPromise, fromLocation) {
+function pushEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const nextIndex = getHistoryState(router).index + 1;
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -512,14 +543,14 @@ function commitReplace(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function replaceEntry(router, entryPromise, fromLocation) {
+function replaceEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const {
     index
   } = getHistoryState(router);
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -545,7 +576,8 @@ function replaceEntry(router, entryPromise, fromLocation) {
     });
   });
 }
-function commitBase(router, entryPromise, location, onResolved) {
+function commitBase(router, entryPromise, location, ac, onResolved) {
+  const core = router;
   const {
     currentGuard,
     onLoadingChange = util.noop
@@ -553,8 +585,16 @@ function commitBase(router, entryPromise, location, onResolved) {
   if (router.resolving) {
     // Cancel current resolve
     onLoadingChange();
+    // ...and stop its requests: the guard below discards the superseded
+    // chain's result, so its in-flight guards/loaders must not keep
+    // consuming the network until they settle on their own.
+    core.resolvingController?.abort();
   }
   router.resolving = location;
+  // External commits(plain tasks from resolveTo/preload) carry no
+  // controller; clearing the slot keeps a stale one from being aborted
+  // by a later supersede.
+  core.resolvingController = ac;
   onLoadingChange('pending');
   return (
     // The whole chain — route guards AND the view task — is guarded from
@@ -568,15 +608,19 @@ function commitBase(router, entryPromise, location, onResolved) {
       entry,
       resolvedView
     }) => {
+      // This chain settled: it is no longer in flight. Clearing the
+      // mark BEFORE onResolved matters because onResolved commits
+      // history, which synchronously re-enters cancel() through the
+      // router's own listen() handler — an already-settled chain must
+      // not be aborted(or fire a cancel signal) as if it were still
+      // running. Superseded chains park forever, so the mark is always
+      // ours to clear.
+      router.resolving = undefined;
       onResolved(resolvedView, entry);
       // The navigation consumed this resolution: drop its preload
       // cache slots so a later preload re-resolves fresh state.
       evictPreloadCache(router, entry.location);
     }).then(() => {
-      // This chain settled, so it is no longer in flight. Superseded
-      // chains park forever, so only the latest chain can reach here:
-      // the mark is always ours to clear.
-      router.resolving = undefined;
       onLoadingChange('resolved');
     }).catch(e => {
       router.resolving = undefined;
@@ -591,7 +635,10 @@ function commitBase(router, entryPromise, location, onResolved) {
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -600,19 +647,29 @@ function commitBase(router, entryPromise, location, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
-  return pushEntry(router, resolveEntry(router, location), location);
+  // One controller per navigation round: guards and view loaders of the
+  // whole chain(including redirect hops) share its signal.
+  const ac = new AbortController();
+  return pushEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function refresh(router) {
   const location = getLocation(router);
-  return replaceEntry(router, resolveEntry(router, location), location);
+  const ac = new AbortController();
+  return replaceEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
@@ -662,12 +719,22 @@ function createHref({
 }
 
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function cancel(router) {
+  const core = router;
+  // Aborting is reserved for chains that are still running: a chain that
+  // just committed re-enters cancel() synchronously through listen()'s
+  // history handler and must not have its(possibly still-rendered) view
+  // contexts aborted after the fact.
+  if (router.resolving) {
+    core.resolvingController?.abort();
+    core.resolvingController = undefined;
+  }
   // The cancelled chain parks forever, so nothing else will clear the
   // in-flight mark: drop it here, or a later navigation would fire a
   // spurious cancel signal(`onLoadingChange()`) for a dead resolve.
@@ -693,6 +760,31 @@ function initHistoryStack(router) {
   });
 }
 
+/**
+ * Drop every view snapshot of the session window. The already rendered
+ * view is untouched — no re-resolve, no re-render; only future POPs
+ * change: with no snapshot to hit, {@link listen} falls back to the same
+ * lazy re-resolve path as out-of-window entries, so the landed entry's
+ * guards(`redirect`/`beforeLoad`) and loaders run again. Call it when
+ * the snapshots stop being valid — e.g. right after a logout or an
+ * account switch, so a back POP cannot render the previous account's
+ * view or bypass guards that already ran in the session.
+ *
+ * 丢弃会话窗口内的全部视图快照。已渲染的当前视图不受影响——不重解析、
+ * 不重渲染；变化的只有后续 POP：无快照可命中时，listen 落入与窗口外条目
+ * 相同的惰性重解析路径，落点条目的守卫与加载器重新执行。快照失效时调用
+ * ——例如登出/切换账号后，后退 POP 不再渲染上一账号的视图、也不再绕过
+ * 会话内已执行过的守卫。
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ */
+function invalidate(router) {
+  // Keep the window shape: locationStack stays untouched, so getParams
+  // and the serialized window keep working — only the snapshots go.
+  router.viewStack = new Array(router.locationStack.length).fill(null);
+}
+
 /**
  * Listen the history change.
  * @group Methods
@@ -874,6 +966,7 @@ exports.getLocation = getLocation;
 exports.getParams = getParams;
 exports.go = go;
 exports.initHistoryStack = initHistoryStack;
+exports.invalidate = invalidate;
 exports.listen = listen;
 exports.match = match;
 exports.mergeMatchedParams = mergeMatchedParams;

package/dist/index.mjs

@@ -73,6 +73,10 @@ const DEFAULT_PRELOAD_TTL = 30_000;
  *   `history index - baseIndex`; entries whose slot falls outside the
  *   memory window re-resolve lazily when landed on.
  * - `preloadCache`: router-level cache of {@link preload} results.
+ * - `resolvingController`: the in-flight chain's AbortController. It is
+ *   aborted(supersede/cancel) only while the chain is in flight; a
+ *   settled chain's controller is left alone so its contexts never
+ *   report `aborted` for a navigation that actually committed.
  */
 
 /**
@@ -106,8 +110,15 @@ function create(routes, history, resolveView, options) {
     resolveView,
     history: instanceHistory,
     locationStack,
-    // The view stack is window-relative, so it is exactly as long as the
-    // location window and stays bounded by maxStackDepth with it.
+    // The view stack is the SPA-navigation counterpart of the browser's
+    // bfcache — a resolved-view snapshot per history entry, restored with
+    // zero requests on POP. It is window-relative, so it is exactly as
+    // long as the location window and stays bounded by maxStackDepth
+    // with it; invalidate() drops these snapshots.
+    //
+    // viewStack 是 SPA 内导航对应的 bfcache——每个 history 条目一份已解析
+    // 视图快照，POP 时零请求还原。它按窗口相对位置存放，与 location 窗口
+    // 等长、随 maxStackDepth 一同封顶；invalidate() 丢弃这些快照。
     viewStack: new Array(locationStack.length).fill(null),
     baseIndex,
     preloadCache: new Map(),
@@ -272,7 +283,10 @@ function resolve(router, location) {
   } = router;
   return (matched ? resolveView(matched, {
     router,
-    location
+    location,
+    // One-shot resolves(warm-up, direct calls) are never superseded
+    // or cancelled: their loaders get a signal that never aborts.
+    signal: new AbortController().signal
   }) : Promise.reject(new NotFoundError(location.pathname))).catch(errorHandler);
 }
 
@@ -299,22 +313,37 @@ function resolveTo(router, to, state) {
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-async function resolveEntry(router, location) {
+async function resolveEntry(router, location, opts) {
   const {
     resolveView,
     errorHandler
   } = router;
+  // The chain owner(navigate/refresh) passes its controller's signal;
+  // standalone resolutions get one more controller whose signal never
+  // aborts, so downstream consumers always observe a real signal.
+  const {
+    signal = new AbortController().signal
+  } = opts ?? {};
   for (let redirects = 0;; redirects++) {
     if (redirects > MAX_REDIRECTS) {
       throw new RedirectLoopError(location.pathname);
@@ -338,7 +367,8 @@ async function resolveEntry(router, location) {
       await route.beforeLoad?.({
         router,
         location,
-        params: mergeMatchedParams(matched, i)
+        params: mergeMatchedParams(matched, i),
+        signal
       }));
       if (target) {
         location = toLocation(router, target, location.state);
@@ -352,7 +382,8 @@ async function resolveEntry(router, location) {
       location,
       task: resolveView(matched, {
         router,
-        location
+        location,
+        signal
       }).catch(errorHandler)
     };
   }
@@ -458,12 +489,12 @@ function commit(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function pushEntry(router, entryPromise, fromLocation) {
+function pushEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const nextIndex = getHistoryState(router).index + 1;
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -510,14 +541,14 @@ function commitReplace(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function replaceEntry(router, entryPromise, fromLocation) {
+function replaceEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const {
     index
   } = getHistoryState(router);
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -543,7 +574,8 @@ function replaceEntry(router, entryPromise, fromLocation) {
     });
   });
 }
-function commitBase(router, entryPromise, location, onResolved) {
+function commitBase(router, entryPromise, location, ac, onResolved) {
+  const core = router;
   const {
     currentGuard,
     onLoadingChange = noop
@@ -551,8 +583,16 @@ function commitBase(router, entryPromise, location, onResolved) {
   if (router.resolving) {
     // Cancel current resolve
     onLoadingChange();
+    // ...and stop its requests: the guard below discards the superseded
+    // chain's result, so its in-flight guards/loaders must not keep
+    // consuming the network until they settle on their own.
+    core.resolvingController?.abort();
   }
   router.resolving = location;
+  // External commits(plain tasks from resolveTo/preload) carry no
+  // controller; clearing the slot keeps a stale one from being aborted
+  // by a later supersede.
+  core.resolvingController = ac;
   onLoadingChange('pending');
   return (
     // The whole chain — route guards AND the view task — is guarded from
@@ -566,15 +606,19 @@ function commitBase(router, entryPromise, location, onResolved) {
       entry,
       resolvedView
     }) => {
+      // This chain settled: it is no longer in flight. Clearing the
+      // mark BEFORE onResolved matters because onResolved commits
+      // history, which synchronously re-enters cancel() through the
+      // router's own listen() handler — an already-settled chain must
+      // not be aborted(or fire a cancel signal) as if it were still
+      // running. Superseded chains park forever, so the mark is always
+      // ours to clear.
+      router.resolving = undefined;
       onResolved(resolvedView, entry);
       // The navigation consumed this resolution: drop its preload
       // cache slots so a later preload re-resolves fresh state.
       evictPreloadCache(router, entry.location);
     }).then(() => {
-      // This chain settled, so it is no longer in flight. Superseded
-      // chains park forever, so only the latest chain can reach here:
-      // the mark is always ours to clear.
-      router.resolving = undefined;
       onLoadingChange('resolved');
     }).catch(e => {
       router.resolving = undefined;
@@ -589,7 +633,10 @@ function commitBase(router, entryPromise, location, onResolved) {
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -598,19 +645,29 @@ function commitBase(router, entryPromise, location, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
-  return pushEntry(router, resolveEntry(router, location), location);
+  // One controller per navigation round: guards and view loaders of the
+  // whole chain(including redirect hops) share its signal.
+  const ac = new AbortController();
+  return pushEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function refresh(router) {
   const location = getLocation(router);
-  return replaceEntry(router, resolveEntry(router, location), location);
+  const ac = new AbortController();
+  return replaceEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
@@ -660,12 +717,22 @@ function createHref({
 }
 
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function cancel(router) {
+  const core = router;
+  // Aborting is reserved for chains that are still running: a chain that
+  // just committed re-enters cancel() synchronously through listen()'s
+  // history handler and must not have its(possibly still-rendered) view
+  // contexts aborted after the fact.
+  if (router.resolving) {
+    core.resolvingController?.abort();
+    core.resolvingController = undefined;
+  }
   // The cancelled chain parks forever, so nothing else will clear the
   // in-flight mark: drop it here, or a later navigation would fire a
   // spurious cancel signal(`onLoadingChange()`) for a dead resolve.
@@ -691,6 +758,31 @@ function initHistoryStack(router) {
   });
 }
 
+/**
+ * Drop every view snapshot of the session window. The already rendered
+ * view is untouched — no re-resolve, no re-render; only future POPs
+ * change: with no snapshot to hit, {@link listen} falls back to the same
+ * lazy re-resolve path as out-of-window entries, so the landed entry's
+ * guards(`redirect`/`beforeLoad`) and loaders run again. Call it when
+ * the snapshots stop being valid — e.g. right after a logout or an
+ * account switch, so a back POP cannot render the previous account's
+ * view or bypass guards that already ran in the session.
+ *
+ * 丢弃会话窗口内的全部视图快照。已渲染的当前视图不受影响——不重解析、
+ * 不重渲染；变化的只有后续 POP：无快照可命中时，listen 落入与窗口外条目
+ * 相同的惰性重解析路径，落点条目的守卫与加载器重新执行。快照失效时调用
+ * ——例如登出/切换账号后，后退 POP 不再渲染上一账号的视图、也不再绕过
+ * 会话内已执行过的守卫。
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ */
+function invalidate(router) {
+  // Keep the window shape: locationStack stays untouched, so getParams
+  // and the serialized window keep working — only the snapshots go.
+  router.viewStack = new Array(router.locationStack.length).fill(null);
+}
+
 /**
  * Listen the history change.
  * @group Methods
@@ -856,4 +948,4 @@ function isThenable(value) {
   return typeof value?.then === 'function';
 }
 
-export { NativeRouterError, NotFoundError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, listen, match, mergeMatchedParams, navigate, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setOptions, toLocation };
+export { NativeRouterError, NotFoundError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, invalidate, listen, match, mergeMatchedParams, navigate, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setOptions, toLocation };

package/dist/types/router.d.ts

@@ -88,18 +88,29 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-export declare function resolveEntry<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, location: Location): Promise<ResolvedEntry<V>>;
+export declare function resolveEntry<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, location: Location, opts?: {
+    signal?: AbortSignal;
+}): Promise<ResolvedEntry<V>>;
 /**
  * Resolve a target through the route guards(`redirect`/`beforeLoad`) and
  * cache the result at the router level, keyed by `pathname + search`.
@@ -147,7 +158,10 @@ export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -157,7 +171,9 @@ export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(
 export declare function navigate<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, to: string, state?: any): Promise<void>;
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -195,7 +211,8 @@ export declare function back<R extends BaseRoute = BaseRoute, V = any>(router: R
  */
 export declare function createHref<R extends BaseRoute = BaseRoute, V = any>({ baseUrl, history }: RouterInstance<R, V>, to: string): string;
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -213,6 +230,26 @@ export declare function cancel<R extends BaseRoute = BaseRoute, V = any>(router:
  * @param router router instance
  */
 export declare function initHistoryStack<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>): Promise<void>;
+/**
+ * Drop every view snapshot of the session window. The already rendered
+ * view is untouched — no re-resolve, no re-render; only future POPs
+ * change: with no snapshot to hit, {@link listen} falls back to the same
+ * lazy re-resolve path as out-of-window entries, so the landed entry's
+ * guards(`redirect`/`beforeLoad`) and loaders run again. Call it when
+ * the snapshots stop being valid — e.g. right after a logout or an
+ * account switch, so a back POP cannot render the previous account's
+ * view or bypass guards that already ran in the session.
+ *
+ * 丢弃会话窗口内的全部视图快照。已渲染的当前视图不受影响——不重解析、
+ * 不重渲染；变化的只有后续 POP：无快照可命中时，listen 落入与窗口外条目
+ * 相同的惰性重解析路径，落点条目的守卫与加载器重新执行。快照失效时调用
+ * ——例如登出/切换账号后，后退 POP 不再渲染上一账号的视图、也不再绕过
+ * 会话内已执行过的守卫。
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ */
+export declare function invalidate<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>): void;
 /**
  * Listen the history change.
  * @group Methods

package/dist/types/types.d.ts

@@ -79,32 +79,61 @@ export type SearchInput = Record<string, string | string[]>;
  * @category Route
  */
 export type SearchOutputOf<S> = S extends StandardSchemaV1<any, infer Output> ? Output : never;
+/** ASCII approximation of path-to-regexp's `ID_Start`. */
+type ParamStartChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '_' | '$';
+/** ASCII approximation of path-to-regexp's `ID_Continue`. */
+type ParamContinueChar = ParamStartChar | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type ParamValueOf<Name extends string, Mode extends 'param' | 'wildcard'> = Mode extends 'wildcard' ? {
+    [K in Name]: string[];
+} : {
+    [K in Name]: string;
+};
+/**
+ * Scan a segment char by char: `\\x` escapes the next char, `:name`
+ * starts a param, `*name` starts a wildcard, anything else is static
+ * text.
+ */
+type SegmentParamsOf<Seg extends string> = Seg extends `${infer Char}${infer Rest}` ? Char extends '\\' ? Rest extends `${string}${infer Tail}` ? SegmentParamsOf<Tail> : {} : Char extends ':' | '*' ? Rest extends `${infer First}${infer Rest2}` ? First extends ParamStartChar ? ParamNameOf<Rest2, First, Char extends '*' ? 'wildcard' : 'param'> : {} : {} : SegmentParamsOf<Rest> : {};
+/** Consume the identifier run started by a `ParamStartChar`. */
+type ParamNameOf<Rest extends string, Name extends string, Mode extends 'param' | 'wildcard'> = Rest extends `${infer Char}${infer Tail}` ? Char extends ParamContinueChar ? ParamNameOf<Tail, `${Name}${Char}`, Mode> : Char extends '?' | '(' | ')' | '[' | ']' | '+' | '!' | '*' ? {} : ParamValueOf<Name, Mode> & SegmentParamsOf<Rest> : ParamValueOf<Name, Mode>;
 /**
- * Params contributed by a single path segment: `:name` is required,
- * `:name?` is optional, anything else(static or wildcard) contributes
- * nothing.
+ * Params contributed by a single path segment, modeled after the
+ * path-to-regexp **8.4.2** string grammar(the version this package
+ * locks):
+ *
+ * - `:name` contributes a required `string` param wherever it appears
+ *   in the segment — `:id`, `page-:id`, `:from-:to` all work at
+ *   runtime and are modeled;
+ * - `*name` contributes a `string[]` wildcard param(the runtime
+ *   matcher splits a wildcard value by `/`).
+ *
+ * Everything else contributes nothing:
  *
- * Only the segment-exact forms of the path-to-regexp 6 syntax are
- * modeled. Prefix/suffix params(`/page-:id`), repetitions(`:id*`,
- * `:id+`) and custom regexes(`:id(\\d+)`) are matched at runtime but
- * not modeled here — they simply contribute no keys.
+ * - the v6-era suffixes `:id?`, `:id+`, `:id*`, `:id(\\d+)` are **not**
+ *   runtime syntax in 8.4.2 — the matcher throws a `PathError` when the
+ *   path is compiled, so they are deliberately left unmodeled instead
+ *   of endorsing a path that crashes;
+ * - quoted names(`:"x y"`) and non-ASCII identifier chars are not
+ *   modeled(the scanner only knows ASCII identifiers).
+ *
+ * Note: wildcard params surface as `string[]` at runtime while the
+ * router-level types(`Matched.params`,
+ * {@link GuardContext.params}) are `Record<string, string>` — the
+ * router does not model wildcard params.
  * @group Types
  * @category Route
  */
-export type PathParamsOf<Seg extends string> = Seg extends `:${infer Name}?` ? {
-    [K in Name & string]?: string;
-} : Seg extends `:${infer Name}` ? {
-    [K in Name & string]: string;
-} : {};
+export type PathParamsOf<Seg extends string> = SegmentParamsOf<Seg>;
 /**
  * Extract the params shape of a route path pattern. Splits the pattern
  * into `/`-separated segments and intersects the params of each, e.g.
- * `ExtractPathParams<'/users/:id/posts/:postId?'>` is
- * `{id: string} & {postId?: string}`.
+ * `ExtractPathParams<'/users/:id/files/*rest'>` is
+ * `{id: string} & {rest: string[]}`.
  *
- * Within the modeled path-to-regexp 6 syntax scope(see
- * {@link PathParamsOf}); wildcards(`*`) and static segments are
- * ignored. Distributes over unions of patterns.
+ * Within the modeled path-to-regexp 8.4.2 syntax scope(see
+ * {@link PathParamsOf}); static segments are ignored and v6-era
+ * suffixes(`:id?`, `:id(\\d+)`, …) contribute nothing because the
+ * runtime matcher rejects them. Distributes over unions of patterns.
  * @group Types
  * @category Route
  */
@@ -118,6 +147,13 @@ export type GuardContext<R extends BaseRoute = BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
     params: Record<string, string>;
+    /**
+     * Aborted when this navigation is superseded by a newer one or
+     * cancelled(see {@link RouterInstance.cancelAll cancel}); pass it to
+     * the guard's requests(e.g. `fetch(url, {signal})`) so a discarded
+     * navigation stops consuming the network.
+     */
+    signal: AbortSignal;
 };
 export type BaseRoute<T = any> = {
     path?: Path;
@@ -147,6 +183,12 @@ export type Matched<R extends BaseRoute = BaseRoute> = {
 export type ResolveViewContext<R extends BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
+    /**
+     * The navigation chain's abort signal: aborted when this navigation is
+     * superseded by a newer one or cancelled. Frameworks forward it into
+     * their data contexts so loaders can abort their requests.
+     */
+    signal: AbortSignal;
 };
 export type ResolveView<R extends BaseRoute, V> = (matched: Matched<R>[], ctx: ResolveViewContext<R>) => Promise<V>;
 export type Options<V> = {
@@ -191,3 +233,4 @@ export type RouterInstance<R extends BaseRoute, V = any> = {
     cancelAll(): void;
     resolving?: Location;
 } & RequiredOf<Options<V>, 'baseUrl' | 'maxStackDepth'>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",