@real-router/navigation-plugin 0.7.5 → 0.7.7

package/src/history-extensions.ts

@@ -1,214 +0,0 @@
-import { extractPathFromAbsoluteUrl } from "./browser-env";
-
-import type { NavigationBrowser } from "./types";
-import type { State } from "@real-router/core";
-import type { PluginApi } from "@real-router/core/api";
-
-/**
- * Validates a candidate history entry for `traverseToLast(routeName)` and
- * returns both the entry (now known non-null) and the matched router state.
- * Extracted from `NavigationPlugin` so the three error branches (missing
- * entry, null url, unmatched url) can be tested directly without vi.spyOn
- * on module namespaces — the star-import spy pattern is fragile under ESM
- * and was working by accident in history-extensions.test.ts.
- *
- * Throws a descriptive Error on any failure; the caller (NavigationPlugin)
- * propagates it as the rejection of `traverseToLast`.
- */
-export function resolveEntryToMatchedState(
-  entry: NavigationHistoryEntry | undefined,
-  routeName: string,
-  api: PluginApi,
-  base: string,
-): { entry: NavigationHistoryEntry; entryUrl: string; matchedState: State } {
-  if (!entry) {
-    throw new Error(`No history entry for route "${routeName}"`);
-  }
-
-  const entryUrl = entry.url;
-
-  if (!entryUrl) {
-    throw new Error(`No matching route for entry URL "${entryUrl}"`);
-  }
-
-  const path = extractPathFromAbsoluteUrl(entryUrl, base);
-  const matchedState = api.matchPath(path);
-
-  if (!matchedState) {
-    throw new Error(`No matching route for entry URL "${entryUrl}"`);
-  }
-
-  // entryUrl is returned alongside `entry` so callers can read the validated
-  // URL without re-doing the null check — TypeScript cannot narrow a property
-  // access through a control-flow guard on `entry.url`.
-  return { entry, entryUrl, matchedState };
-}
-
-/**
- * Converts a NavigationHistoryEntry to a State via URL matching.
- * Uses URL matching (not entry.getState()) because:
- * - Entries before plugin init have no state
- * - Entries after router.replace(routes) may have stale state
- * - Entries from other SPAs on the same origin have foreign state
- */
-export function entryToState(
-  entry: NavigationHistoryEntry | undefined,
-  api: PluginApi,
-  base: string,
-): State | undefined {
-  if (!entry?.url) {
-    return undefined;
-  }
-
-  return (
-    api.matchPath(extractPathFromAbsoluteUrl(entry.url, base)) ?? undefined
-  );
-}
-
-function peekAt(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-  offset: number,
-): State | undefined {
-  const idx = browser.currentEntry?.index;
-
-  if (idx == null) {
-    return undefined;
-  }
-
-  return entryToState(browser.entries()[idx + offset], api, base);
-}
-
-export function peekBack(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-): State | undefined {
-  return peekAt(browser, api, base, -1);
-}
-
-export function peekForward(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-): State | undefined {
-  return peekAt(browser, api, base, 1);
-}
-
-export function hasVisited(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-  routeName: string,
-): boolean {
-  return browser.entries().some((entry) => {
-    const state = entryToState(entry, api, base);
-
-    return state?.name === routeName;
-  });
-}
-
-export function getVisitedRoutes(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-): string[] {
-  const names = new Set<string>();
-
-  for (const entry of browser.entries()) {
-    const state = entryToState(entry, api, base);
-
-    if (state) {
-      names.add(state.name);
-    }
-  }
-
-  return [...names];
-}
-
-export function getRouteVisitCount(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-  routeName: string,
-): number {
-  let count = 0;
-
-  for (const entry of browser.entries()) {
-    if (entryToState(entry, api, base)?.name === routeName) {
-      count++;
-    }
-  }
-
-  return count;
-}
-
-/**
- * Finds the last NavigationHistoryEntry matching the given route name,
- * excluding the current entry (to avoid SAME_STATES on traverseToLast("current-route")).
- */
-export function findLastEntryForRoute(
-  entries: NavigationHistoryEntry[],
-  routeName: string,
-  api: PluginApi,
-  base: string,
-  currentKey: string | undefined,
-): NavigationHistoryEntry | undefined {
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const entry = entries[i];
-
-    if (entry.key === currentKey) {
-      continue;
-    }
-
-    const state = entryToState(entry, api, base);
-
-    if (state?.name === routeName) {
-      return entry;
-    }
-  }
-
-  return undefined;
-}
-
-export function canGoBack(browser: NavigationBrowser): boolean {
-  const idx = browser.currentEntry?.index;
-
-  return idx != null && idx > 0;
-}
-
-export function canGoForward(browser: NavigationBrowser): boolean {
-  const idx = browser.currentEntry?.index;
-
-  if (idx == null) {
-    return false;
-  }
-
-  return idx < browser.entries().length - 1;
-}
-
-export function canGoBackTo(
-  browser: NavigationBrowser,
-  api: PluginApi,
-  base: string,
-  routeName: string,
-): boolean {
-  const idx = browser.currentEntry?.index;
-
-  if (idx == null) {
-    return false;
-  }
-
-  const entries = browser.entries();
-
-  for (let i = idx - 1; i >= 0; i--) {
-    const state = entryToState(entries[i], api, base);
-
-    if (state?.name === routeName) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/href-utils.ts

@@ -1,65 +0,0 @@
-/**
- * Pure URL-comparison helper extracted from `plugin.ts` so it can be unit and
- * property-tested in isolation. See INVARIANTS.md section K for the formal
- * properties this function satisfies.
- *
- * Sole production call site: the same-URL guard in
- * `NavigationPlugin.onTransitionSuccess` (#580).
- */
-
-/**
- * Returns `true` when resolving `target` (a relative or absolute URL) against
- * `currentHref` identifies the same logical document — same protocol, host,
- * pathname (with empty pathname normalised to `"/"`), search, and hash.
- *
- * Why component-wise (not raw `.href` equality):
- *
- * For **special schemes** (`http:`, `https:`, `ws:`, `wss:`, `file:`) the URL
- * parser canonicalises empty pathname to `"/"`, so `http://x` and `http://x/`
- * share the same `.href` and either comparison would work.
- *
- * For **non-special schemes** (`tauri://`, `app://`, custom protocols used by
- * Tauri/Electron) the parser preserves the empty pathname:
- *
- *   new URL("tauri://localhost").href         === "tauri://localhost"
- *   new URL("/", "tauri://localhost").href    === "tauri://localhost/"
- *
- * A naive `.href` equality would treat these as different. `nav.navigate("/")`
- * against `tauri://localhost` would then go through the navigate path — and
- * under Safari 26.2 WKWebView that round-trip triggers a cross-document
- * reload (the #580 root cause). The first time the user observed this, the
- * `same-URL guard` fix only kicked in on the SECOND iteration (after the
- * URL had been auto-normalised to include the trailing slash). Component-
- * wise comparison with `pathname || "/"` closes that first-iteration hole.
- *
- * Returns `false` when:
- * - `currentHref` is null, undefined or empty (SSR fallback / pre-start),
- * - either URL construction throws (malformed input).
- *
- * Total over all string inputs: never throws.
- *
- * @internal — exported for property testing; not part of the public surface.
- */
-export function isSameHref(
-  target: string,
-  currentHref: string | null | undefined,
-): boolean {
-  if (!currentHref) {
-    return false;
-  }
-
-  try {
-    const resolved = new URL(target, currentHref);
-    const base = new URL(currentHref);
-
-    return (
-      resolved.protocol === base.protocol &&
-      resolved.host === base.host &&
-      (resolved.pathname || "/") === (base.pathname || "/") &&
-      resolved.search === base.search &&
-      resolved.hash === base.hash
-    );
-  } catch {
-    return false;
-  }
-}

package/src/index.ts

@@ -1,65 +0,0 @@
-/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
-
-import type { Params, State } from "@real-router/core";
-
-export { navigationPluginFactory } from "./factory";
-
-export { PLUGIN_SYNC_INFO } from "./navigation-browser";
-
-export type {
-  NavigationPluginOptions,
-  NavigationBrowser,
-  NavigationMeta,
-  NavigationDirection,
-} from "./types";
-
-declare module "@real-router/types" {
-  interface StateContext {
-    navigation?: import("./types").NavigationMeta;
-    /**
-     * URL fragment ("hash") layer state (#532). Populated by both URL plugins
-     * (navigation-plugin, browser-plugin) — they are mutually exclusive at
-     * runtime, so only one writes to this namespace.
-     */
-    url?: import("./browser-env").UrlContext;
-  }
-
-  interface NavigationOptions {
-    /**
-     * URL fragment override (decoded, no leading "#") (#532).
-     * Tri-state: `undefined` → preserve current; `""` → clear; non-empty → set.
-     */
-    hash?: string;
-    /**
-     * @internal — set by URL plugins on hash-only browser-driven navigation.
-     * Subscribers should branch on `state.context.url.hashChanged` instead.
-     */
-    hashChange?: boolean;
-  }
-}
-
-declare module "@real-router/core" {
-  interface Router {
-    buildUrl(
-      name: string,
-      params?: Params,
-      options?: { hash?: string },
-    ): string;
-    matchUrl(url: string): State | undefined;
-    replaceHistoryState(
-      name: string,
-      params?: Params,
-      options?: { hash?: string },
-    ): void;
-    peekBack(): State | undefined;
-    peekForward(): State | undefined;
-    hasVisited(routeName: string): boolean;
-    getVisitedRoutes(): string[];
-    getRouteVisitCount(routeName: string): number;
-    traverseToLast(routeName: string): Promise<State>;
-    canGoBack(): boolean;
-    canGoForward(): boolean;
-    canGoBackTo(routeName: string): boolean;
-    start(path?: string): Promise<State>;
-  }
-}

package/src/navigate-handler.ts

@@ -1,260 +0,0 @@
-import { errorCodes, RouterError } from "@real-router/core";
-
-import { urlToPathAndHash } from "./browser-env";
-import { PLUGIN_SYNC_INFO } from "./navigation-browser";
-
-import type {
-  NavigationBrowser,
-  NavigationDirection,
-  NavigationMeta,
-} from "./types";
-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.
-//
-// `scroll: "manual"` is critical for plugin-originated re-emits: by the time
-// the navigate event fires for a router-driven mutation (e.g. scroll-spy's
-// hash-only nav, scroll-restoration's URL sync), the router has already
-// committed the transition and the app owns scroll position. Default
-// `scroll: "after-transition"` would auto-scroll the new URL fragment into
-// view, fighting against the user's own scroll motion (concrete bug:
-// scroll-spy + slow user scroll → viewport jump on every emit).
-// Aligns with browser-plugin (History API has no auto-scroll on
-// programmatic URL changes). Apps that want hash-anchor auto-scroll opt
-// in via `createScrollRestoration({ anchorScrolling: true })`.
-const NOOP_ASYNC = async (): Promise<void> => {};
-const NOOP_INTERCEPT: NavigationInterceptOptions = {
-  handler: NOOP_ASYNC,
-  scroll: "manual",
-};
-
-interface NavigateHandlerDeps {
-  router: Router;
-  api: PluginApi;
-  browser: NavigationBrowser;
-  setCapturedMeta: (meta: NavigationMeta) => void;
-  base: string;
-  transitionOptions: {
-    source: string;
-    replace: true;
-    forceDeactivate?: boolean;
-  };
-}
-
-export function computeDirection(
-  navigationType: NavigationMeta["navigationType"],
-  destinationIndex: number,
-  currentIndex: number,
-): NavigationDirection {
-  if (navigationType === "traverse") {
-    if (destinationIndex === currentIndex) {
-      return "unknown";
-    }
-
-    return destinationIndex > currentIndex ? "forward" : "back";
-  }
-
-  return navigationType === "push" ? "forward" : "unknown";
-}
-
-export function createNavigateHandler(deps: NavigateHandlerDeps) {
-  const { router, api, browser, base, transitionOptions } = deps;
-  const { allowNotFound } = api.getOptions();
-
-  return function handleNavigateEvent(event: NavigateEvent): void {
-    if (!event.canIntercept || !router.isActive()) {
-      return;
-    }
-
-    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.
-      //
-      // 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;
-    }
-
-    const { path, hash } = urlToPathAndHash(event.destination.url, base);
-    const matchedState = api.matchPath(path);
-
-    const navType = event.navigationType;
-    const currentIndex = browser.currentEntry?.index ?? -1;
-
-    deps.setCapturedMeta({
-      navigationType: navType,
-      userInitiated: event.userInitiated,
-      info: event.info,
-      direction: computeDirection(
-        navType,
-        event.destination.index,
-        currentIndex,
-      ),
-      sourceElement: event.sourceElement ?? null,
-    });
-
-    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,
-              }),
-            router,
-            browser,
-          ),
-      });
-    } else if (allowNotFound) {
-      event.intercept({
-        handler: () => {
-          router.navigateToNotFound(path);
-        },
-      });
-    } else {
-      // Strict mode — unmatched URL is an error. Emit $$error and reject the
-      // intercept so the Navigation API auto-rolls back the URL. No silent
-      // fallback to defaultRoute.
-      event.intercept({
-        // eslint-disable-next-line @typescript-eslint/require-await -- Navigation API requires async handler; synchronous throw is the rollback signal
-        handler: async () => {
-          const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, { path });
-
-          api.emitTransitionError(err);
-
-          throw err;
-        },
-      });
-    }
-  };
-}
-
-/**
- * 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,
-  browser: NavigationBrowser,
-): void {
-  console.error(
-    "[navigation-plugin] Critical error in navigate handler",
-    error,
-  );
-
-  syncUrlToRouterState(router, browser);
-}
-
-function syncUrlToRouterState(
-  router: Router,
-  browser: NavigationBrowser,
-): void {
-  try {
-    const currentState = router.getState();
-
-    if (currentState) {
-      // Preserve hash on recovery (#532): reading from state.context.url
-      // keeps the visible URL fragment intact when a guard rejects a hash-
-      // bearing navigation.
-      const ctxHash = (
-        currentState.context as { url?: { hash?: string } } | undefined
-      )?.url?.hash;
-      const url = router.buildUrl(
-        currentState.name,
-        currentState.params,
-        ctxHash ? { hash: ctxHash } : undefined,
-      );
-
-      // 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,
-          params: currentState.params,
-          path: currentState.path,
-        },
-        history: "replace",
-      });
-    }
-  } catch (syncError) {
-    console.error(
-      "[navigation-plugin] Failed to sync URL to router state",
-      syncError,
-    );
-  }
-}

package/src/navigation-browser.ts

@@ -1,92 +0,0 @@
-import { safelyEncodePath, extractPath } from "./browser-env";
-
-import type { NavigationBrowser } from "./types";
-
-/**
- * Sentinel carried on `event.info` for every router-driven mutation.
- *
- * 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 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`. Scroll-after-transition suppression
- * (`scroll: "manual"`) lives in `navigate-handler.ts`'s `NOOP_INTERCEPT`
- * — `scroll` is an `event.intercept()` option, not a `nav.navigate()`
- * option per WHATWG Navigation API spec.
- */
-export function createNavigationBrowser(base: string): NavigationBrowser {
-  const nav = globalThis.navigation;
-
-  return {
-    getLocation: () =>
-      safelyEncodePath(extractPath(globalThis.location.pathname, base)) +
-      globalThis.location.search,
-
-    getHash: () => globalThis.location.hash,
-
-    navigate: (url, options) => {
-      nav.navigate(url, { ...options, info: PLUGIN_SYNC_INFO });
-    },
-
-    replaceState: (state, url) => {
-      nav.navigate(url, {
-        state,
-        history: "replace",
-        info: PLUGIN_SYNC_INFO,
-      });
-    },
-
-    updateCurrentEntry: (options) => {
-      nav.updateCurrentEntry(options);
-    },
-
-    traverseTo: (key) => {
-      nav.traverseTo(key, TRAVERSE_OPTS);
-    },
-
-    addNavigateListener: (fn) => {
-      nav.addEventListener("navigate", fn);
-
-      return () => {
-        nav.removeEventListener("navigate", fn);
-      };
-    },
-
-    entries: () => nav.entries(),
-
-    get currentEntry() {
-      return nav.currentEntry;
-    },
-
-    getActivationType: () => nav.activation?.navigationType,
-  };
-}