@real-router/core 0.78.0 → 0.79.1

package/dist/esm/types.d.mts

@@ -1,2 +1,208 @@
-import { $ as State, A as LeaveFn, B as PluginFactory, C as PluginMethod, D as ForwardToCallback, E as DefaultRouteCallback, F as LogLevelConfig, G as SubscribeFn, H as RouteConfigUpdate, I as LoggerConfig, J as LimitsConfig, K as SubscribeState, L as Navigator, M as Listener, N as LogCallback, O as GuardFn, P as LogLevel, Q as SimpleState, R as Options, S as EventsKeys, T as DefaultParamsCallback, U as Router, V as Route, W as RouterLogger, X as Params, Y as NavigationOptions, Z as RouterError, _ as ErrorCodeValues, a as LifecycleApi, at as Unsubscribe, b as EventToNameMap, c as TreeChangedAdd, ct as RouteParams, d as TreeChangedRemove, et as StateContext, f as TreeChangedReplace, g as ErrorCodeToValueMap, h as ErrorCodeKeys, i as InterceptorFn, it as TransitionReason, j as LeaveState, k as GuardFnFactory, l as TreeChangedClear, lt as RouteTreeState, m as TreeStructuralPatch, n as DependenciesApi, nt as TransitionMeta, o as PluginApi, ot as QueryParamsMode, p as TreeChangedUpdate, q as Subscription, r as InterceptableMethodMap, rt as TransitionPhase, s as RoutesApi, st as QueryParamsOptions, t as ContextNamespaceClaim, tt as StateMetaInput, u as TreeChangedEvent, v as EventMethodMap, w as DefaultDependencies, x as EventToPluginMap, y as EventName, z as Plugin } from "./index-CAnGQpnz.mjs";
-export type { ContextNamespaceClaim, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, InterceptableMethodMap, InterceptorFn, LeaveFn, LeaveState, LifecycleApi, LimitsConfig, Listener, LogCallback, LogLevel, LogLevelConfig, LoggerConfig, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RouterLogger, RoutesApi, SimpleState, State, StateContext, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, TreeChangedAdd, TreeChangedClear, TreeChangedEvent, TreeChangedRemove, TreeChangedReplace, TreeChangedUpdate, TreeStructuralPatch, Unsubscribe };
+import { QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState } from "./types/route-node-types.mjs";
+import { Params, RouterError, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe } from "./types/base.mjs";
+import { LimitsConfig } from "./types/limits.mjs";
+import { DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ForwardToCallback, GuardFn, GuardFnFactory, LeaveFn, LeaveState, Listener, LogCallback, LogLevel, LogLevelConfig, LoggerConfig, Navigator, Options, Plugin, PluginFactory, Route, RouteConfigUpdate, Router, RouterLogger, SubscribeFn, SubscribeState, Subscription } from "./types/router.mjs";
+import { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod } from "./types/constants.mjs";
+import { TreeChangedAdd, TreeChangedClear, TreeChangedEvent, TreeChangedRemove, TreeChangedReplace, TreeChangedUpdate, TreeStructuralPatch } from "./types/tree-changed.mjs";
+import { ContextNamespaceClaim, DependenciesApi, InterceptableMethodMap, InterceptorFn, LifecycleApi, PluginApi, RoutesApi } from "./types/api.mjs";
+//#region src/types/index.d.ts
+/**
+ * Empty interface extended by plugins via module augmentation to declare
+ * typed `state.context.<namespace>` fields.
+ *
+ * @description
+ * Plugins add typed context namespaces by augmenting this interface:
+ *
+ * ```typescript
+ * declare module "@real-router/core/types" {
+ *   interface StateContext {
+ *     navigation: { direction: "forward" | "back" | "navigate" };
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, `state.context.navigation` becomes typed. The intersection
+ * with `Record<string, unknown>` in {@link State.context} keeps the type open,
+ * so plugins that don't augment can still write arbitrary namespaces.
+ *
+ * @see {@link State.context}
+ * @see {@link ContextNamespaceClaim}
+ */
+interface StateContext {}
+/**
+ * Configuration options that control navigation transition behavior.
+ *
+ * @description
+ * NavigationOptions provides fine-grained control over how the router performs navigation
+ * transitions. These options affect history management, transition lifecycle execution,
+ * guard enforcement, and state comparison logic.
+ *
+ * All options are optional and have sensible defaults. Options can be combined to achieve
+ * complex navigation behaviors. These options are available to guards and event listeners.
+ *
+ * @see {@link Router.navigate} for navigation method that accepts these options
+ */
+interface NavigationOptions {
+  /**
+   * Replace the current history entry instead of pushing a new one.
+   *
+   * @description
+   * When `true`, the navigation will replace the current entry in browser history instead
+   * of adding a new entry. This is typically used by history plugins (browser plugin) to
+   * control how navigation affects the browser's back/forward buttons.
+   *
+   * @default false
+   *
+   * @example
+   * // Redirect after login - prevent back button to login page
+   * router.navigate('dashboard', {}, { replace: true });
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState}
+   */
+  replace?: boolean | undefined;
+  /**
+   * Marks a `replace()` state-revalidation emit — a core-set signal, NOT a
+   * user-facing navigation option.
+   *
+   * @description
+   * `getRoutesApi(router).replace(...)` revalidates the active state against the
+   * new tree and emits `TRANSITION_SUCCESS` (#950). Core sets `revalidate: true`
+   * on that emit so a plugin's `onTransitionSuccess(toState, fromState, opts)`
+   * can distinguish a revalidation from a real navigation — both otherwise carry
+   * `replace: true` and are indistinguishable (#1201). Passing it to
+   * `router.navigate(...)` has no effect on the navigation itself.
+   *
+   * @default undefined
+   */
+  revalidate?: boolean | undefined;
+  /**
+   * Force reload of the current route even if states are equal.
+   *
+   * @description
+   * When `true`, bypasses the "same state" check that normally prevents navigation when
+   * the target state equals the current state. This forces a full transition lifecycle
+   * execution, allowing route components to reload with the same parameters.
+   *
+   * Without `reload`:
+   * - Navigation to current route throws SAME_STATES error
+   * - No lifecycle hooks execute
+   * - No events are fired
+   *
+   * With `reload`:
+   * - Full transition executes (deactivate → activate)
+   * - All lifecycle hooks run again
+   * - TRANSITION_SUCCESS event fires with same state
+   * - State object is recreated (new reference)
+   *
+   * @default false
+   *
+   * @example
+   * // Refresh current page data
+   * router.navigate(currentRoute.name, currentRoute.params, { reload: true });
+   *
+   * @example
+   * // Force re-fetch on same route with different query params
+   * // Note: query params are in path, not checked for equality
+   * router.navigate('search', { term: 'react' }, { reload: true });
+   *
+   * @see {@link force} for alternative that forces transition
+   * @see {@link Router.areStatesEqual} for state comparison logic
+   */
+  reload?: boolean | undefined;
+  /**
+   * Force navigation even if target state equals current state.
+   *
+   * @description
+   * When `true`, bypasses the "same state" equality check but still executes the full
+   * transition lifecycle. Similar to `reload` but can be used
+   * for any forced navigation scenario.
+   *
+   * Difference from `reload`:
+   * - `reload`: semantic meaning is "refresh current route"
+   * - `force`: general-purpose bypass of equality check
+   * - Both have identical implementation effect
+   *
+   * The equality check compares:
+   * - state.name (route name)
+   * - state.params (route parameters, shallow comparison)
+   *
+   * @default false
+   *
+   * @example
+   * // Force transition for tracking even if params didn't change
+   * router.navigate('analytics', { event: 'pageview' }, { force: true });
+   *
+   * @see {@link reload} for semantic equivalent (preferred for refresh scenarios)
+   */
+  force?: boolean | undefined;
+  /**
+   * Skip canDeactivate guards during transition.
+   *
+   * @description
+   * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
+   * deactivated. canActivate guards still execute normally. This allows
+   * forcing navigation away from routes with confirmation dialogs or unsaved changes.
+   *
+   * Skipped vs executed:
+   * ```
+   * // Normal transition
+   * deactivate(fromSegments) → activate(toSegments) → success
+   *
+   * // With forceDeactivate: true
+   * [skip deactivate] → activate(toSegments) → success
+   * ```
+   *
+   * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
+   *
+   * @default false
+   *
+   * @example
+   * // Force logout even with unsaved changes
+   * function forceLogout() {
+   *   router.navigate('login', {}, {
+   *     forceDeactivate: true,
+   *     replace: true
+   *   });
+   * }
+   *
+   * @see {@link Router.clearCanDeactivate} for programmatically clearing guards
+   */
+  forceDeactivate?: boolean | undefined;
+  /**
+   * Internal flag indicating navigation is result of a redirect.
+   *
+   * @internal
+   *
+   * @description
+   * Automatically set by the router when a navigation is triggered by a redirect.
+   * Available on `state.transition` after successful navigation (not during guard execution).
+   *
+   * @default false (auto-set by router during redirects)
+   *
+   * @example
+   * // Accessing redirect flag in TRANSITION_SUCCESS listener
+   * router.addEventListener('TRANSITION_SUCCESS', (state) => {
+   *   if (state.transition?.redirected) {
+   *     console.log('This navigation is from a redirect');
+   *   }
+   * });
+   *
+   * @see {@link Router.navigate} for redirect handling implementation
+   * @see {@link NavigationOptions.redirected} for the input mechanism
+   */
+  redirected?: boolean | undefined;
+  /**
+   * Optional abort signal for cancelling the navigation.
+   *
+   * @description
+   * When provided, this signal can be used to cancel the navigation operation.
+   * If the signal is aborted, the navigation will be cancelled and any pending
+   * guards or transitions will be interrupted.
+   *
+   * @default undefined
+   */
+  signal?: AbortSignal | undefined;
+}
+//#endregion
+export { type ContextNamespaceClaim, type DefaultDependencies, type DefaultParamsCallback, type DefaultRouteCallback, type DependenciesApi, type ErrorCodeKeys, type ErrorCodeToValueMap, type ErrorCodeValues, type EventMethodMap, type EventName, type EventToNameMap, type EventToPluginMap, type EventsKeys, type ForwardToCallback, type GuardFn, type GuardFnFactory, type InterceptableMethodMap, type InterceptorFn, type LeaveFn, type LeaveState, type LifecycleApi, type LimitsConfig, type Listener, type LogCallback, type LogLevel, type LogLevelConfig, type LoggerConfig, NavigationOptions, type Navigator, type Options, type Params, type Plugin, type PluginApi, type PluginFactory, type PluginMethod, type QueryParamsMode, type QueryParamsOptions, type Route, type RouteConfigUpdate, type RouteParams, type RouteTreeState, type Router, type RouterError, type RouterLogger, type RoutesApi, type SimpleState, type State, StateContext, type StateMetaInput, type SubscribeFn, type SubscribeState, type Subscription, type TransitionMeta, type TransitionPhase, type TransitionReason, type TreeChangedAdd, type TreeChangedClear, type TreeChangedEvent, type TreeChangedRemove, type TreeChangedReplace, type TreeChangedUpdate, type TreeStructuralPatch, type Unsubscribe };
+//# sourceMappingURL=types.d.mts.map

package/dist/esm/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/types/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA0DiB;;;;;;;;;;;;;;UAeA;;;;;;;;;;;;;;;;;EAiBf;;;;;;;;;;;;;;;EAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCA;;;;;;;;;;;;;;;;;;;;;;;EAwBA;;;;;;;;;;;EAYA,SAAS"}

package/dist/esm/utils/createRequestScope.d.mts

@@ -0,0 +1,111 @@
+import { DefaultDependencies, Router } from "../types/router.mjs";
+import { Router as Router$1 } from "../Router.mjs";
+//#region src/utils/createRequestScope.d.ts
+/**
+ * Subset of Node's `http.IncomingMessage` that `createRequestScope` relies on:
+ * a `"close"` event indicating that the client disconnected (or the response
+ * was fully sent) and the standard `removeListener` cleanup hook.
+ */
+interface IncomingMessageLike {
+  on: (event: "close", listener: () => void) => unknown;
+  removeListener?: (event: "close", listener: () => void) => unknown;
+}
+/**
+ * Web `Request`-shaped object — anything carrying an `AbortSignal`. Web
+ * runtimes (Bun, Cloudflare Workers, Vite RSC) surface client-disconnect via
+ * `request.signal` directly, so no listener attachment is needed.
+ */
+interface RequestLike {
+  signal: AbortSignal;
+}
+type RequestScopeSource = IncomingMessageLike | RequestLike;
+interface RequestScope<Dependencies extends DefaultDependencies = DefaultDependencies> extends AsyncDisposable {
+  /**
+   * Per-request router clone. Carries `abortSignal` injected into its
+   * dependencies — loaders can `getDep("abortSignal")` and pass it to fetch /
+   * `withTimeout` for cooperative cancellation when the client disconnects.
+   */
+  readonly router: Router$1<Dependencies>;
+  /**
+   * Aborts when the request closes (Node `IncomingMessage`'s `"close"` event)
+   * or when the upstream Web `Request.signal` aborts.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Detach the close listener (if attached to a Node `IncomingMessage`) and
+   * dispose the cloned router. Idempotent — safe to call multiple times or in
+   * combination with `Symbol.asyncDispose`.
+   */
+  dispose: () => Promise<void>;
+}
+/**
+ * Build a per-request router scope: clones `base`, attaches an `AbortSignal`
+ * tied to the request's lifetime, and exposes `dispose()` (plus
+ * `Symbol.asyncDispose` for `await using` declarations).
+ *
+ * Replaces the four-step boilerplate that every server entry repeats:
+ *
+ * 1. `new AbortController()` per request
+ * 2. `req.on("close", () => controller.abort())`
+ * 3. `cloneRouter(base, { ...deps, abortSignal: signal })`
+ * 4. `try { ... } finally { router.dispose() }`
+ *
+ * The signal is injected into the router clone under `abortSignal` so existing
+ * loaders that read `getDep("abortSignal")` keep working without changes. If
+ * `deps` already carries an `abortSignal`, the request-tied signal **wins** (it
+ * is spread last) — a caller-supplied `abortSignal` is intentionally overridden,
+ * since the scope's purpose is to own the request-lifecycle signal.
+ *
+ * ## `await using` compatibility
+ *
+ * The scope implements `Symbol.asyncDispose`, so `await using scope = …` is
+ * supported on runtimes that ship the well-known `Symbol.asyncDispose`:
+ *
+ * - **Node.js 24+** (full support; partial in 20.4–20.17 only for `fs`/`stream`)
+ * - **Bun 1.0.23+**, **Deno 1.37+**
+ * - **Chrome / Edge 127+**, **Firefox 141+**
+ * - **Safari**: not yet supported (irrelevant in practice — this helper is
+ *   server-side only and never reaches the browser)
+ *
+ * On Node.js 22 LTS the well-known symbol is unavailable, so `await using`
+ * fails. **The bundled SSR examples therefore use the explicit
+ * `try/finally` + `await scope.dispose()` form**, which works on every
+ * runtime. Use `await using` only when you control the deployment target and
+ * know it ships the symbol.
+ *
+ * @example
+ * ```typescript
+ * // Explicit dispose — works on Node 18+, all browsers, every CI image
+ * export async function render(url: string, req: IncomingMessage) {
+ *   const scope = createRequestScope(req, baseRouter, { currentUser });
+ *   try {
+ *     scope.router.usePlugin(ssrDataPluginFactory(loaders));
+ *     return await renderShell(scope.router, url);
+ *   } finally {
+ *     await scope.dispose();
+ *   }
+ * }
+ *
+ * // `await using` — Node 24+, Bun, Deno, modern browsers
+ * export async function render(url: string, req: IncomingMessage) {
+ *   await using scope = createRequestScope(req, baseRouter, { currentUser });
+ *   scope.router.usePlugin(ssrDataPluginFactory(loaders));
+ *   return await renderShell(scope.router, url);
+ * }
+ *
+ * // Web runtime (signal already on the request)
+ * async function handler(request: Request) {
+ *   const scope = createRequestScope(request, baseRouter, { db });
+ *   try {
+ *     scope.router.usePlugin(rscServerPluginFactory(loaders));
+ *     return await render(scope.router, request.url);
+ *   } finally {
+ *     await scope.dispose();
+ *   }
+ * }
+ * ```
+ */
+declare function createRequestScope<Dependencies extends DefaultDependencies = DefaultDependencies>(request: RequestScopeSource, base: Router<Dependencies>, deps?: Partial<Dependencies>): RequestScope<Dependencies>;
+//#endregion
+export { IncomingMessageLike, RequestLike, RequestScope, RequestScopeSource, createRequestScope };
+//# sourceMappingURL=createRequestScope.d.mts.map

package/dist/esm/utils/createRequestScope.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRequestScope.d.mts","names":[],"sources":["../../../src/utils/createRequestScope.ts"],"mappings":";;;;;;;;UAUiB;EACf,KAAK,gBAAgB;EACrB,kBAAkB,gBAAgB;;;;;;;UAQnB;EACf,QAAQ;;KAGE,qBAAqB,sBAAsB;UAEtC,aACf,qBAAqB,sBAAsB,6BACnC;;;;;;WAMC,QAAQ,SAAY;;;;;WAMpB,QAAQ;;;;;;EAOjB,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+ED,mBACd,qBAAqB,sBAAsB,qBAE3C,SAAS,oBACT,MAAM,OAAO,eACb,OAAO,QAAQ,gBACd,aAAa"}

package/dist/esm/utils/getStaticPaths.d.mts

@@ -0,0 +1,7 @@
+import { DefaultDependencies, Router } from "../types/router.mjs";
+//#region src/utils/getStaticPaths.d.ts
+type StaticPathEntries = Record<string, () => Promise<Record<string, string>[]>>;
+declare function getStaticPaths<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>, entries?: StaticPathEntries): Promise<string[]>;
+//#endregion
+export { StaticPathEntries, getStaticPaths };
+//# sourceMappingURL=getStaticPaths.d.mts.map

package/dist/esm/utils/getStaticPaths.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getStaticPaths.d.mts","names":[],"sources":["../../../src/utils/getStaticPaths.ts"],"mappings":";;KAKY,oBAAoB,qBAExB,QAAQ;iBA2BM,eACpB,qBAAqB,sBAAsB,qBAE3C,QAAQ,OAAO,eACf,UAAU,oBACT"}

package/dist/esm/utils/hydrateRouter.d.mts

@@ -0,0 +1,69 @@
+import { State } from "../types/base.mjs";
+import { Router } from "../types/router.mjs";
+//#region src/utils/hydrateRouter.d.ts
+/**
+ * Custom deserializer signature for {@link hydrateRouter} (#606). Compatible
+ * with `JSON.parse` (default), `devalue.parse`, `superjson.parse`, or any
+ * user-supplied function.
+ */
+type Deserialize = (json: string) => unknown;
+interface HydrateRouterOptions {
+  /**
+   * Custom deserializer (e.g., `devalue.parse` / `superjson.parse`) for
+   * matching the `serialize` passed to {@link serializeRouterState}. Defaults
+   * to `JSON.parse`. Ignored when `source` is already an object.
+   *
+   * @default JSON.parse
+   *
+   * @example
+   * ```typescript
+   * import * as devalue from "devalue";
+   * await hydrateRouter(router, ssrJson, { deserialize: devalue.parse });
+   * ```
+   */
+  deserialize?: Deserialize;
+}
+/**
+ * Hydrate a fresh router from server-serialized State (#563, #596).
+ *
+ * Accepts either a JSON string (parsed via `JSON.parse` by default, or
+ * `options.deserialize` when provided) 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 full parsed state (incl. `state.context.<namespace>` payloads) is
+ * deposited into a one-shot scratchpad on `RouterInternals.hydrationState`
+ * before `start()` is invoked and cleared in the matching `finally`. SSR
+ * loader plugins (`@real-router/ssr-data-plugin`,
+ * `@real-router/rsc-server-plugin`) read this scratchpad to skip their loader
+ * call when the server-resolved namespace value is already present — avoiding
+ * the post-hydration loader re-run on first paint.
+ *
+ * Single-shot semantics: the scratchpad is consumed during the first `start()`
+ * triggered by `hydrateRouter` regardless of route mismatch; subsequent
+ * `start()` calls run loaders normally.
+ *
+ * @example
+ * ```typescript
+ * // Client
+ * const router = createAppRouter();
+ * router.usePlugin(browserPluginFactory());
+ * await hydrateRouter(router, window.__SSR_STATE__);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With non-JSON types (Date / Map / Set / RegExp / BigInt) via devalue (#606)
+ * import * as devalue from "devalue";
+ *
+ * await hydrateRouter(router, window.__SSR_STATE__, {
+ *   deserialize: devalue.parse,
+ * });
+ * ```
+ */
+declare function hydrateRouter(router: Router, source: string | {
+  path: string;
+}, options?: HydrateRouterOptions): Promise<State>;
+//#endregion
+export { Deserialize, HydrateRouterOptions, hydrateRouter };
+//# sourceMappingURL=hydrateRouter.d.mts.map

package/dist/esm/utils/hydrateRouter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrateRouter.d.mts","names":[],"sources":["../../../src/utils/hydrateRouter.ts"],"mappings":";;;;;;;;KAUY,eAAe;UAEV;;;;;;;;;;;;;;EAcf,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyCM,cACpB,QAAQ,QACR;EAAmB;GACnB,UAAU,uBACT,QAAQ"}

package/dist/esm/utils/serializeRouterState.d.mts

@@ -0,0 +1,84 @@
+import { Params, State } from "../types/base.mjs";
+import { Serialize } from "./serializeState.mjs";
+//#region src/utils/serializeRouterState.d.ts
+/**
+ * Parsed shape produced by {@link serializeRouterState} (after `JSON.parse`).
+ *
+ * Identical to {@link State} minus `transition` (per-navigation `TransitionMeta`
+ * is meaningless after hydration; the client builds its own on commit). Used as
+ * the input shape for {@link hydrateRouter} and as the type of the one-shot
+ * hydration scratchpad consumed by SSR loader plugins.
+ */
+type SerializedRouterState<P extends Params = Params> = Omit<State<P>, "transition">;
+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[];
+  /**
+   * Custom serializer (e.g., `devalue.stringify` / `superjson.stringify`) to
+   * support non-JSON types in `state.params` and `state.context.<ns>` payloads
+   * (Date / Map / Set / RegExp / BigInt). Defaults to `JSON.stringify`.
+   *
+   * Pair with the matching `deserialize` on `hydrateRouter` to round-trip the
+   * extended types on the client.
+   *
+   * @default JSON.stringify
+   *
+   * @example
+   * ```typescript
+   * import * as devalue from "devalue";
+   *
+   * const json = serializeRouterState(state, { serialize: devalue.stringify });
+   * ```
+   */
+  serialize?: Serialize;
+}
+/**
+ * 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"] });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Non-JSON types (Date / Map / Set / RegExp / BigInt) via devalue (#606)
+ * import * as devalue from "devalue";
+ *
+ * const json = serializeRouterState(state, { serialize: devalue.stringify });
+ * // On the client:
+ * await hydrateRouter(router, json, { deserialize: devalue.parse });
+ * ```
+ */
+declare function serializeRouterState(state: State, options?: SerializeRouterStateOptions): string;
+//#endregion
+export { SerializeRouterStateOptions, SerializedRouterState, serializeRouterState };
+//# sourceMappingURL=serializeRouterState.d.mts.map

package/dist/esm/utils/serializeRouterState.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializeRouterState.d.mts","names":[],"sources":["../../../src/utils/serializeRouterState.ts"],"mappings":";;;;;;;;;;;KAaY,sBAAsB,UAAU,SAAS,UAAU,KAC7D,MAAM;UAIS;;;;;;;;EAQf;;;;;;;;;;;;;;;;;;EAmBA,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2CE,qBACd,OAAO,OACP,UAAU"}

package/dist/esm/utils/serializeState.d.mts

@@ -0,0 +1,50 @@
+//#region src/utils/serializeState.d.ts
+/**
+ * Custom serializer signature for {@link serializeState} (#606).
+ *
+ * Compatible with `JSON.stringify` (default) as well as `devalue.stringify`,
+ * `superjson.stringify`, or any user-supplied function that returns a JSON
+ * string. The output is run through XSS-safe character escapes regardless
+ * of which serializer produced it.
+ */
+type Serialize = (data: unknown) => string;
+interface SerializeStateOptions {
+  /**
+   * Custom serializer (e.g., `devalue.stringify` / `superjson.stringify`) to
+   * support non-JSON types (Date / Map / Set / RegExp / BigInt). Defaults to
+   * `JSON.stringify`. Output is still XSS-escaped.
+   *
+   * @default JSON.stringify
+   */
+  serialize?: Serialize;
+}
+/**
+ * XSS-safe JSON serialization for embedding data in HTML `<script>` tags.
+ *
+ * Escapes `<`, `>`, and `&` to their Unicode equivalents to prevent
+ * injection via `</script>` or HTML entities inside inline scripts.
+ *
+ * Pass `options.serialize` to use a custom serializer such as `devalue` or
+ * `superjson` for non-JSON types (Date/Map/Set/RegExp/BigInt). The serializer
+ * must return a string; XSS-escape is applied to its output.
+ *
+ * @example
+ * ```typescript
+ * const json = serializeState({ name: "home", path: "/" });
+ * const html = `<script>window.__STATE__=${json}</script>`;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as devalue from "devalue";
+ *
+ * const json = serializeState(
+ *   { date: new Date(), tags: new Set(["a", "b"]) },
+ *   { serialize: devalue.stringify },
+ * );
+ * ```
+ */
+declare function serializeState(data: unknown, options?: SerializeStateOptions): string;
+//#endregion
+export { Serialize, SerializeStateOptions, serializeState };
+//# sourceMappingURL=serializeState.d.mts.map

package/dist/esm/utils/serializeState.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializeState.d.mts","names":[],"sources":["../../../src/utils/serializeState.ts"],"mappings":";;;;;;;;;KAQY,aAAa;UAER;;;;;;;;EAQf,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BE,eACd,eACA,UAAU"}

package/dist/esm/utils.d.mts

@@ -1,2 +1,6 @@
-import { a as SerializeStateOptions, c as HydrateRouterOptions, d as getStaticPaths, f as IncomingMessageLike, g as createRequestScope, h as RequestScopeSource, i as Serialize, l as hydrateRouter, m as RequestScope, n as SerializedRouterState, o as serializeState, p as RequestLike, r as serializeRouterState, s as Deserialize, t as SerializeRouterStateOptions, u as StaticPathEntries } from "./index-DnSU6huX.mjs";
+import { IncomingMessageLike, RequestLike, RequestScope, RequestScopeSource, createRequestScope } from "./utils/createRequestScope.mjs";
+import { StaticPathEntries, getStaticPaths } from "./utils/getStaticPaths.mjs";
+import { Deserialize, HydrateRouterOptions, hydrateRouter } from "./utils/hydrateRouter.mjs";
+import { Serialize, SerializeStateOptions, serializeState } from "./utils/serializeState.mjs";
+import { SerializeRouterStateOptions, SerializedRouterState, serializeRouterState } from "./utils/serializeRouterState.mjs";
 export { type Deserialize, type HydrateRouterOptions, type IncomingMessageLike, type RequestLike, type RequestScope, type RequestScopeSource, type Serialize, type SerializeRouterStateOptions, type SerializeStateOptions, type SerializedRouterState, type StaticPathEntries, createRequestScope, getStaticPaths, hydrateRouter, serializeRouterState, serializeState };

package/dist/esm/utils.mjs

@@ -1,2 +1,2 @@
-import{f as e}from"./buildParamMeta-Bl0uORu6.mjs";import{r as t,t as n}from"./cloneRouter-CqS4kTs8.mjs";function r(e){return`signal`in e&&typeof e.signal==`object`&&e.signal!==void 0&&typeof e.signal.aborted==`boolean`}function i(e,t,i){let a,o,s;if(r(e))s=e.signal;else{let t=new AbortController,n=()=>{t.abort()};s=t.signal,o=()=>{e.on(`close`,n)},a=()=>{e.removeListener?.(`close`,n)}}let c=n(t,{...i,abortSignal:s});o?.();let l=!1,u=()=>l?Promise.resolve():(l=!0,a?.(),c.dispose(),Promise.resolve());return{router:c,signal:s,dispose:u,[Symbol.asyncDispose]:u}}function a(e,t){for(let n of e.children.values())n.children.size===0?t.push(n.fullName):a(n,t)}function o(e){let t=[];return a(e,t),t}async function s(e,n){let r=o(t(e).getTree()),i=[];for(let t of r){let r=n?.[t];if(r){let n=await r();for(let r of n)i.push(e.buildPath(t,r))}else i.push(e.buildPath(t,{}))}return i}async function c(t,n,r){let i=r?.deserialize??JSON.parse,a=typeof n==`string`?i(n):n,o=e(t),s=o.hydrationState;o.hydrationState=a;try{return await t.start(a.path)}finally{o.hydrationState=s}}function l(e,t){return((t?.serialize??JSON.stringify)(e)??`null`).replaceAll(`<`,String.raw`\u003c`).replaceAll(`>`,String.raw`\u003e`).replaceAll(`&`,String.raw`\u0026`)}function u(e,t){let n=t?.excludeContext,r=e.context;if(n?.length){let t=Object.create(null),i=e.context;for(let[e,r]of Object.entries(i))n.includes(e)||(t[e]=r);r=t}let i={name:e.name,params:e.params,path:e.path,context:r};return t?.serialize?l(i,{serialize:t.serialize}):l(i)}export{i as createRequestScope,s as getStaticPaths,c as hydrateRouter,u as serializeRouterState,l as serializeState};
+import{u as e}from"./buildParamMeta-bOLhLF9h.mjs";import{r as t,t as n}from"./cloneRouter-D4rnqmi9.mjs";function r(e){return`signal`in e&&typeof e.signal==`object`&&e.signal!==void 0&&typeof e.signal.aborted==`boolean`}function i(e,t,i){let a,o,s;if(r(e))s=e.signal;else{let t=new AbortController,n=()=>{t.abort()};s=t.signal,o=()=>{e.on(`close`,n)},a=()=>{e.removeListener?.(`close`,n)}}let c=n(t,{...i,abortSignal:s});o?.();let l=!1,u=()=>l?Promise.resolve():(l=!0,a?.(),c.dispose(),Promise.resolve());return{router:c,signal:s,dispose:u,[Symbol.asyncDispose]:u}}function a(e,t){for(let n of e.children.values())n.children.size===0?t.push(n.fullName):a(n,t)}function o(e){let t=[];return a(e,t),t}async function s(e,n){let r=o(t(e).getTree()),i=[];for(let t of r){let r=n?.[t];if(r){let n=await r();for(let r of n)i.push(e.buildPath(t,r))}else i.push(e.buildPath(t,{}))}return i}async function c(t,n,r){let i=r?.deserialize??JSON.parse,a=typeof n==`string`?i(n):n,o=e(t),s=o.hydrationState;o.hydrationState=a;try{return await t.start(a.path)}finally{o.hydrationState=s}}function l(e,t){return((t?.serialize??JSON.stringify)(e)??`null`).replaceAll(`<`,String.raw`\u003c`).replaceAll(`>`,String.raw`\u003e`).replaceAll(`&`,String.raw`\u0026`)}function u(e,t){let n=t?.excludeContext,r=e.context;if(n?.length){let t=Object.create(null),i=e.context;for(let[e,r]of Object.entries(i))n.includes(e)||(t[e]=r);r=t}let i={name:e.name,params:e.params,path:e.path,context:r};return t?.serialize?l(i,{serialize:t.serialize}):l(i)}export{i as createRequestScope,s as getStaticPaths,c as hydrateRouter,u as serializeRouterState,l as serializeState};
 //# sourceMappingURL=utils.mjs.map