@real-router/core 0.50.2 → 0.52.0

package/src/api/getPluginApi.ts

@@ -12,12 +12,25 @@ import type {
   State,
 } from "@real-router/types";
 
+// Cache the assembled PluginApi per router — mirrors getNavigator() (#525):
+// avoids re-allocating the closure-bag on each call (plugins call this once
+// at init, but tests + nested plugins poll it), and gives spy/stub helpers
+// a stable object identity to attach to (e.g. spying on
+// `getPluginApi(router).navigateToState` to inject errors in popstate
+// recovery tests).
+const cache = new WeakMap<object, PluginApi>();
+
 export function getPluginApi<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(router: Router<Dependencies>): PluginApi {
-  const ctx = getInternals(router);
+  const cached = cache.get(router);
+
+  if (cached) {
+    return cached;
+  }
 
-  return {
+  const ctx = getInternals(router);
+  const api: PluginApi = {
     makeState: (name, params, path, meta) => {
       ctx.validator?.state.validateMakeStateArgs(name, params, path);
 
@@ -58,6 +71,20 @@ export function getPluginApi<
 
       return ctx.matchPath(path, ctx.getOptions());
     },
+    navigateToState: (state, options) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      ctx.validator?.navigation.validateNavigateToStateArgs(state);
+
+      if (options !== undefined) {
+        ctx.validator?.navigation.validateNavigationOptions(
+          options,
+          "navigateToState",
+        );
+      }
+
+      return ctx.navigateToState(state, options);
+    },
     setRootPath: (rootPath) => {
       throwIfDisposed(ctx.isDisposed);
 
@@ -194,4 +221,8 @@ export function getPluginApi<
       } satisfies ContextNamespaceClaim;
     }) as PluginApi["claimContextNamespace"],
   };
+
+  cache.set(router, api);
+
+  return api;
 }

package/src/internals.ts

@@ -6,6 +6,7 @@ import type { RouterValidator } from "./types/RouterValidator";
 import type {
   DefaultDependencies,
   EventName,
+  NavigationOptions,
   Options,
   Params,
   Plugin,
@@ -55,6 +56,17 @@ export interface RouterInternals<
 
   readonly start: (path: string) => Promise<State>;
 
+  /**
+   * Plugin-only navigation entry point — delegates to
+   * `NavigationNamespace.navigateToState` (`getPluginApi(router).navigateToState`).
+   * Hidden from `Router`/`Navigator` to keep the userland surface minimal;
+   * see `core-types/src/api.ts` for usage docs.
+   */
+  readonly navigateToState: (
+    state: State,
+    options?: NavigationOptions,
+  ) => Promise<State>;
+
   /* eslint-disable @typescript-eslint/no-explicit-any -- heterogeneous map: stores different InterceptorFn<M> types under different keys */
   readonly interceptors: Map<
     string,

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -98,24 +98,176 @@ export class NavigationNamespace {
     }
 
     let toState: State | undefined;
-    let fromState: State | undefined;
-    let transitionStarted = false;
-    let controller: AbortController | null = null;
 
     try {
       toState = deps.buildNavigateState(name, params);
+    } catch (error) {
+      /* v8 ignore next 3 -- @preserve: reachable only via validator-driven
+         throws from buildNavigateState (validateStateBuilderArgs) — covered
+         in @real-router/validation-plugin's suite, not in core. */
+      return Promise.reject(error as Error);
+    }
 
-      if (!toState) {
-        deps.emitTransitionError(
-          undefined,
-          deps.getState(),
-          CACHED_ROUTE_NOT_FOUND_ERROR,
-        );
-        this.lastSyncRejected = true;
+    if (!toState) {
+      deps.emitTransitionError(
+        undefined,
+        deps.getState(),
+        CACHED_ROUTE_NOT_FOUND_ERROR,
+      );
+      this.lastSyncRejected = true;
 
-        return CACHED_ROUTE_NOT_FOUND_REJECTION;
-      }
+      return CACHED_ROUTE_NOT_FOUND_REJECTION;
+    }
+
+    return this.#executeNavigation(toState, opts);
+  }
+
+  /**
+   * Navigate to a fully-built `State` directly, skipping `buildNavigateState`
+   * (forwardState + buildPath + meta lookup). Used by URL plugins after they
+   * have already produced a `State` from a browser-initiated event via
+   * `api.matchPath(url)` — see issue #525.
+   *
+   * Semantics vs. `navigate(name, params, opts)`:
+   * - `forwardState` is NOT re-applied. matchPath already runs it; reapplying
+   *   is redundant in the idempotent case and can race in the dynamic case.
+   * - `buildPath` is NOT re-run. The caller's `state.path` is used as-is —
+   *   so `trailingSlash:"preserve"` matchedState paths flow through unchanged
+   *   (closes #525 Q2). `buildPath` interceptors do NOT run; the URL the
+   *   user navigated to is the source of truth for this code path.
+   * - All other pipeline steps run unchanged: SAME_STATES check, FSM
+   *   transition, guards, `subscribeLeave`, `completeTransition`,
+   *   plugin lifecycle hooks.
+   */
+  navigateToState(state: State, opts: NavigationOptions): Promise<State> {
+    this.lastSyncResolved = false;
+    const deps = this.#deps;
+
+    if (!deps.canNavigate()) {
+      this.lastSyncRejected = true;
 
+      return CACHED_NOT_STARTED_REJECTION;
+    }
+
+    // Reject states whose route no longer exists (e.g. the route tree was
+    // mutated between matchPath and navigateToState). UNKNOWN_ROUTE is
+    // structurally legal — it is the navigateToNotFound output shape.
+    if (state.name !== constants.UNKNOWN_ROUTE && !deps.hasRoute(state.name)) {
+      const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+        routeName: state.name,
+      });
+
+      deps.emitTransitionError(undefined, deps.getState(), err);
+      this.lastSyncRejected = true;
+
+      return Promise.reject(err);
+    }
+
+    // States from `matchPath` are deeply frozen (`freezeStateInPlace`).
+    // `completeTransition` mutates `toState.transition` and `context` is
+    // intentionally extensible for plugin claim writes, so we hand the
+    // pipeline a writable shell — same shape `makeState(skipFreeze=true)`
+    // produces. `params` stays referentially shared (already frozen).
+    // `transition` is omitted so completeTransition can assign it.
+    const writableState = {
+      name: state.name,
+      params: state.params,
+      path: state.path,
+      context: { ...state.context },
+    } as State;
+
+    return this.#executeNavigation(writableState, opts);
+  }
+
+  navigateToDefault(opts: NavigationOptions): Promise<State> {
+    const deps = this.#deps;
+    const options = deps.getOptions();
+
+    if (!options.defaultRoute) {
+      return Promise.reject(
+        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+          routeName: "defaultRoute not configured",
+        }),
+      );
+    }
+
+    let route: string;
+    let params: Params;
+
+    try {
+      ({ route, params } = deps.resolveDefault());
+    } catch (error) {
+      return Promise.reject(error as Error);
+    }
+
+    if (!route) {
+      return Promise.reject(
+        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+          routeName: "defaultRoute resolved to empty",
+        }),
+      );
+    }
+
+    return this.navigate(route, params, opts);
+  }
+
+  navigateToNotFound(path: string): State {
+    this.#abortPreviousNavigation();
+
+    const fromState = this.#deps.getState();
+    const deactivated: string[] = fromState
+      ? nameToIDs(fromState.name).toReversed()
+      : [];
+
+    Object.freeze(deactivated);
+
+    const segments: TransitionMeta["segments"] = {
+      deactivated,
+      activated: FROZEN_ACTIVATED,
+      intersection: "",
+    };
+
+    Object.freeze(segments);
+
+    const transitionMeta: TransitionMeta = {
+      phase: "activating",
+      ...(fromState && { from: fromState.name }),
+      reason: "success",
+      segments,
+    };
+
+    Object.freeze(transitionMeta);
+
+    const state: State = {
+      name: constants.UNKNOWN_ROUTE,
+      params: EMPTY_PARAMS as Params,
+      path,
+      transition: transitionMeta,
+      context: {},
+    };
+
+    Object.freeze(state);
+
+    this.#deps.setState(state);
+    this.#deps.emitTransitionSuccess(state, fromState, FROZEN_REPLACE_OPTS);
+
+    return state;
+  }
+
+  abortCurrentNavigation(): void {
+    this.#currentController?.abort(
+      new RouterError(errorCodes.TRANSITION_CANCELLED),
+    );
+    this.#currentController = null;
+  }
+
+  #executeNavigation(toState: State, opts: NavigationOptions): Promise<State> {
+    const deps = this.#deps;
+    let fromState: State | undefined;
+    let transitionStarted = false;
+    let controller: AbortController | null = null;
+
+    try {
       fromState = deps.getState();
       opts = forceReplaceFromUnknown(opts, fromState);
 
@@ -256,88 +408,6 @@ export class NavigationNamespace {
     }
   }
 
-  navigateToDefault(opts: NavigationOptions): Promise<State> {
-    const deps = this.#deps;
-    const options = deps.getOptions();
-
-    if (!options.defaultRoute) {
-      return Promise.reject(
-        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-          routeName: "defaultRoute not configured",
-        }),
-      );
-    }
-
-    let route: string;
-    let params: Params;
-
-    try {
-      ({ route, params } = deps.resolveDefault());
-    } catch (error) {
-      return Promise.reject(error as Error);
-    }
-
-    if (!route) {
-      return Promise.reject(
-        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-          routeName: "defaultRoute resolved to empty",
-        }),
-      );
-    }
-
-    return this.navigate(route, params, opts);
-  }
-
-  navigateToNotFound(path: string): State {
-    this.#abortPreviousNavigation();
-
-    const fromState = this.#deps.getState();
-    const deactivated: string[] = fromState
-      ? nameToIDs(fromState.name).toReversed()
-      : [];
-
-    Object.freeze(deactivated);
-
-    const segments: TransitionMeta["segments"] = {
-      deactivated,
-      activated: FROZEN_ACTIVATED,
-      intersection: "",
-    };
-
-    Object.freeze(segments);
-
-    const transitionMeta: TransitionMeta = {
-      phase: "activating",
-      ...(fromState && { from: fromState.name }),
-      reason: "success",
-      segments,
-    };
-
-    Object.freeze(transitionMeta);
-
-    const state: State = {
-      name: constants.UNKNOWN_ROUTE,
-      params: EMPTY_PARAMS as Params,
-      path,
-      transition: transitionMeta,
-      context: {},
-    };
-
-    Object.freeze(state);
-
-    this.#deps.setState(state);
-    this.#deps.emitTransitionSuccess(state, fromState, FROZEN_REPLACE_OPTS);
-
-    return state;
-  }
-
-  abortCurrentNavigation(): void {
-    this.#currentController?.abort(
-      new RouterError(errorCodes.TRANSITION_CANCELLED),
-    );
-    this.#currentController = null;
-  }
-
   async #finishAsyncNavigation(
     guardCompletion: Promise<void>,
     nav: NavigationContext,

package/src/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts

@@ -60,11 +60,11 @@ export class RouterLifecycleNamespace {
     deps.completeStart();
 
     if (matchedState) {
-      return deps.navigate(
-        matchedState.name,
-        matchedState.params,
-        REPLACE_OPTS,
-      );
+      // navigateToState commits matchedState verbatim — same primitive URL
+      // plugins use on popstate / navigate-event (#525). Keeps trailing-slash
+      // and any other source-URL flavor that matchPath produced; skips the
+      // redundant forwardState+buildPath round-trip in buildNavigateState.
+      return deps.navigateToState(matchedState, REPLACE_OPTS);
     }
 
     return deps.navigateToNotFound(startPath);

package/src/namespaces/RouterLifecycleNamespace/types.ts

@@ -9,11 +9,15 @@ import type {
 
 export interface RouterLifecycleDependencies {
   getOptions: () => Options;
-  navigate: (
-    name: string,
-    params: Params,
-    opts: NavigationOptions,
-  ) => Promise<State>;
+  /**
+   * Commit a fully-resolved State without re-running `forwardState`/`buildPath`.
+   * `start(path)` uses this to commit `matchPath(path)` directly — the same
+   * primitive URL plugins use on popstate / navigate-event (#525). Keeps
+   * `state.path` identical to the source URL (preserves trailing slash in
+   * `trailingSlash:"preserve"` mode) and avoids the redundant
+   * forwardState+buildPath round-trip in `buildNavigateState`.
+   */
+  navigateToState: (state: State, opts: NavigationOptions) => Promise<State>;
   navigateToNotFound: (path: string) => State;
   clearState: () => void;
   matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;

package/src/types/RouterValidator.ts

@@ -124,6 +124,7 @@ export interface RouterValidator {
   navigation: {
     validateNavigateArgs: (name: unknown) => void;
     validateNavigateToDefaultArgs: (options: unknown) => void;
+    validateNavigateToStateArgs: (state: unknown) => void;
     validateNavigationOptions: (options: unknown, caller: string) => void;
     validateParams: (params: unknown, methodName: string) => void;
     validateStartArgs: (path: unknown) => void;

package/src/utils/hydrateRouter.ts

@@ -0,0 +1,33 @@
+import type { Router, State } from "@real-router/types";
+
+/**
+ * Hydrate a fresh router from server-serialized State (#563).
+ *
+ * Accepts either a JSON string (parsed via `JSON.parse`) or a State-shaped
+ * object. Extracts `state.path` and delegates to `router.start(state.path)` —
+ * the canonical URL is the source of truth for the router on hydration.
+ *
+ * The serialized State (produced by `serializeRouterState`) is still useful
+ * for application-level concerns: `state.context.<namespace>` payloads (e.g.
+ * server-side data from `ssr-data-plugin`) can be read separately by app code
+ * before or after `hydrateRouter` resolves.
+ *
+ * @example
+ * ```typescript
+ * // Client
+ * const router = createAppRouter();
+ * router.usePlugin(browserPluginFactory());
+ * await hydrateRouter(router, window.__SSR_STATE__);
+ * ```
+ */
+export function hydrateRouter(
+  router: Router,
+  source: string | { path: string },
+): Promise<State> {
+  const parsed =
+    typeof source === "string"
+      ? (JSON.parse(source) as { path: string })
+      : source;
+
+  return router.start(parsed.path);
+}

package/src/utils/index.ts

@@ -1,5 +1,11 @@
 export { getStaticPaths } from "./getStaticPaths";
 
+export { hydrateRouter } from "./hydrateRouter";
+
+export { serializeRouterState } from "./serializeRouterState";
+
+export type { SerializeRouterStateOptions } from "./serializeRouterState";
+
 export { serializeState } from "./serializeState";
 
 export type { StaticPathEntries } from "./getStaticPaths";

package/src/utils/serializeRouterState.ts

@@ -0,0 +1,73 @@
+import { serializeState } from "./serializeState";
+
+import type { State } from "@real-router/types";
+
+export interface SerializeRouterStateOptions {
+  /**
+   * Plugin context namespaces to strip from the serialized output.
+   * Use when a plugin populates `state.context.<ns>` with non-JSON-serializable
+   * values (e.g., RSC payload: ReactNode trees containing functions/symbols).
+   *
+   * @default []
+   */
+  excludeContext?: readonly string[];
+}
+
+/**
+ * XSS-safe JSON serialization of router State for SSR → client transport (#563).
+ *
+ * Strips `state.transition` (per-navigation `TransitionMeta` — meaningless after
+ * hydration; the client's hydration commit produces its own `transition`).
+ * Keeps `name`, `params`, `path`, and `context` (plugin context namespaces are
+ * preserved as-is — server's `state.context.data` from `ssr-data-plugin` and
+ * any other plugin claims travel to the client untouched).
+ *
+ * Pass `options.excludeContext` to strip specific namespaces from the output —
+ * required for plugins that publish non-JSON-serializable values (e.g., RSC
+ * `ReactNode` trees from `@real-router/rsc-server-plugin`).
+ *
+ * @example
+ * ```typescript
+ * // Server
+ * const state = await router.start(req.url);
+ * const html = `<script>window.__SSR_STATE__=${serializeRouterState(state)}</script>`;
+ *
+ * // Client
+ * await hydrateRouter(router, window.__SSR_STATE__);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With RSC plugin: strip the "rsc" namespace before transport
+ * const state = await router.start(url);
+ * const json = serializeRouterState(state, { excludeContext: ["rsc"] });
+ * ```
+ */
+export function serializeRouterState(
+  state: State,
+  options?: SerializeRouterStateOptions,
+): string {
+  const exclude = options?.excludeContext;
+
+  let context = state.context;
+
+  if (exclude?.length) {
+    const filtered: Record<string, unknown> = {};
+    const source = state.context as Record<string, unknown>;
+
+    for (const key of Object.keys(source)) {
+      if (!exclude.includes(key)) {
+        filtered[key] = source[key];
+      }
+    }
+
+    context = filtered;
+  }
+
+  return serializeState({
+    name: state.name,
+    params: state.params,
+    path: state.path,
+    context,
+  });
+}

package/src/wiring/RouterWiringBuilder.ts

@@ -225,8 +225,8 @@ export class RouterWiringBuilder<
   wireLifecycleDeps(): void {
     const lifecycleDeps: RouterLifecycleDependencies = {
       getOptions: () => this.options.get(),
-      navigate: (name, params, opts) =>
-        this.navigation.navigate(name, params, opts),
+      navigateToState: (state, opts) =>
+        this.navigation.navigateToState(state, opts),
       navigateToNotFound: (path) => this.navigation.navigateToNotFound(path),
       clearState: () => {
         this.state.set(undefined);