@real-router/navigation-plugin 0.7.2 → 0.7.3

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,71 +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 {
-  // Hot path: each mutation is called on every navigation. Inline the
-  // try/finally instead of routing through a generic `wrap` helper — that
-  // helper created two closure layers (outer arrow + the `() => fn()` arg)
-  // per call. Inlining drops to a single closure and lets V8 monomorphize
-  // the call sites.
-  return {
-    getLocation: () => browser.getLocation(),
-    getHash: () => browser.getHash(),
-
-    navigate: (url, options) => {
-      syncing.current = true;
-      try {
-        browser.navigate(url, options);
-      } finally {
-        syncing.current = false;
-      }
-    },
-    replaceState: (state, url) => {
-      syncing.current = true;
-      try {
-        browser.replaceState(state, url);
-      } finally {
-        syncing.current = false;
-      }
-    },
-    updateCurrentEntry: (options) => {
-      syncing.current = true;
-      try {
-        browser.updateCurrentEntry(options);
-      } finally {
-        syncing.current = false;
-      }
-    },
-    traverseTo: (key) => {
-      syncing.current = true;
-      try {
-        browser.traverseTo(key);
-      } finally {
-        syncing.current = false;
-      }
-    },
-
-    addNavigateListener: (fn) => browser.addNavigateListener(fn),
-    entries: () => browser.entries(),
-
-    get currentEntry() {
-      return browser.currentEntry;
-    },
-
-    getActivationType: () => browser.getActivationType(),
-  };
-}

package/src/plugin.ts

@@ -25,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,
@@ -76,7 +75,6 @@ export class NavigationPlugin {
     release: () => void;
   };
   readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
-  readonly #syncing: SyncingFlag = { current: false };
 
   #capturedMeta: NavigationMeta | undefined;
   #pendingTraverseKey: string | undefined;
@@ -111,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");
@@ -182,7 +179,6 @@ export class NavigationPlugin {
       router,
       api,
       browser: this.#browser,
-      isSyncingFromRouter: () => this.#syncing.current,
       setCapturedMeta: (meta) => {
         this.#capturedMeta = meta;
       },
@@ -293,8 +289,6 @@ 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;
 
@@ -355,7 +349,26 @@ export class NavigationPlugin {
           this.#historyStateBuffer.params = toState.params;
           this.#historyStateBuffer.path = toState.path;
 
-          if (toState.name === UNKNOWN_ROUTE) {
+          // 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,
             });