@real-router/core 0.79.0 → 0.80.0

package/dist/cjs/types/router.d.ts

@@ -0,0 +1,313 @@
+import { QueryParamsMode, QueryParamsOptions } from "./route-node-types.js";
+import { Params, RouterError, State, Unsubscribe } from "./base.js";
+import { LimitsConfig } from "./limits.js";
+import { NavigationOptions } from "../types.js";
+//#region src/types/router.d.ts
+type LogLevel = "log" | "warn" | "error";
+type LogLevelConfig = "all" | "warn-error" | "error-only" | "none";
+type LogCallback = (level: LogLevel, context: string, message: string, ...args: unknown[]) => void;
+interface LoggerConfig {
+  level: LogLevelConfig;
+  callback?: LogCallback | undefined;
+  callbackIgnoresLevel?: boolean;
+}
+/**
+ * Per-router logging surface — the contract core writes through and plugins
+ * consume.
+ *
+ * Core stores a concrete instance on `RouterInternals.logger` (built from
+ * `options.logger` in the `Router` constructor); plugins and other consumers
+ * reach that same per-instance logger via `getPluginApi(router).logger`. The
+ * concrete `RouterLogger` class lives in core's `foundation/logger` — this
+ * interface is the shared contract, so nothing outside core needs to import the
+ * class (or depend on the former standalone `@real-router/logger` package).
+ */
+interface RouterLogger {
+  log: (context: string, message: string, ...args: unknown[]) => void;
+  warn: (context: string, message: string, ...args: unknown[]) => void;
+  error: (context: string, message: string, ...args: unknown[]) => void;
+}
+/**
+ * Callback function for dynamically resolving the default route.
+ * Receives a dependency getter function to access router dependencies.
+ */
+type DefaultRouteCallback<Dependencies = object> = (getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K]) => string;
+/**
+ * Callback function for dynamically resolving the forward target route.
+ * Receives a dependency getter function and current route parameters.
+ */
+type ForwardToCallback<Dependencies = object> = (getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K], params: Params) => string;
+/**
+ * Callback function for dynamically resolving the default parameters.
+ * Receives a dependency getter function to access router dependencies.
+ */
+type DefaultParamsCallback<Dependencies = object> = (getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K]) => Params;
+/**
+ * Router configuration options.
+ *
+ * Note: For input, use `Partial<Options>` as all fields have defaults.
+ * After initialization, `getOptions()` returns resolved `Options` with all fields populated.
+ */
+interface Options {
+  /**
+   * Default route to navigate to on start.
+   * Empty string means no default route.
+   *
+   * @default ""
+   */
+  defaultRoute: string | DefaultRouteCallback;
+  /**
+   * Default parameters for the default route.
+   *
+   * @default {}
+   */
+  defaultParams: Params | DefaultParamsCallback;
+  /**
+   * How to handle trailing slashes in URLs.
+   * - "strict": Route must match exactly
+   * - "never": Always remove trailing slash
+   * - "always": Always add trailing slash
+   * - "preserve": Keep the source path's trailing-slash choice, even when
+   *   `rewritePathOnMatch: true` rewrites the rest of the path.
+   *
+   * @default "preserve"
+   */
+  trailingSlash: "strict" | "never" | "always" | "preserve";
+  /**
+   * Whether route matching is case-sensitive.
+   *
+   * When `false`, a mixed-case URL matches a lower-case route (`/Team` matches a
+   * `/team` route). Dynamic param **values** keep their original case — only
+   * static literal segments are compared case-insensitively.
+   *
+   * Default `true` (spec-correct: RFC 3986 §6.2.2.1 treats URL paths as
+   * case-sensitive). Case-insensitive is an explicit **opt-in** for a narrow
+   * niche — server-less / hash / static-hosted / legacy routing where no server
+   * or edge layer can normalize the URL's case before it reaches the router. For
+   * public SSR/edge apps, prefer a canonical-lowercase redirect at the server
+   * instead (SEO / dedup). Note the divergence from React Router v7 / TanStack /
+   * vue-router, which default to case-**insensitive**.
+   *
+   * @default true
+   */
+  caseSensitive: boolean;
+  /**
+   * How to encode URL parameters.
+   * - "default": Standard encoding
+   * - "uri": URI encoding (encodeURI)
+   * - "uriComponent": Component encoding (encodeURIComponent)
+   * - "none": No encoding
+   *
+   * @default "default"
+   */
+  urlParamsEncoding: "default" | "uri" | "uriComponent" | "none";
+  /**
+   * How to handle query parameters.
+   *
+   * @default "loose"
+   */
+  queryParamsMode: QueryParamsMode;
+  /**
+   * Query parameter parsing options.
+   *
+   * @default undefined
+   */
+  queryParams?: QueryParamsOptions;
+  /**
+   * Allow matching routes that don't exist.
+   * When true, unknown routes navigate without error.
+   *
+   * @default true
+   */
+  allowNotFound: boolean;
+  /**
+   * Rewrite `state.path` on successful match to the canonical path built
+   * from the matched route's pattern. Applies `forwardTo` aliases, encoders,
+   * `defaultParams`, and `trailingSlash` normalization (`"never"` / `"always"`).
+   * When `trailingSlash: "preserve"`, the source path's trailing-slash choice
+   * is kept on the rewritten path.
+   *
+   * @default true
+   */
+  rewritePathOnMatch: boolean;
+  /**
+   * Logger configuration.
+   *
+   * @default undefined
+   */
+  logger?: Partial<LoggerConfig>;
+  /**
+   * Router resource limits configuration.
+   * Controls maximum allowed values for various router operations.
+   *
+   * @default DEFAULT_LIMITS (from LimitsNamespace)
+   */
+  limits?: Partial<LimitsConfig>;
+}
+type GuardFn = (toState: State, fromState: State | undefined, signal?: AbortSignal) => boolean | Promise<boolean>;
+type DefaultDependencies = object;
+interface Plugin {
+  onStart?: () => void;
+  onStop?: () => void;
+  onTransitionStart?: (toState: State, fromState?: State) => void;
+  onTransitionLeaveApprove?: (toState: State, fromState?: State) => void;
+  onTransitionCancel?: (toState: State, fromState?: State) => void;
+  onTransitionError?: (toState: State | undefined, fromState: State | undefined, err: RouterError) => void;
+  onTransitionSuccess?: (toState: State, fromState: State | undefined, opts: NavigationOptions) => void;
+  teardown?: () => void;
+}
+interface SubscribeState {
+  route: State;
+  previousRoute?: State | undefined;
+}
+type SubscribeFn = (state: SubscribeState) => void;
+interface LeaveState {
+  route: State;
+  nextRoute: State;
+  signal: AbortSignal;
+}
+type LeaveFn = (state: LeaveState) => void | Promise<void>;
+interface Listener {
+  [key: string]: unknown;
+  next: (val: unknown) => void;
+  error?: (err: unknown) => void;
+  complete?: () => void;
+}
+interface Subscription {
+  unsubscribe: Unsubscribe;
+}
+/**
+ * Navigator interface - a minimal, safe subset of Router methods.
+ *
+ * Provides only the essential navigation and state inspection methods.
+ * Excludes lifecycle methods (start, stop), plugin management, and internal APIs.
+ * Use this when you need to pass a limited router interface to components.
+ *
+ * For full router access, use the Router interface directly or the useRouter() hook.
+ */
+interface Navigator {
+  navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
+  getState: () => State | undefined;
+  isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+  canNavigateTo: (name: string, params?: Params) => boolean;
+  subscribe: (listener: SubscribeFn) => Unsubscribe;
+  subscribeLeave: (listener: LeaveFn) => Unsubscribe;
+  isLeaveApproved: () => boolean;
+}
+/**
+ * Router interface — full public API for route navigation and lifecycle management.
+ *
+ * Generic parameter D constrains dependency injection types.
+ * Factory types (PluginFactory, GuardFnFactory) self-reference this interface
+ * within the same file to avoid circular dependencies.
+ */
+interface Router<D extends DefaultDependencies = DefaultDependencies> {
+  [key: string]: unknown;
+  isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+  buildPath: (route: string, params?: Params) => string;
+  getState: <P extends Params = Params>() => State<P> | undefined;
+  getPreviousState: () => State | undefined;
+  areStatesEqual: (state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean) => boolean;
+  shouldUpdateNode: (nodeName: string) => (toState: State, fromState?: State) => boolean;
+  isActive: () => boolean;
+  start: (startPath: string) => Promise<State>;
+  stop: () => this;
+  dispose: () => void;
+  canNavigateTo: (name: string, params?: Params) => boolean;
+  usePlugin: (...plugins: (PluginFactory<D> | false | null | undefined)[]) => Unsubscribe;
+  subscribe: (listener: SubscribeFn) => Unsubscribe;
+  subscribeLeave: (listener: LeaveFn) => Unsubscribe;
+  isLeaveApproved: () => boolean;
+  navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
+  navigateToDefault: (options?: NavigationOptions) => Promise<State>;
+  navigateToNotFound: (path?: string) => State;
+}
+/**
+ * Factory function for creating plugins.
+ * Receives the router instance and a dependency getter.
+ */
+type PluginFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => Plugin;
+/**
+ * Factory function for creating guards.
+ * Receives the router instance and a dependency getter.
+ */
+type GuardFnFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => GuardFn;
+/**
+ * Route configuration.
+ */
+interface Route<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  [key: string]: unknown;
+  /** Route name (dot-separated for nested routes). */
+  name: string;
+  /** URL path pattern for this route. */
+  path: string;
+  /** Factory function that returns a guard for route activation. */
+  canActivate?: GuardFnFactory<Dependencies>;
+  /** Factory function that returns a guard for route deactivation. */
+  canDeactivate?: GuardFnFactory<Dependencies>;
+  /**
+   * Redirects navigation to another route.
+   *
+   * IMPORTANT: forwardTo creates a URL alias, not a transition chain.
+   * Guards (canActivate) on the source route are NOT executed.
+   * Only guards on the final destination are executed.
+   *
+   * This matches Vue Router and Angular Router behavior.
+   */
+  forwardTo?: string | ForwardToCallback<Dependencies>;
+  /** Nested child routes. */
+  children?: Route<Dependencies>[];
+  /** Encodes state params to URL params. */
+  encodeParams?: (stateParams: Params) => Params;
+  /** Decodes URL params to state params. */
+  decodeParams?: (pathParams: Params) => Params;
+  /**
+   * Default parameters for this route.
+   *
+   * These values are merged into state.params when creating route states.
+   * Missing URL params are filled from defaultParams.
+   */
+  defaultParams?: Params;
+}
+/**
+ * Configuration update options for `updateRoute()`.
+ *
+ * All properties are optional. For every field, `null` removes the
+ * configuration, `undefined` (or omission) leaves it untouched, and any other
+ * value sets it — values are shallow-merged into the route by patch key.
+ *
+ * Besides the structural and guard fields below, `update` also patches
+ * **plugin-defined custom fields** (lifecycle hooks, `preload`, `searchSchema`,
+ * …), symmetric with how `add`/`replace` register them. This interface is
+ * **augmentable**: a plugin declares its updatable field via declaration
+ * merging, mirroring its `Route` augmentation but with `| null` to allow removal:
+ *
+ * ```ts
+ * declare module "@real-router/core" {
+ *   interface RouteConfigUpdate<Dependencies extends DefaultDependencies> {
+ *     onNavigate?: LifecycleHookFactory<Dependencies> | null;
+ *   }
+ * }
+ * ```
+ *
+ * Note: `name` / `path` / `children` are route identity and are NOT patchable —
+ * use `remove` + `add` to restructure. The interface stays closed (no index
+ * signature) so typos in structural field names remain compile errors.
+ */
+interface RouteConfigUpdate<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  /** Set to null to remove forwardTo */
+  forwardTo?: string | ForwardToCallback<Dependencies> | null;
+  /** Set to null to remove defaultParams */
+  defaultParams?: Params | null;
+  /** Set to null to remove decoder */
+  decodeParams?: ((params: Params) => Params) | null;
+  /** Set to null to remove encoder */
+  encodeParams?: ((params: Params) => Params) | null;
+  /** Set to null to remove canActivate */
+  canActivate?: GuardFnFactory<Dependencies> | null;
+  /** Set to null to remove canDeactivate */
+  canDeactivate?: GuardFnFactory<Dependencies> | null;
+}
+//#endregion
+export { DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ForwardToCallback, GuardFn, GuardFnFactory, LeaveFn, LeaveState, Listener, LogCallback, LogLevel, LogLevelConfig, LoggerConfig, Navigator, Options, Plugin, PluginFactory, Route, RouteConfigUpdate, Router, RouterLogger, SubscribeFn, SubscribeState, Subscription };
+//# sourceMappingURL=router.d.ts.map

package/dist/cjs/types/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","names":[],"sources":["../../../src/types/router.ts"],"mappings":"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"}

package/dist/cjs/types/tree-changed.d.ts

@@ -0,0 +1,55 @@
+import { DefaultDependencies, Route, RouteConfigUpdate } from "./router.js";
+//#region src/types/tree-changed.d.ts
+/**
+ * The subset of {@link RouteConfigUpdate} fields that count as **structural**
+ * changes — the only ones that emit `TREE_CHANGED` from `update()`.
+ *
+ * Guard fields (`canActivate` / `canDeactivate`) are deliberately excluded:
+ * guards are invoked-on-demand (fresh-read per navigation), not cached derived
+ * state, so they need no observation channel.
+ */
+type TreeStructuralPatch<Dependencies extends DefaultDependencies = DefaultDependencies> = Pick<RouteConfigUpdate<Dependencies>, "forwardTo" | "defaultParams" | "encodeParams" | "decodeParams">;
+interface TreeChangedAdd<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  readonly op: "add";
+  /** Top-level routes that were added (deep-cloned + frozen; caller untouched). */
+  readonly added: readonly Route<Dependencies>[];
+  /** Parent route name when added via `add(routes, { parent })`. */
+  readonly parent?: string;
+}
+interface TreeChangedRemove<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  readonly op: "remove";
+  readonly name: string;
+  /**
+   * The removed route and all of its descendants, as a FLAT array (each entry's
+   * `name` is the full dotted name). Collected before the mutation.
+   */
+  readonly removedSubtree: readonly Route<Dependencies>[];
+}
+interface TreeChangedUpdate<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  readonly op: "update";
+  readonly name: string;
+  /** Structural fields only (deep-cloned + frozen; caller's patch untouched). */
+  readonly patch: Readonly<TreeStructuralPatch<Dependencies>>;
+}
+interface TreeChangedReplace<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  readonly op: "replace";
+  /** FLAT by all names (including descendants) present before but not after. */
+  readonly removed: readonly Route<Dependencies>[];
+  /** FLAT by all names (including descendants) present after but not before. */
+  readonly added: readonly Route<Dependencies>[];
+}
+interface TreeChangedClear<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  readonly op: "clear";
+  /** Top-level routes (with nested children) that existed before the clear. */
+  readonly removed: readonly Route<Dependencies>[];
+}
+/**
+ * Discriminated union (by `op`) describing a single structural route-tree
+ * mutation. Consumers should `switch (event.op)` with an exhaustive `default`
+ * — do not rely on `Object.keys(event)`, array ordering, or absence of future
+ * fields (see Invariant 11 in `.claude/rfc-tree-mutation-event.md`).
+ */
+type TreeChangedEvent<Dependencies extends DefaultDependencies = DefaultDependencies> = TreeChangedAdd<Dependencies> | TreeChangedRemove<Dependencies> | TreeChangedUpdate<Dependencies> | TreeChangedReplace<Dependencies> | TreeChangedClear<Dependencies>;
+//#endregion
+export { TreeChangedAdd, TreeChangedClear, TreeChangedEvent, TreeChangedRemove, TreeChangedReplace, TreeChangedUpdate, TreeStructuralPatch };
+//# sourceMappingURL=tree-changed.d.ts.map

package/dist/cjs/types/tree-changed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-changed.d.ts","names":[],"sources":["../../../src/types/tree-changed.ts"],"mappings":";;;;;;;;;;KAsBY,oBACV,qBAAqB,sBAAsB,uBACzC,KACF,kBAAkB;UAIH,eACf,qBAAqB,sBAAsB;WAElC;;WAEA,gBAAgB,MAAM;;WAEtB;;UAGM,kBACf,qBAAqB,sBAAsB;WAElC;WACA;;;;;WAKA,yBAAyB,MAAM;;UAGzB,kBACf,qBAAqB,sBAAsB;WAElC;WACA;;WAEA,OAAO,SAAS,oBAAoB;;UAG9B,mBACf,qBAAqB,sBAAsB;WAElC;;WAEA,kBAAkB,MAAM;;WAExB,gBAAgB,MAAM;;UAGhB,iBACf,qBAAqB,sBAAsB;WAElC;;WAEA,kBAAkB,MAAM;;;;;;;;KASvB,iBACV,qBAAqB,sBAAsB,uBAEzC,eAAe,gBACf,kBAAkB,gBAClB,kBAAkB,gBAClB,mBAAmB,gBACnB,iBAAiB"}

package/dist/cjs/types.d.ts

@@ -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.js";
-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.js";
+import { Params, RouterError, SerializedRouterState, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe } from "./types/base.js";
+import { LimitsConfig } from "./types/limits.js";
+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.js";
+import { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod } from "./types/constants.js";
+import { TreeChangedAdd, TreeChangedClear, TreeChangedEvent, TreeChangedRemove, TreeChangedReplace, TreeChangedUpdate, TreeStructuralPatch } from "./types/tree-changed.js";
+import { ContextNamespaceClaim, DependenciesApi, InterceptableMethodMap, InterceptorFn, LifecycleApi, PluginApi, RoutesApi } from "./types/api.js";
+//#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 SerializedRouterState, 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.ts.map

package/dist/cjs/types.d.ts.map

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