@real-router/navigation-plugin 0.7.1 → 0.7.3

package/src/navigate-handler.ts

@@ -1,6 +1,7 @@
 import { errorCodes, RouterError } from "@real-router/core";
 
 import { urlToPathAndHash } from "./browser-env";
+import { PLUGIN_SYNC_INFO } from "./navigation-browser";
 
 import type {
   NavigationBrowser,
@@ -10,11 +11,17 @@ import type {
 import type { Router } from "@real-router/core";
 import type { PluginApi } from "@real-router/core/api";
 
+// Hoisted noop intercept options — reused on every plugin-originated
+// navigate event (the hot path). `event.intercept` reads `handler` once per
+// call per Navigation API spec, so a shared object/function is safe and
+// saves two allocations per intercepted event.
+const NOOP_ASYNC = async (): Promise<void> => {};
+const NOOP_INTERCEPT: NavigationInterceptOptions = { handler: NOOP_ASYNC };
+
 interface NavigateHandlerDeps {
   router: Router;
   api: PluginApi;
   browser: NavigationBrowser;
-  isSyncingFromRouter: () => boolean;
   setCapturedMeta: (meta: NavigationMeta) => void;
   base: string;
   transitionOptions: {
@@ -41,8 +48,7 @@ export function computeDirection(
 }
 
 export function createNavigateHandler(deps: NavigateHandlerDeps) {
-  const { router, api, browser, isSyncingFromRouter, base, transitionOptions } =
-    deps;
+  const { router, api, browser, base, transitionOptions } = deps;
   const { allowNotFound } = api.getOptions();
 
   return function handleNavigateEvent(event: NavigateEvent): void {
@@ -50,16 +56,22 @@ export function createNavigateHandler(deps: NavigateHandlerDeps) {
       return;
     }
 
-    if (isSyncingFromRouter()) {
+    if (event.info === PLUGIN_SYNC_INFO) {
       // Plugin-originated navigate event after its own successful transition
       // (onTransitionSuccess calls browser.navigate to sync URL). We must still
       // intercept — a bare `return` leaves the event un-intercepted, and
       // Chromium falls back to a cross-document navigation (full page reload).
       // The noop handler cancels the fallback without running router logic;
       // state is already committed.
-      event.intercept({
-        handler: async () => {},
-      });
+      //
+      // Detection by `event.info` (identity) instead of a synchronous flag
+      // (timing) so this works under Safari 26.2 WKWebView, which delivers
+      // navigate events on a subsequent task — by then a `finally`-cleared
+      // flag would already be false and the handler would loop (#580).
+      //
+      // NOOP_INTERCEPT is module-level so the intercept options + handler
+      // are not re-allocated per navigation (hot path).
+      event.intercept(NOOP_INTERCEPT);
 
       return;
     }
@@ -82,67 +94,30 @@ export function createNavigateHandler(deps: NavigateHandlerDeps) {
       sourceElement: event.sourceElement ?? null,
     });
 
-    const withRecovery = async (run: () => Promise<unknown>): Promise<void> => {
-      try {
-        await run();
-      } catch (error) {
-        if (!(error instanceof RouterError)) {
-          recoverFromNavigateError(error, router, browser);
-
-          return;
-        }
-
-        // TRANSITION_CANCELLED: a newer navigation aborted this one — the
-        // newer navigate event is (or will be) handled by this same plugin,
-        // and THAT event is responsible for syncing URL/state. Firing our
-        // own sync here races against it: browser.navigate(replace, same-url)
-        // would cancel the in-flight newer transition, which is exactly the
-        // rapid-fire-events storm failure mode.
-        //
-        // SAME_STATES: router refused because router.getState() already equals
-        // the target. URL and router state are already consistent — no sync
-        // needed.
-        if (
-          error.code === errorCodes.TRANSITION_CANCELLED ||
-          error.code === errorCodes.SAME_STATES
-        ) {
-          return;
-        }
-
-        // Other RouterError codes (CANNOT_DEACTIVATE, CANNOT_ACTIVATE,
-        // ROUTE_NOT_FOUND, …) — router rejected the transition, state is
-        // unchanged, but URL may have already committed to a different
-        // value by the Navigation API. Sync the URL back to the current
-        // router state in a single visible transition (headless Chromium
-        // and some cross-origin setups leave "committed-then-reverted"
-        // windows if we relied on the native rollback via intercept reject).
-        // Observers that care about the error see it through the router's
-        // TRANSITION_ERROR event.
-        syncUrlToRouterState(router, browser);
-      }
-    };
-
     if (matchedState) {
       event.intercept({
         handler: () =>
-          withRecovery(() =>
-            // api.navigateToState: matchPath already applied forwardState +
-            // matchSourceTrailingSlash; reusing the State avoids the redundant
-            // round-trip and preserves trailing slashes (#525). Plugin-only
-            // entry point — not on the public Router/Navigator surface.
-            //
-            // Hash extraction (#532): pass through the destination's hash so
-            // onTransitionSuccess sets state.context.url.hash. When the
-            // browser fires hashChange (same-document fragment-only nav),
-            // add force+hashChange to bypass SAME_STATES — subscribers
-            // disambiguate via state.context.url.hashChanged, not via the
-            // overloaded force flag.
-            api.navigateToState(matchedState, {
-              ...transitionOptions,
-              hash,
-              ...(event.hashChange ? { force: true, hashChange: true } : {}),
-              signal: event.signal,
-            }),
+          withRecovery(
+            () =>
+              // api.navigateToState: matchPath already applied forwardState +
+              // matchSourceTrailingSlash; reusing the State avoids the redundant
+              // round-trip and preserves trailing slashes (#525). Plugin-only
+              // entry point — not on the public Router/Navigator surface.
+              //
+              // Hash extraction (#532): pass through the destination's hash so
+              // onTransitionSuccess sets state.context.url.hash. When the
+              // browser fires hashChange (same-document fragment-only nav),
+              // add force+hashChange to bypass SAME_STATES — subscribers
+              // disambiguate via state.context.url.hashChanged, not via the
+              // overloaded force flag.
+              api.navigateToState(matchedState, {
+                ...transitionOptions,
+                hash,
+                ...(event.hashChange ? { force: true, hashChange: true } : {}),
+                signal: event.signal,
+              }),
+            router,
+            browser,
           ),
       });
     } else if (allowNotFound) {
@@ -169,6 +144,54 @@ export function createNavigateHandler(deps: NavigateHandlerDeps) {
   };
 }
 
+/**
+ * Module-scope helper hoisted out of handleNavigateEvent so the closure is
+ * not re-allocated on every navigate event. The router/browser refs come from
+ * arguments instead of an enclosing scope; identical behaviour, fewer GC'd
+ * closures.
+ */
+async function withRecovery(
+  run: () => Promise<unknown>,
+  router: Router,
+  browser: NavigationBrowser,
+): Promise<void> {
+  try {
+    await run();
+  } catch (error) {
+    if (!(error instanceof RouterError)) {
+      recoverFromNavigateError(error, router, browser);
+
+      return;
+    }
+
+    // TRANSITION_CANCELLED: a newer navigation aborted this one — the newer
+    // navigate event is (or will be) handled by this same plugin, and THAT
+    // event is responsible for syncing URL/state. Firing our own sync here
+    // races against it: browser.navigate(replace, same-url) would cancel the
+    // in-flight newer transition, which is exactly the rapid-fire-events storm
+    // failure mode.
+    //
+    // SAME_STATES: router refused because router.getState() already equals the
+    // target. URL and router state are already consistent — no sync needed.
+    if (
+      error.code === errorCodes.TRANSITION_CANCELLED ||
+      error.code === errorCodes.SAME_STATES
+    ) {
+      return;
+    }
+
+    // Other RouterError codes (CANNOT_DEACTIVATE, CANNOT_ACTIVATE,
+    // ROUTE_NOT_FOUND, …) — router rejected the transition, state is
+    // unchanged, but URL may have already committed to a different value by
+    // the Navigation API. Sync the URL back to the current router state in a
+    // single visible transition (headless Chromium and some cross-origin
+    // setups leave "committed-then-reverted" windows if we relied on the
+    // native rollback via intercept reject). Observers that care about the
+    // error see it through the router's TRANSITION_ERROR event.
+    syncUrlToRouterState(router, browser);
+  }
+}
+
 function recoverFromNavigateError(
   error: unknown,
   router: Router,
@@ -202,9 +225,9 @@ function syncUrlToRouterState(
         ctxHash ? { hash: ctxHash } : undefined,
       );
 
-      // The syncing flag is raised/lowered inside NavigationBrowser around
-      // browser.navigate, including the throw path — no manual try/finally
-      // needed here.
+      // browser.navigate inside `createNavigationBrowser` tags `info` with
+      // PLUGIN_SYNC_INFO so the navigate event this fires is recognised by
+      // the handler and short-circuited — no manual flag management here.
       browser.navigate(url, {
         state: {
           name: currentState.name,

package/src/navigation-browser.ts

@@ -3,20 +3,42 @@ import { safelyEncodePath, extractPath } from "./browser-env";
 import type { NavigationBrowser } from "./types";
 
 /**
- * Mutable cell carrying the "syncing-from-router" flag shared between
- * `wrapNavigationBrowserWithSyncing` (which raises it around every router-driven
- * mutation) and the plugin's navigate handler (which reads it to short-circuit
- * the event fired by the plugin's own write).
+ * Sentinel carried on `event.info` for every router-driven mutation.
  *
- * Internal to navigation-plugin — not part of the public type surface.
+ * The navigate-event handler reads `event.info === PLUGIN_SYNC_INFO` to detect
+ * plugin-originated events and short-circuit them with a noop intercept.
+ * Identity-based detection works regardless of whether the navigate event is
+ * delivered synchronously inside `nav.navigate(...)` (Chromium) or
+ * asynchronously on the next task (Safari 26.2 WKWebView — #580).
+ *
+ * The previous `SyncingFlag` mechanism raised a per-instance boolean before
+ * the call and lowered it in a synchronous `finally`. Under Safari WKWebView
+ * the flag was already `false` by the time the event arrived, so the handler
+ * treated the plugin's own write as user-initiated and re-issued
+ * `router.navigate(...)` — render loop on macOS 26.2 Tauri release.
+ *
+ * Consumers supplying a custom `NavigationBrowser` should pass this value as
+ * `info` in their `nav.navigate` / `nav.traverseTo` calls so the plugin can
+ * recognise plugin-initiated events. See packages/navigation-plugin/CLAUDE.md.
  */
-export interface SyncingFlag {
-  current: boolean;
-}
+export const PLUGIN_SYNC_INFO = "@real-router/navigation-plugin:syncing";
+
+// `traverseTo` options never carry per-call data — the sentinel `info` is the
+// only field — so a single frozen constant is reused across every traversal.
+// Saves one allocation per `nav.traverseTo` on the hot path.
+const TRAVERSE_OPTS: NavigationOptions = Object.freeze({
+  info: PLUGIN_SYNC_INFO,
+});
 
 /**
  * Creates a NavigationBrowser wrapping the real Navigation API.
  * Only call this when `"navigation" in globalThis` is true.
+ *
+ * Every router-driven mutation (`navigate`, `replaceState`, `traverseTo`)
+ * tags `info` with `PLUGIN_SYNC_INFO` so the navigate-event handler can
+ * recognise and short-circuit the event it fires — see `PLUGIN_SYNC_INFO`
+ * for the rationale. `updateCurrentEntry` is excluded because it fires
+ * `currententrychange`, not `navigate`.
  */
 export function createNavigationBrowser(base: string): NavigationBrowser {
   const nav = globalThis.navigation;
@@ -29,13 +51,14 @@ export function createNavigationBrowser(base: string): NavigationBrowser {
     getHash: () => globalThis.location.hash,
 
     navigate: (url, options) => {
-      nav.navigate(url, options);
+      nav.navigate(url, { ...options, info: PLUGIN_SYNC_INFO });
     },
 
     replaceState: (state, url) => {
       nav.navigate(url, {
         state,
         history: "replace",
+        info: PLUGIN_SYNC_INFO,
       });
     },
 
@@ -44,7 +67,7 @@ export function createNavigationBrowser(base: string): NavigationBrowser {
     },
 
     traverseTo: (key) => {
-      nav.traverseTo(key);
+      nav.traverseTo(key, TRAVERSE_OPTS);
     },
 
     addNavigateListener: (fn) => {
@@ -64,63 +87,3 @@ export function createNavigationBrowser(base: string): NavigationBrowser {
     getActivationType: () => nav.activation?.navigationType,
   };
 }
-
-/**
- * Wraps every router-driven mutation of a NavigationBrowser with the syncing
- * flag — raised before the underlying call, lowered after, including the
- * throw path. The plugin's navigate handler reads `syncing.current` to
- * short-circuit the navigate event fired by the plugin's own write
- * (`nav.navigate(...)` and `nav.navigate({history:"replace"})` both fire
- * navigate events synchronously).
- *
- * Applied at the factory level to both the built-in `createNavigationBrowser`
- * and any user-supplied browser, so consumers don't need to manage the flag.
- */
-export function wrapNavigationBrowserWithSyncing(
-  browser: NavigationBrowser,
-  syncing: SyncingFlag,
-): NavigationBrowser {
-  const wrap = <T>(fn: () => T): T => {
-    syncing.current = true;
-    try {
-      return fn();
-    } finally {
-      syncing.current = false;
-    }
-  };
-
-  return {
-    getLocation: () => browser.getLocation(),
-    getHash: () => browser.getHash(),
-
-    navigate: (url, options) => {
-      wrap(() => {
-        browser.navigate(url, options);
-      });
-    },
-    replaceState: (state, url) => {
-      wrap(() => {
-        browser.replaceState(state, url);
-      });
-    },
-    updateCurrentEntry: (options) => {
-      wrap(() => {
-        browser.updateCurrentEntry(options);
-      });
-    },
-    traverseTo: (key) => {
-      wrap(() => {
-        browser.traverseTo(key);
-      });
-    },
-
-    addNavigateListener: (fn) => browser.addNavigateListener(fn),
-    entries: () => browser.entries(),
-
-    get currentEntry() {
-      return browser.currentEntry;
-    },
-
-    getActivationType: () => browser.getActivationType(),
-  };
-}

package/src/plugin.ts

@@ -4,11 +4,14 @@ import {
   shouldReplaceHistory,
   buildUrl,
   urlToPath,
+  createPluginBuildUrl,
   createStartInterceptor,
   createReplaceHistoryState,
   encodeHashFragment,
   getDecodedHash,
   normalizeHashInput,
+  safeParseUrl,
+  decodeHashFragment,
 } from "./browser-env";
 import {
   peekBack,
@@ -22,11 +25,10 @@ import {
   canGoForward,
   canGoBackTo,
 } from "./history-extensions";
+import { isSameHref } from "./href-utils";
 import { createNavigateHandler } from "./navigate-handler";
-import { wrapNavigationBrowserWithSyncing } from "./navigation-browser";
 
 import type { UrlContext } from "./browser-env";
-import type { SyncingFlag } from "./navigation-browser";
 import type {
   NavigationBrowser,
   NavigationMeta,
@@ -35,7 +37,6 @@ import type {
 } from "./types";
 import type {
   NavigationOptions,
-  Params,
   Router,
   State,
   Plugin,
@@ -74,10 +75,24 @@ export class NavigationPlugin {
     release: () => void;
   };
   readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
-  readonly #syncing: SyncingFlag = { current: false };
 
   #capturedMeta: NavigationMeta | undefined;
   #pendingTraverseKey: string | undefined;
+  // Always set together with #pendingTraverseKey; `""` means "destination has
+  // no fragment". Typed as `string` (not `string | undefined`) so the traverse
+  // branch reads it without a redundant `?? ""` fallback that coverage cannot
+  // exercise.
+  #pendingTraverseHash = "";
+  // Reusable buffer for the {name, params, path} payload passed to
+  // browser.navigate / browser.updateCurrentEntry. The Navigation API
+  // structured-clones state synchronously inside the call, so this object
+  // never escapes — same trick createReplaceHistoryState uses.
+  readonly #historyStateBuffer: { name: string; params: object; path: string } =
+    {
+      name: "",
+      params: {},
+      path: "",
+    };
 
   constructor(
     router: Router,
@@ -94,13 +109,12 @@ export class NavigationPlugin {
     this.#router = router;
     this.#api = api;
     this.#options = options;
-    // Wrap mutations with the syncing flag so the navigate handler can
-    // short-circuit re-entrant events fired by the plugin's own writes
-    // (`nav.navigate` and `nav.navigate({history:"replace"})` fire navigate
-    // events synchronously). The flag is per-instance — never shared across
-    // plugins — so multiple routers running concurrent transitions don't
-    // bleed syncing state into each other.
-    this.#browser = wrapNavigationBrowserWithSyncing(browser, this.#syncing);
+    // The navigate handler short-circuits re-entrant events from plugin-
+    // initiated writes by checking `event.info === PLUGIN_SYNC_INFO`. The
+    // built-in `createNavigationBrowser` tags every mutation with that
+    // sentinel; consumer-supplied browsers must do the same — see CLAUDE.md
+    // "Router-driven mutations re-enter the navigate handler".
+    this.#browser = browser;
 
     this.#claim = api.claimContextNamespace("navigation");
     this.#urlClaim = api.claimContextNamespace("url");
@@ -133,22 +147,7 @@ export class NavigationPlugin {
     // bar entry: by the time onTransitionSuccess fires the browser already
     // reflects the destination URL.
 
-    const pluginBuildUrl = (
-      route: string,
-      params?: Params,
-      opts?: { hash?: string },
-    ) => {
-      const path = router.buildPath(route, params);
-      const url = buildUrl(path, options.base);
-
-      if (opts?.hash === undefined) {
-        return url;
-      }
-
-      const norm = normalizeHashInput(opts.hash);
-
-      return norm ? `${url}#${encodeHashFragment(norm)}` : url;
-    };
+    const pluginBuildUrl = createPluginBuildUrl(router, options.base);
 
     this.#removeExtensions = api.extendRouter({
       buildUrl: pluginBuildUrl,
@@ -180,7 +179,6 @@ export class NavigationPlugin {
       router,
       api,
       browser: this.#browser,
-      isSyncingFromRouter: () => this.#syncing.current,
       setCapturedMeta: (meta) => {
         this.#capturedMeta = meta;
       },
@@ -216,7 +214,7 @@ export class NavigationPlugin {
     // unmatched url — same three error branches the old inline checks
     // produced. Extracted so the error paths can be unit-tested directly
     // without namespace-level vi.spyOn gymnastics.
-    const { entry, matchedState } = resolveEntryToMatchedState(
+    const { entry, entryUrl, matchedState } = resolveEntryToMatchedState(
       candidate,
       routeName,
       this.#api,
@@ -243,6 +241,10 @@ export class NavigationPlugin {
       sourceElement: null,
     };
     this.#pendingTraverseKey = entry.key;
+    // Capture the destination entry's hash so onTransitionSuccess can populate
+    // state.context.url for the traverse branch — mirrors what navigate-handler
+    // does via navOptions.hash for browser-initiated navigation.
+    this.#pendingTraverseHash = extractHashFromEntryUrl(entryUrl);
 
     return this.#router.navigate(matchedState.name, matchedState.params);
   }
@@ -287,13 +289,27 @@ export class NavigationPlugin {
         // under memory pressure), we must not leave the stale key behind —
         // otherwise the NEXT transition's onTransitionSuccess would see it
         // and replay the traverse against the same already-broken key.
-        // The syncing flag is raised/lowered inside NavigationBrowser around
-        // each mutation, so we do not need to manage it here.
         const traverseKey = this.#pendingTraverseKey;
+        const traverseHash = this.#pendingTraverseHash;
 
         this.#pendingTraverseKey = undefined;
+        this.#pendingTraverseHash = "";
+
+        const publishedPrevHash = readPublishedHash(fromState);
 
         if (traverseKey) {
+          // Mirror the urlClaim.write the `else` branch does for non-traverse
+          // navigations — without this, `router.traverseToLast(name)` leaves
+          // state.context.url undefined for subscribers (#urlClaim was set in
+          // navigate-handler for browser-driven traverse, but programmatic
+          // traverseToLast bypasses that path).
+          this.#urlClaim.write(
+            toState,
+            Object.freeze({
+              hash: traverseHash,
+              hashChanged: traverseHash !== publishedPrevHash,
+            }),
+          );
           this.#browser.traverseTo(traverseKey);
         } else {
           // Tri-state hash resolution (#532).
@@ -312,9 +328,6 @@ export class NavigationPlugin {
           // a true signal regardless of whether the value came from
           // navOptions or the browser.
           const browserHash = getDecodedHash(this.#browser);
-          const publishedPrevHash =
-            (fromState?.context as { url?: { hash?: string } } | undefined)?.url
-              ?.hash ?? "";
 
           const hash =
             navOptions.hash === undefined
@@ -331,19 +344,48 @@ export class NavigationPlugin {
 
           const url = buildUrl(toState.path, this.#options.base);
           const finalUrl = hash ? `${url}#${encodeHashFragment(hash)}` : url;
-          const historyState = {
-            name: toState.name,
-            params: toState.params,
-            path: toState.path,
-          };
 
-          if (toState.name === UNKNOWN_ROUTE) {
-            this.#browser.updateCurrentEntry({ state: historyState });
+          this.#historyStateBuffer.name = toState.name;
+          this.#historyStateBuffer.params = toState.params;
+          this.#historyStateBuffer.path = toState.path;
+
+          // Two cases route through `updateCurrentEntry` (state-only mutation
+          // of the current history entry, no navigate event):
+          //
+          // 1. UNKNOWN_ROUTE — URL stays as the browser had it; we only need
+          //    to tag the entry's state with the router's `name/params/path`.
+          // 2. Same-URL transition (#580) — the target URL is what the
+          //    browser already shows, so a `nav.navigate(url,
+          //    {history:"replace"})` would either be a no-op (Chromium fires
+          //    a navigate event we short-circuit via `event.info ===
+          //    PLUGIN_SYNC_INFO`) or — on Safari 26.2 WKWebView under custom
+          //    protocols (`tauri://`, `app://`) — a *cross-document*
+          //    navigation that discards the JS context. The bootstrap then
+          //    re-runs the plugin which re-issues the same call, and the
+          //    cycle becomes a render loop the user perceives as flicker.
+          //    `updateCurrentEntry` is the spec-correct primitive for a
+          //    state-only mutation and avoids both behaviours.
+          if (
+            toState.name === UNKNOWN_ROUTE ||
+            isSameHref(finalUrl, this.#browser.currentEntry?.url)
+          ) {
+            this.#browser.updateCurrentEntry({
+              state: this.#historyStateBuffer,
+            });
           } else {
-            const replace = frozenMeta.navigationType !== "push";
+            // Initial transition (no fromState) means router.start() is
+            // resolving the cross-document load — the browser already created
+            // a history entry for it. A `push` here would duplicate that
+            // entry. Always `replace` on the first transition so the
+            // back/forward stack has only one entry (canGoBack === false).
+            // navigationType metadata stays "push"/"reload"/"replace" for
+            // downstream consumers (scroll restore, direction tracker).
+            const isInitialTransition = fromState === undefined;
+            const replace =
+              frozenMeta.navigationType !== "push" || isInitialTransition;
 
             this.#browser.navigate(finalUrl, {
-              state: historyState,
+              state: this.#historyStateBuffer,
               history: replace ? "replace" : "push",
             });
           }
@@ -353,11 +395,13 @@ export class NavigationPlugin {
       onTransitionCancel: () => {
         this.#capturedMeta = undefined;
         this.#pendingTraverseKey = undefined;
+        this.#pendingTraverseHash = "";
       },
 
       onTransitionError: () => {
         this.#capturedMeta = undefined;
         this.#pendingTraverseKey = undefined;
+        this.#pendingTraverseHash = "";
       },
     };
   }
@@ -372,6 +416,33 @@ interface NavigateLifecycleDeps {
   shared: NavigationSharedState;
 }
 
+/**
+ * Reads the previously published hash from `fromState.context.url`.
+ * Returns `""` for the initial transition (no `fromState`), for states whose
+ * `context.url` namespace was not claimed yet, or for the documented `{ hash:
+ * "" }` cleared form. Extracted from `onTransitionSuccess` to share between
+ * the traverse and non-traverse branches.
+ */
+function readPublishedHash(fromState: State | undefined): string {
+  return (
+    (fromState?.context as { url?: { hash?: string } } | undefined)?.url
+      ?.hash ?? ""
+  );
+}
+
+/**
+ * Decodes the URL fragment from a NavigationHistoryEntry's url string.
+ * Returns `""` when no fragment is present. The caller (NavigationPlugin's
+ * `traverseToLast`) only reaches here AFTER `resolveEntryToMatchedState`,
+ * which has already rejected `entry.url === null`, so the input is guaranteed
+ * non-null at runtime.
+ */
+function extractHashFromEntryUrl(entryUrl: string): string {
+  const rawHash = safeParseUrl(entryUrl).hash;
+
+  return rawHash ? decodeHashFragment(rawHash.slice(1)) : "";
+}
+
 function createNavigateLifecycle(deps: NavigateLifecycleDeps): Plugin {
   return {
     onStart() {

package/src/types.ts

@@ -6,7 +6,7 @@ export interface NavigationPluginOptions {
   /**
    * Bypass canDeactivate guards on browser back/forward.
    *
-   * @default true
+   * @default false
    */
   forceDeactivate?: boolean;