@native-router/core 1.5.0 → 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.
@@ -59,6 +71,7 @@ commit(router, entry.task, entry.location); // commit like a click
 - 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 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

@@ -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(),
@@ -753,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
@@ -934,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

@@ -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(),
@@ -751,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
@@ -916,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

@@ -230,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/package.json

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