@native-router/core 1.5.0 → 1.7.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.
@@ -58,7 +70,9 @@ commit(router, entry.task, entry.location); // commit like a click
 - 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. 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 blockers: `setBlocker(router, fn)` registers a synchronous `(to, from) => boolean` veto over path strings, asked at the head of every `navigate`/`commit`/`commitReplace` and before a history POP lands; a vetoed navigation never starts and its promise resolves immediately (a veto is not an error — unlike a cancelled navigation, whose promise never settles), a vetoed POP is rewound with a counter-`go()` that leaves any in-flight navigation running — the classic unsaved-changes guard. `refresh` and guard redirects are never blocked
 - 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
@@ -98,6 +112,14 @@ const router = create(
 - `parseSearch(schema, search)` resolves the schema output (async validators are awaited); `parseSearchSync` is the render/guard-time flavor and rejects async validators with a clear error
 - A rejected validation throws `SearchError` (a `NativeRouterError`) carrying the raw `search` and the reported `issues` — route it through your `errorHandler` like any other resolve failure
 
+## Design principles
+
+**Navigation semantics follow the browser** — native-router aligns with browser-native navigation semantics, not with what other SPA routers happen to do. Every navigation API decision is measured against that yardstick; "a popular router has it" is not, by itself, a reason to follow. These are deliberate choices, not bugs to fix.
+
+- **An in-flight navigation keeps the old view.** The chain — guards, loaders — settles as a whole, and only then commits and pushes (`history.push`). The browser does the same: the old document stays displayed until the new one commits. A superseded or cancelled navigation is the browser's stop button / ESC — you stay on the old page and the URL never moved.
+- **Failure means an error view.** A failed resolve renders the error semantics (`errorHandler` in core, `errorComponent` in the react bindings) — the counterpart of the browser's error page. There is no "waited too long → switch to a loading view" path: the browser has no UI-layer load timeout; a timeout surfaces as a network-layer failure, i.e. an error page.
+- **Corollary: no pending-timeout escalation.** No TanStack-style `pendingMs` / in-app `pendingComponent` timeout upgrade. A pending view renders only on cold start / refresh, when there is no old view to keep.
+
 ## Install
 
 ```bash

package/dist/index.cjs

@@ -112,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(),
@@ -477,6 +484,15 @@ function preloadCacheOf(router) {
  * @param location the location to resolved
  */
 function commit(router, resolvePromise, location) {
+  // Blockers sit at the chain head: a vetoed external commit is dropped
+  // before the given task is ever awaited. The dropped task still gets
+  // a rejection handler — an orphaned failure(preload tasks re-throw
+  // NotFoundError through the default errorHandler) would otherwise
+  // surface as an unhandled rejection.
+  if (blockedBy(router, history.createPath(location))) {
+    resolvePromise.catch(util.noop);
+    return Promise.resolve();
+  }
   // Wrap the raw task so external callers share the guarded entry
   // pipeline; the entry location is the given one, as-is.
   return pushEntry(router, Promise.resolve({
@@ -531,6 +547,12 @@ function pushEntry(router, entryPromise, fromLocation, ac) {
  * @param location the location to resolved
  */
 function commitReplace(router, resolvePromise, location) {
+  // Same chain-head veto as commit: a blocked replace never starts, and
+  // the dropped task's failure is swallowed the same way.
+  if (blockedBy(router, history.createPath(location))) {
+    resolvePromise.catch(util.noop);
+    return Promise.resolve();
+  }
   return replaceEntry(router, Promise.resolve({
     location,
     task: resolvePromise
@@ -626,7 +648,9 @@ function commitBase(router, entryPromise, location, ac, onResolved) {
 /**
  * Navigate to a new path. Route guards(`redirect`/`beforeLoad`) run before
  * the view resolves; the history entry is committed on the terminal
- * location when guards redirected. The guard phase is part of the
+ * location when guards redirected. A registered blocker(see {@link
+ * setBlocker}) may veto the navigation before anything starts. The guard
+ * phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
  * guards are still running discards this navigation — and aborts the
  * chain's `signal`, so guards and loaders observing it({@link
@@ -640,6 +664,14 @@ function commitBase(router, entryPromise, location, ac, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
+  // Blockers sit at the chain head, before the controller exists: a
+  // vetoed navigation never resolves a single guard, and its promise
+  // resolves immediately — a veto is not an error, and unlike a
+  // cancelled navigation(whose promise never settles) it does settle —
+  // so the ubiquitous `void navigate(...)` call sites stay untouched.
+  // The target is asked in its committed path form(`createPath`), the
+  // same string a POP blocker sees, baseUrl included.
+  if (blockedBy(router, history.createPath(location))) return Promise.resolve();
   // One controller per navigation round: guards and view loaders of the
   // whole chain(including redirect hops) share its signal.
   const ac = new AbortController();
@@ -753,6 +785,174 @@ 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);
+}
+
+/**
+ * Navigation blocker predicate: `to` and `from` are path strings
+ * (pathname, search and hash included, built with `createPath`). Return
+ * `false` to veto the navigation. A blocker that throws counts as a
+ * veto too — a crashed gate must not open, and the exception must not
+ * escape into a history listener.
+ * @group Methods
+ * @category Router
+ */
+
+/**
+ * Registered blockers per router, in registration order. Module-level
+ * so the public {@link RouterInstance} type stays untouched; the router
+ * key is weakly held, an empty leftover set after the last release
+ * leaks nothing.
+ */
+const blockerRegistry = new WeakMap();
+
+/**
+ * Last settled history position per router, kept in sync by {@link listen}.
+ * POP blockers read it as the `from` path and the rewind base: by the
+ * time a POP listener runs, `history.location` is already the landed
+ * location, so the pre-POP position must be tracked separately.
+ */
+const lastSettled = new WeakMap();
+
+/**
+ * Pending blocker rewind per router: a rewind `go()` is in flight. The
+ * rewind's own POP must not query the blockers again — they would veto
+ * it too and ping-pong the history forever.
+ */
+const pendingRewind = new WeakMap();
+
+/**
+ * Register a navigation blocker. Every {@link navigate}, {@link commit},
+ * {@link commitReplace} and every history POP(see {@link listen}) asks
+ * the registered blockers(in registration order, first veto wins)
+ * before anything else; a vetoed navigation never starts — no guards,
+ * no loaders, no history change — and its promise resolves immediately
+ * (a veto is not an error; unlike a cancelled navigation, whose promise
+ * never settles, a vetoed one does). `refresh` and guard redirects
+ * are never blocked: a refresh re-resolves the current location, and a
+ * redirect is the guard chain's own target correction, already asked
+ * once at the chain head. A vetoed POP is rewound with a
+ * counter-`go()`; its landing re-announces the current view without
+ * cancelling an in-flight chain.
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ * @param fn blocker predicate; `to` is the target path, `from` the
+ * current path, both path strings
+ * @returns unblock - remove the blocker(idempotent)
+ */
+function setBlocker(router, fn) {
+  let set = blockerRegistry.get(router);
+  if (!set) {
+    set = new Set();
+    blockerRegistry.set(router, set);
+  }
+  set.add(fn);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    set.delete(fn);
+  };
+}
+
+/**
+ * Ask every registered blocker, in registration order. The first veto
+ * wins — `some` stops asking at it — and a blocker that throws counts
+ * as a veto: a crashed gate must not open, and the exception must not
+ * escape into a history listener.
+ */
+function vetoedBy(set, to, from) {
+  return Array.from(set).some(block => {
+    try {
+      return !block(to, from);
+    } catch {
+      return true;
+    }
+  });
+}
+
+/**
+ * Ask the blockers about a router-driven navigation. Runs before
+ * anything else, so `history.location` is still the pre-navigation
+ * `from`. Returns `true` when any blocker vetoed.
+ */
+function blockedBy(router, to) {
+  const set = blockerRegistry.get(router);
+  if (!set) return false;
+  return vetoedBy(set, to, history.createPath(router.history.location));
+}
+
+/**
+ * Ask the blockers about a history POP; rewind it when vetoed.
+ * Returns the POP's disposition for {@link listen}:
+ * - `'vetoed'`: a blocker vetoed. The caller drops the event wholesale
+ *   — no `onViewChange`, no window sync, and no `cancel()` either, so
+ *   an in-flight chain keeps running as if the POP never happened.
+ * - `'rewind'`: this POP is the landing of an earlier veto's rewind,
+ *   back on the entry the router never left. The router state did not
+ *   change, so the caller re-announces the current view without
+ *   cancelling the in-flight chain or re-syncing the window state.
+ * - `false`: not blocked; the caller handles the POP normally.
+ */
+function blockedPop(router, location, index) {
+  const {
+    history: history$1
+  } = router;
+  // A pending rewind's own landing: swallow it without a second query
+  // (a blocker that vetoes leaving a page would veto the rewind too)
+  // and report it for the no-cancel re-announce branch in the caller.
+  // Deliberately not index-matched: a user POP racing the pending
+  // rewind must never re-enter the blockers either.
+  if (pendingRewind.delete(router)) return 'rewind';
+  const set = blockerRegistry.get(router);
+  if (!set) return false;
+  // Without a settled baseline(unreachable while this listener exists:
+  // listen() seeds the tracker before registering) there is neither a
+  // `from` nor a rewind delta to work with — let the POP land rather
+  // than veto blind.
+  const settled = lastSettled.get(router);
+  if (!settled) return false;
+  const to = history.createPath(location);
+  const from = history.createPath(settled.location);
+  if (!vetoedBy(set, to, from)) return false;
+  // Rewind by the distance the POP travelled. Router-driven pushes keep
+  // the state index and the history index in lockstep, so the delta
+  // between the landed and settled state indexes doubles as the history
+  // delta. A zero delta(same-index POP between stateless external
+  // entries) cannot be rewound — `go(0)` goes nowhere — so the URL
+  // stays on the vetoed target while the router stacks and the
+  // rendered view keep the current entry.
+  const delta = index - settled.index;
+  if (delta) {
+    pendingRewind.set(router, true);
+    history$1.go(-delta);
+  }
+  return 'vetoed';
+}
+
 /**
  * Listen the history change.
  * @group Methods
@@ -765,13 +965,45 @@ function listen(router, onViewChange) {
   const {
     history: history$1
   } = router;
+
+  // Seed the settled-position tracker so a POP arriving before any other
+  // history change still reads a correct `from` and rewind delta.
+  lastSettled.set(router, {
+    index: getHistoryState(router).index,
+    location: history$1.location
+  });
   const rmListener = history$1.listen(({
     action,
     location
   }) => {
-    cancel(router);
     const state = location.state;
     const index = state?.index || 0;
+    if (action === 'POP') {
+      const blocked = blockedPop(router, location, index);
+      // A blocker veto runs before anything else: the POP is rewound
+      // with a counter-`go()`, so neither the view nor the in-flight
+      // chain may observe it.
+      if (blocked === 'vetoed') return;
+      if (blocked === 'rewind') {
+        // The rewind's landing: an entry the router never left. The
+        // stacks and the landed entry's window state are already
+        // correct — no sync replace — and no `cancel()` either: an
+        // in-flight chain must survive the bounced POP. Re-announce
+        // the current view only when a snapshot exists; an
+        // invalidate()d slot emits nothing and the host keeps its
+        // retained view, exactly like invalidate() itself — a lazy
+        // refresh here would supersede the very chain this branch
+        // protects.
+        const view = viewAt(router, index);
+        if (view) onViewChange(view);
+        lastSettled.set(router, {
+          index,
+          location
+        });
+        return;
+      }
+    }
+    cancel(router);
     const view = viewAt(router, index);
     onViewChange(view);
     if (!view) {
@@ -790,6 +1022,10 @@ function listen(router, onViewChange) {
         ...serializeStack(router)
       });
     }
+    lastSettled.set(router, {
+      index,
+      location
+    });
   });
   history$1.replace(history.createPath(history$1.location), history$1.location.state);
   return () => {
@@ -934,6 +1170,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;
@@ -946,5 +1183,6 @@ exports.refresh = refresh;
 exports.resolve = resolve;
 exports.resolveEntry = resolveEntry;
 exports.resolveTo = resolveTo;
+exports.setBlocker = setBlocker;
 exports.setOptions = setOptions;
 exports.toLocation = toLocation;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createPath, parsePath } from 'history';
 import { match as match$1 } from 'path-to-regexp';
-import { createCurrentGuard, reject, noop } from './util.mjs';
+import { noop, createCurrentGuard, reject } from './util.mjs';
 
 /* eslint-disable max-classes-per-file */
 
@@ -110,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(),
@@ -475,6 +482,15 @@ function preloadCacheOf(router) {
  * @param location the location to resolved
  */
 function commit(router, resolvePromise, location) {
+  // Blockers sit at the chain head: a vetoed external commit is dropped
+  // before the given task is ever awaited. The dropped task still gets
+  // a rejection handler — an orphaned failure(preload tasks re-throw
+  // NotFoundError through the default errorHandler) would otherwise
+  // surface as an unhandled rejection.
+  if (blockedBy(router, createPath(location))) {
+    resolvePromise.catch(noop);
+    return Promise.resolve();
+  }
   // Wrap the raw task so external callers share the guarded entry
   // pipeline; the entry location is the given one, as-is.
   return pushEntry(router, Promise.resolve({
@@ -529,6 +545,12 @@ function pushEntry(router, entryPromise, fromLocation, ac) {
  * @param location the location to resolved
  */
 function commitReplace(router, resolvePromise, location) {
+  // Same chain-head veto as commit: a blocked replace never starts, and
+  // the dropped task's failure is swallowed the same way.
+  if (blockedBy(router, createPath(location))) {
+    resolvePromise.catch(noop);
+    return Promise.resolve();
+  }
   return replaceEntry(router, Promise.resolve({
     location,
     task: resolvePromise
@@ -624,7 +646,9 @@ function commitBase(router, entryPromise, location, ac, onResolved) {
 /**
  * Navigate to a new path. Route guards(`redirect`/`beforeLoad`) run before
  * the view resolves; the history entry is committed on the terminal
- * location when guards redirected. The guard phase is part of the
+ * location when guards redirected. A registered blocker(see {@link
+ * setBlocker}) may veto the navigation before anything starts. The guard
+ * phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
  * guards are still running discards this navigation — and aborts the
  * chain's `signal`, so guards and loaders observing it({@link
@@ -638,6 +662,14 @@ function commitBase(router, entryPromise, location, ac, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
+  // Blockers sit at the chain head, before the controller exists: a
+  // vetoed navigation never resolves a single guard, and its promise
+  // resolves immediately — a veto is not an error, and unlike a
+  // cancelled navigation(whose promise never settles) it does settle —
+  // so the ubiquitous `void navigate(...)` call sites stay untouched.
+  // The target is asked in its committed path form(`createPath`), the
+  // same string a POP blocker sees, baseUrl included.
+  if (blockedBy(router, createPath(location))) return Promise.resolve();
   // One controller per navigation round: guards and view loaders of the
   // whole chain(including redirect hops) share its signal.
   const ac = new AbortController();
@@ -751,6 +783,174 @@ 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);
+}
+
+/**
+ * Navigation blocker predicate: `to` and `from` are path strings
+ * (pathname, search and hash included, built with `createPath`). Return
+ * `false` to veto the navigation. A blocker that throws counts as a
+ * veto too — a crashed gate must not open, and the exception must not
+ * escape into a history listener.
+ * @group Methods
+ * @category Router
+ */
+
+/**
+ * Registered blockers per router, in registration order. Module-level
+ * so the public {@link RouterInstance} type stays untouched; the router
+ * key is weakly held, an empty leftover set after the last release
+ * leaks nothing.
+ */
+const blockerRegistry = new WeakMap();
+
+/**
+ * Last settled history position per router, kept in sync by {@link listen}.
+ * POP blockers read it as the `from` path and the rewind base: by the
+ * time a POP listener runs, `history.location` is already the landed
+ * location, so the pre-POP position must be tracked separately.
+ */
+const lastSettled = new WeakMap();
+
+/**
+ * Pending blocker rewind per router: a rewind `go()` is in flight. The
+ * rewind's own POP must not query the blockers again — they would veto
+ * it too and ping-pong the history forever.
+ */
+const pendingRewind = new WeakMap();
+
+/**
+ * Register a navigation blocker. Every {@link navigate}, {@link commit},
+ * {@link commitReplace} and every history POP(see {@link listen}) asks
+ * the registered blockers(in registration order, first veto wins)
+ * before anything else; a vetoed navigation never starts — no guards,
+ * no loaders, no history change — and its promise resolves immediately
+ * (a veto is not an error; unlike a cancelled navigation, whose promise
+ * never settles, a vetoed one does). `refresh` and guard redirects
+ * are never blocked: a refresh re-resolves the current location, and a
+ * redirect is the guard chain's own target correction, already asked
+ * once at the chain head. A vetoed POP is rewound with a
+ * counter-`go()`; its landing re-announces the current view without
+ * cancelling an in-flight chain.
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ * @param fn blocker predicate; `to` is the target path, `from` the
+ * current path, both path strings
+ * @returns unblock - remove the blocker(idempotent)
+ */
+function setBlocker(router, fn) {
+  let set = blockerRegistry.get(router);
+  if (!set) {
+    set = new Set();
+    blockerRegistry.set(router, set);
+  }
+  set.add(fn);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    set.delete(fn);
+  };
+}
+
+/**
+ * Ask every registered blocker, in registration order. The first veto
+ * wins — `some` stops asking at it — and a blocker that throws counts
+ * as a veto: a crashed gate must not open, and the exception must not
+ * escape into a history listener.
+ */
+function vetoedBy(set, to, from) {
+  return Array.from(set).some(block => {
+    try {
+      return !block(to, from);
+    } catch {
+      return true;
+    }
+  });
+}
+
+/**
+ * Ask the blockers about a router-driven navigation. Runs before
+ * anything else, so `history.location` is still the pre-navigation
+ * `from`. Returns `true` when any blocker vetoed.
+ */
+function blockedBy(router, to) {
+  const set = blockerRegistry.get(router);
+  if (!set) return false;
+  return vetoedBy(set, to, createPath(router.history.location));
+}
+
+/**
+ * Ask the blockers about a history POP; rewind it when vetoed.
+ * Returns the POP's disposition for {@link listen}:
+ * - `'vetoed'`: a blocker vetoed. The caller drops the event wholesale
+ *   — no `onViewChange`, no window sync, and no `cancel()` either, so
+ *   an in-flight chain keeps running as if the POP never happened.
+ * - `'rewind'`: this POP is the landing of an earlier veto's rewind,
+ *   back on the entry the router never left. The router state did not
+ *   change, so the caller re-announces the current view without
+ *   cancelling the in-flight chain or re-syncing the window state.
+ * - `false`: not blocked; the caller handles the POP normally.
+ */
+function blockedPop(router, location, index) {
+  const {
+    history
+  } = router;
+  // A pending rewind's own landing: swallow it without a second query
+  // (a blocker that vetoes leaving a page would veto the rewind too)
+  // and report it for the no-cancel re-announce branch in the caller.
+  // Deliberately not index-matched: a user POP racing the pending
+  // rewind must never re-enter the blockers either.
+  if (pendingRewind.delete(router)) return 'rewind';
+  const set = blockerRegistry.get(router);
+  if (!set) return false;
+  // Without a settled baseline(unreachable while this listener exists:
+  // listen() seeds the tracker before registering) there is neither a
+  // `from` nor a rewind delta to work with — let the POP land rather
+  // than veto blind.
+  const settled = lastSettled.get(router);
+  if (!settled) return false;
+  const to = createPath(location);
+  const from = createPath(settled.location);
+  if (!vetoedBy(set, to, from)) return false;
+  // Rewind by the distance the POP travelled. Router-driven pushes keep
+  // the state index and the history index in lockstep, so the delta
+  // between the landed and settled state indexes doubles as the history
+  // delta. A zero delta(same-index POP between stateless external
+  // entries) cannot be rewound — `go(0)` goes nowhere — so the URL
+  // stays on the vetoed target while the router stacks and the
+  // rendered view keep the current entry.
+  const delta = index - settled.index;
+  if (delta) {
+    pendingRewind.set(router, true);
+    history.go(-delta);
+  }
+  return 'vetoed';
+}
+
 /**
  * Listen the history change.
  * @group Methods
@@ -763,13 +963,45 @@ function listen(router, onViewChange) {
   const {
     history
   } = router;
+
+  // Seed the settled-position tracker so a POP arriving before any other
+  // history change still reads a correct `from` and rewind delta.
+  lastSettled.set(router, {
+    index: getHistoryState(router).index,
+    location: history.location
+  });
   const rmListener = history.listen(({
     action,
     location
   }) => {
-    cancel(router);
     const state = location.state;
     const index = state?.index || 0;
+    if (action === 'POP') {
+      const blocked = blockedPop(router, location, index);
+      // A blocker veto runs before anything else: the POP is rewound
+      // with a counter-`go()`, so neither the view nor the in-flight
+      // chain may observe it.
+      if (blocked === 'vetoed') return;
+      if (blocked === 'rewind') {
+        // The rewind's landing: an entry the router never left. The
+        // stacks and the landed entry's window state are already
+        // correct — no sync replace — and no `cancel()` either: an
+        // in-flight chain must survive the bounced POP. Re-announce
+        // the current view only when a snapshot exists; an
+        // invalidate()d slot emits nothing and the host keeps its
+        // retained view, exactly like invalidate() itself — a lazy
+        // refresh here would supersede the very chain this branch
+        // protects.
+        const view = viewAt(router, index);
+        if (view) onViewChange(view);
+        lastSettled.set(router, {
+          index,
+          location
+        });
+        return;
+      }
+    }
+    cancel(router);
     const view = viewAt(router, index);
     onViewChange(view);
     if (!view) {
@@ -788,6 +1020,10 @@ function listen(router, onViewChange) {
         ...serializeStack(router)
       });
     }
+    lastSettled.set(router, {
+      index,
+      location
+    });
   });
   history.replace(createPath(history.location), history.location.state);
   return () => {
@@ -916,4 +1152,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, setBlocker, setOptions, toLocation };

package/dist/types/router.d.ts

@@ -156,7 +156,9 @@ export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(
 /**
  * Navigate to a new path. Route guards(`redirect`/`beforeLoad`) run before
  * the view resolves; the history entry is committed on the terminal
- * location when guards redirected. The guard phase is part of the
+ * location when guards redirected. A registered blocker(see {@link
+ * setBlocker}) may veto the navigation before anything starts. The guard
+ * phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
  * guards are still running discards this navigation — and aborts the
  * chain's `signal`, so guards and loaders observing it({@link
@@ -230,6 +232,57 @@ 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;
+/**
+ * Navigation blocker predicate: `to` and `from` are path strings
+ * (pathname, search and hash included, built with `createPath`). Return
+ * `false` to veto the navigation. A blocker that throws counts as a
+ * veto too — a crashed gate must not open, and the exception must not
+ * escape into a history listener.
+ * @group Methods
+ * @category Router
+ */
+export type BlockerFn = (to: string, from: string) => boolean;
+/**
+ * Register a navigation blocker. Every {@link navigate}, {@link commit},
+ * {@link commitReplace} and every history POP(see {@link listen}) asks
+ * the registered blockers(in registration order, first veto wins)
+ * before anything else; a vetoed navigation never starts — no guards,
+ * no loaders, no history change — and its promise resolves immediately
+ * (a veto is not an error; unlike a cancelled navigation, whose promise
+ * never settles, a vetoed one does). `refresh` and guard redirects
+ * are never blocked: a refresh re-resolves the current location, and a
+ * redirect is the guard chain's own target correction, already asked
+ * once at the chain head. A vetoed POP is rewound with a
+ * counter-`go()`; its landing re-announces the current view without
+ * cancelling an in-flight chain.
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ * @param fn blocker predicate; `to` is the target path, `from` the
+ * current path, both path strings
+ * @returns unblock - remove the blocker(idempotent)
+ */
+export declare function setBlocker<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, fn: BlockerFn): () => void;
 /**
  * Listen the history change.
  * @group Methods

package/package.json

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