@native-router/core 1.6.0 → 1.8.0

package/README.md

@@ -70,6 +70,7 @@ 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`
@@ -107,10 +108,19 @@ const router = create(
 );
 ```
 
-- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query are arrays — which is also the input every schema validates
-- `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
+- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query string are arrays — which is also the input every schema validates
+- `parseSearch(schema, search)` resolves the schema output (async validators are awaited); `parseSearchSync` is the render-time flavor and rejects async validators with a clear error
+- Guards: `beforeLoad` receives the level's parsed search as `ctx.search` — the schema output (parsed with `parseSearch`, so async validators work), or the degraded input on schema-less levels; an invalid search fails the resolution through the `errorHandler` channel like a data-phase search 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

@@ -45,6 +45,84 @@ function formatIssuePath(path) {
   return `${keys.join('.')}: `;
 }
 
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -327,6 +405,11 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -364,14 +447,37 @@ async function resolveEntry(router, location, opts) {
       } = matched[i];
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params: mergeMatchedParams(matched, i),
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -484,6 +590,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({
@@ -538,6 +653,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
@@ -633,7 +754,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
@@ -647,6 +770,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();
@@ -785,6 +916,149 @@ function invalidate(router) {
   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
@@ -797,13 +1071,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) {
@@ -822,6 +1128,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 () => {
@@ -872,84 +1182,6 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-/**
- * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
- * input object consumed by {@link StandardSchemaV1 search schemas}:
- * single-valued keys are strings, keys repeated in the query string are
- * arrays of their values. An empty search is `{}`.
- *
- * This is also the degraded shape every search API falls back to when no
- * schema is given.
- * @group Methods
- * @category Route
- * @param search the raw `location.search` string, with or without `?`
- * @returns the input object for schema validation
- */
-function parseSearchInput(search) {
-  const input = {};
-  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
-  new URLSearchParams(search).forEach((value, key) => {
-    const prev = input[key];
-    if (prev === undefined) {
-      input[key] = value;
-    } else if (Array.isArray(prev)) {
-      prev.push(value);
-    } else {
-      input[key] = [prev, value];
-    }
-  });
-  return input;
-}
-
-/**
- * Validate a search string with a {@link StandardSchemaV1} schema — any
- * zod/valibot/arktype schema works, no hard dependency. The string is
- * first degraded via {@link parseSearchInput}, then parsed by the schema,
- * so schemas can coerce(`'2'` → `2`) and normalize along the way.
- *
- * Async schemas(`validate` returning a promise) are awaited.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- */
-async function parseSearch(schema, search) {
-  const result = await schema['~standard'].validate(parseSearchInput(search));
-  if (result.issues) throw new SearchError(search, result.issues);
-  // The schema's declared output; the loose `StandardSchemaV1` default
-  // degrades to `unknown`.
-  return result.value;
-}
-
-/**
- * Synchronous flavor of {@link parseSearch}, for render-time reads(see
- * `useSearch` of `@native-router/react`) and route guards.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema — must validate synchronously
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- * @throws when the schema validates asynchronously; use {@link parseSearch}
- * for async schemas instead
- */
-function parseSearchSync(schema, search) {
-  const result = schema['~standard'].validate(parseSearchInput(search));
-  if (isThenable(result)) {
-    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
-  }
-  if (result.issues) throw new SearchError(search, result.issues);
-  // See parseSearch for the cast rationale.
-  return result.value;
-}
-function isThenable(value) {
-  return typeof value?.then === 'function';
-}
-
 exports.NativeRouterError = NativeRouterError;
 exports.NotFoundError = NotFoundError;
 exports.RedirectLoopError = RedirectLoopError;
@@ -979,5 +1211,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 */
 
@@ -43,6 +43,84 @@ function formatIssuePath(path) {
   return `${keys.join('.')}: `;
 }
 
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -325,6 +403,11 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -362,14 +445,37 @@ async function resolveEntry(router, location, opts) {
       } = matched[i];
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params: mergeMatchedParams(matched, i),
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -482,6 +588,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({
@@ -536,6 +651,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
@@ -631,7 +752,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
@@ -645,6 +768,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();
@@ -783,6 +914,149 @@ function invalidate(router) {
   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
@@ -795,13 +1069,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) {
@@ -820,6 +1126,10 @@ function listen(router, onViewChange) {
         ...serializeStack(router)
       });
     }
+    lastSettled.set(router, {
+      index,
+      location
+    });
   });
   history.replace(createPath(history.location), history.location.state);
   return () => {
@@ -870,82 +1180,4 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-/**
- * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
- * input object consumed by {@link StandardSchemaV1 search schemas}:
- * single-valued keys are strings, keys repeated in the query string are
- * arrays of their values. An empty search is `{}`.
- *
- * This is also the degraded shape every search API falls back to when no
- * schema is given.
- * @group Methods
- * @category Route
- * @param search the raw `location.search` string, with or without `?`
- * @returns the input object for schema validation
- */
-function parseSearchInput(search) {
-  const input = {};
-  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
-  new URLSearchParams(search).forEach((value, key) => {
-    const prev = input[key];
-    if (prev === undefined) {
-      input[key] = value;
-    } else if (Array.isArray(prev)) {
-      prev.push(value);
-    } else {
-      input[key] = [prev, value];
-    }
-  });
-  return input;
-}
-
-/**
- * Validate a search string with a {@link StandardSchemaV1} schema — any
- * zod/valibot/arktype schema works, no hard dependency. The string is
- * first degraded via {@link parseSearchInput}, then parsed by the schema,
- * so schemas can coerce(`'2'` → `2`) and normalize along the way.
- *
- * Async schemas(`validate` returning a promise) are awaited.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- */
-async function parseSearch(schema, search) {
-  const result = await schema['~standard'].validate(parseSearchInput(search));
-  if (result.issues) throw new SearchError(search, result.issues);
-  // The schema's declared output; the loose `StandardSchemaV1` default
-  // degrades to `unknown`.
-  return result.value;
-}
-
-/**
- * Synchronous flavor of {@link parseSearch}, for render-time reads(see
- * `useSearch` of `@native-router/react`) and route guards.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema — must validate synchronously
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- * @throws when the schema validates asynchronously; use {@link parseSearch}
- * for async schemas instead
- */
-function parseSearchSync(schema, search) {
-  const result = schema['~standard'].validate(parseSearchInput(search));
-  if (isThenable(result)) {
-    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
-  }
-  if (result.issues) throw new SearchError(search, result.issues);
-  // See parseSearch for the cast rationale.
-  return result.value;
-}
-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, invalidate, 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

@@ -100,6 +100,11 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -156,7 +161,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
@@ -250,6 +257,37 @@ export declare function initHistoryStack<R extends BaseRoute = BaseRoute, V = an
  * @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/dist/types/types.d.ts

@@ -143,10 +143,19 @@ export type ExtractPathParams<P extends string> = P extends `${infer Head}/${inf
  * `params` are accumulated from the root level down to the level that
  * owns the guard, so a guard only sees params of itself and its parents.
  */
-export type GuardContext<R extends BaseRoute = BaseRoute> = {
+export type GuardContext<R extends BaseRoute = BaseRoute, S = unknown> = {
     router: RouterInstance<R>;
     location: Location;
     params: Record<string, string>;
+    /**
+     * The search the guard sees: the route's {@link BaseRoute.search search
+     * schema} output(parsed and validated before the guard runs), or the
+     * degraded {@link SearchInput} when the route declares no schema. The
+     * loose default types it `unknown` — narrow it in the guard, or let a
+     * typed route table(see `createRoutes` of `@native-router/react`)
+     * derive it from the schema.
+     */
+    search: S;
     /**
      * Aborted when this navigation is superseded by a newer one or
      * cancelled(see {@link RouterInstance.cancelAll cancel}); pass it to
@@ -173,7 +182,11 @@ export type BaseRoute<T = any> = {
     search?: StandardSchemaV1;
     /**
      * Route guard invoked before the view resolves. Return a path string
-     * to redirect, or nothing(`undefined`) to continue.
+     * to redirect, or nothing(`undefined`) to continue. The guard's
+     * {@link GuardContext context} carries the level's parsed
+     * {@link GuardContext.search search}(schema output, or the degraded
+     * input without a schema); an invalid search fails the resolution at
+     * this phase like any other navigation error.
      */
     beforeLoad?(ctx: GuardContext<BaseRoute<T>>): Awaitable<string | void>;
 } & Omit<T, 'path' | 'children'>;

package/package.json

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