@real-router/core 0.78.0 → 0.79.1

package/dist/esm/index-CAnGQpnz.d.mts

@@ -1,974 +0,0 @@
-//#region src/types/route-node-types.d.ts
-/**
- * Route Node Type Definitions — Minimal Public API.
- *
- * This module exports ONLY the essential types used by real-router:
- * - QueryParamsMode, QueryParamsOptions
- * - RouteParams, RouteTreeState
- *
- * These types are copied from route-node to avoid circular dependencies.
- *
- * @module route-node-types
- */
-type ArrayFormat = "none" | "brackets" | "index" | "comma";
-type BooleanFormat = "none" | "auto" | "empty-true";
-type NullFormat = "default" | "hidden";
-type NumberFormat = "none" | "auto";
-/**
- * Options for query parameter parsing and building.
- */
-interface QueryParamsOptions {
-  arrayFormat?: ArrayFormat;
-  booleanFormat?: BooleanFormat;
-  nullFormat?: NullFormat;
-  numberFormat?: NumberFormat;
-}
-/**
- * Controls how query parameters are handled during matching.
- */
-type QueryParamsMode = "default" | "strict" | "loose";
-type ParamSource = "url" | "query";
-type ParamTypeMap = Record<string, ParamSource>;
-type RouteTreeStateMeta = Record<string, ParamTypeMap>;
-interface RouteParams {
-  [key: string]: string | string[] | number | number[] | boolean | boolean[] | RouteParams | RouteParams[] | Record<string, string | number | boolean> | null | undefined;
-}
-/**
- * Complete state representation of a matched route.
- */
-interface RouteTreeState<P extends Record<string, unknown> = RouteParams> {
-  name: string;
-  params: P;
-  meta: RouteTreeStateMeta;
-}
-//#endregion
-//#region src/types/base.d.ts
-/**
- * Detach function returned by subscription APIs.
- *
- * @description
- * Calling this function removes the associated listener. Returned by
- * `router.subscribe()`, `router.addEventListener()`, `router.subscribeLeave()`,
- * and plugin interceptors. Idempotent — calling more than once is safe and
- * has no additional effect after the first call.
- */
-type Unsubscribe = () => void;
-interface SimpleState<P extends Params = Params> {
-  name: string;
-  params: P;
-}
-type TransitionPhase = "deactivating" | "activating";
-type TransitionReason = "success" | "blocked" | "cancelled" | "error";
-interface TransitionMeta {
-  phase: TransitionPhase;
-  reason: TransitionReason;
-  reload?: boolean;
-  replace?: boolean;
-  redirected?: boolean;
-  from?: string;
-  blocker?: string;
-  segments: {
-    deactivated: string[];
-    activated: string[];
-    intersection: string;
-  };
-}
-/**
- * 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 {}
-interface State<P extends Params = Params> {
-  name: string;
-  params: P;
-  path: string;
-  transition: TransitionMeta;
-  /**
-   * Plugin-extensible per-route data, attached by plugins via
-   * `PluginApi.claimContextNamespace()` + `claim.write(state, value)`.
-   *
-   * @description
-   * Required field — always present as at least `{}` on every State created by
-   * the router (via `makeState`, `navigateToNotFound`, or `cloneRouter`).
-   *
-   * Typed extensions come from plugins augmenting {@link StateContext} through
-   * module augmentation. The intersection with `Record<string, unknown>` allows
-   * untyped namespaces (inline plugins, tests, or plugins that skip augmentation)
-   * to write without compile errors.
-   *
-   * The `context` object itself is **not frozen** — this is intentional, so
-   * plugins can attach data without cloning state. Core structural fields
-   * (`name`, `params`, `path`, `transition`) remain immutable via shallow
-   * `Object.freeze(state)`.
-   *
-   * @see {@link StateContext}
-   */
-  context: StateContext & Record<string, unknown>;
-}
-interface StateMetaInput<P extends Params = Params> {
-  params: P;
-}
-/**
- * RouterError interface describing the public API of the RouterError class.
- * The actual class implementation is in the real-router package.
- * This interface enables structural typing compatibility between
- * core-types and real-router packages.
- */
-interface RouterError extends Error {
-  [key: string]: unknown;
-  readonly code: string;
-  readonly segment: string | undefined;
-  readonly path: string | undefined;
-  setCode: (code: string) => void;
-  setErrorInstance: (err: Error) => void;
-  setAdditionalFields: (fields: Record<string, unknown>) => void;
-  hasField: (key: string) => boolean;
-  getField: (key: string) => unknown;
-  toJSON: () => Record<string, unknown>;
-}
-/**
- * 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;
-}
-interface Params {
-  [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
-}
-//#endregion
-//#region src/types/limits.d.ts
-/**
- * Configuration for router resource limits.
- * Controls maximum allowed values for various router operations to prevent resource exhaustion.
- */
-interface LimitsConfig {
-  /**
-   * Maximum number of route dependencies allowed.
-   * Prevents circular dependency chains and excessive dependency graphs.
-   *
-   * @default 100
-   */
-  maxDependencies: number;
-  /**
-   * Maximum number of plugins that can be registered.
-   * Limits plugin stack depth to prevent performance degradation.
-   *
-   * @default 50
-   */
-  maxPlugins: number;
-  /**
-   * Maximum number of event listeners per event type.
-   * Prevents memory leaks from excessive listener registration.
-   *
-   * @default 10000
-   */
-  maxListeners: number;
-  /**
-   * Listener count at which a memory leak warning is logged per event type.
-   * Set to 0 to disable the warning.
-   *
-   * @default 1000
-   */
-  warnListeners: number;
-  /**
-   * Maximum number of lifecycle handlers (canActivate/canDeactivate) per route.
-   * Controls guard function stack to prevent excessive validation overhead.
-   *
-   * @default 200
-   */
-  maxLifecycleHandlers: number;
-}
-//#endregion
-//#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
-//#region src/types/constants.d.ts
-/**
- * Plugin lifecycle method names
- */
-type PluginMethod = "onStart" | "onStop" | "onTransitionStart" | "onTransitionLeaveApprove" | "onTransitionCancel" | "onTransitionSuccess" | "onTransitionError";
-/**
- * Router event names
- */
-type EventName = "$start" | "$stop" | "$$start" | "$$leaveApprove" | "$$cancel" | "$$success" | "$$error";
-/**
- * Event type keys
- */
-type EventsKeys = "ROUTER_START" | "ROUTER_STOP" | "TRANSITION_START" | "TRANSITION_LEAVE_APPROVE" | "TRANSITION_CANCEL" | "TRANSITION_SUCCESS" | "TRANSITION_ERROR";
-/**
- * Error code values
- */
-type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED" | "PLUGIN_CONFLICT" | "CONTEXT_NAMESPACE_ALREADY_CLAIMED";
-/**
- * Error code keys
- */
-type ErrorCodeKeys = "ROUTER_NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ROUTER_ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "TRANSITION_CANCELLED" | "ROUTER_DISPOSED" | "PLUGIN_CONFLICT" | "CONTEXT_NAMESPACE_ALREADY_CLAIMED" | "REENTRANT_NAVIGATION" | "REENTRANT_TREE_MUTATION";
-/**
- * Mapping of event keys to plugin methods
- */
-interface EventToPluginMap {
-  readonly ROUTER_START: "onStart";
-  readonly ROUTER_STOP: "onStop";
-  readonly TRANSITION_START: "onTransitionStart";
-  readonly TRANSITION_LEAVE_APPROVE: "onTransitionLeaveApprove";
-  readonly TRANSITION_CANCEL: "onTransitionCancel";
-  readonly TRANSITION_SUCCESS: "onTransitionSuccess";
-  readonly TRANSITION_ERROR: "onTransitionError";
-}
-/**
- * Mapping of event keys to event names
- */
-interface EventToNameMap {
-  ROUTER_START: "$start";
-  ROUTER_STOP: "$stop";
-  TRANSITION_START: "$$start";
-  TRANSITION_LEAVE_APPROVE: "$$leaveApprove";
-  TRANSITION_CANCEL: "$$cancel";
-  TRANSITION_SUCCESS: "$$success";
-  TRANSITION_ERROR: "$$error";
-}
-/**
- * Mapping of event names to plugin method names.
- * Type-level computation from EventToNameMap + EventToPluginMap.
- */
-type EventMethodMap = { [K in EventsKeys as EventToNameMap[K]]: EventToPluginMap[K] };
-/**
- * Mapping of error code keys to their values
- */
-interface ErrorCodeToValueMap {
-  ROUTER_NOT_STARTED: "NOT_STARTED";
-  NO_START_PATH_OR_STATE: "NO_START_PATH_OR_STATE";
-  ROUTER_ALREADY_STARTED: "ALREADY_STARTED";
-  ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND";
-  SAME_STATES: "SAME_STATES";
-  CANNOT_DEACTIVATE: "CANNOT_DEACTIVATE";
-  CANNOT_ACTIVATE: "CANNOT_ACTIVATE";
-  TRANSITION_ERR: "TRANSITION_ERR";
-  TRANSITION_CANCELLED: "CANCELLED";
-  ROUTER_DISPOSED: "DISPOSED";
-  PLUGIN_CONFLICT: "PLUGIN_CONFLICT";
-  CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED";
-  REENTRANT_NAVIGATION: "REENTRANT_NAVIGATION";
-  REENTRANT_TREE_MUTATION: "REENTRANT_TREE_MUTATION";
-}
-//#endregion
-//#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
-//#region src/types/api.d.ts
-/**
- * Maps interceptable method names to their signatures.
- * Used by {@link PluginApi.addInterceptor} to provide type-safe interceptor registration.
- *
- * To add a new interceptable method:
- * 1. Add its signature here
- * 2. Wrap it with `createInterceptable()` / `createBinaryInterceptable()` in
- *    the `registerInternals` block of the Router constructor
- *    (`packages/core/src/Router.ts`)
- */
-interface InterceptableMethodMap {
-  start: (path?: string) => Promise<State>;
-  buildPath: (route: string, params?: Params) => string;
-  forwardState: (routeName: string, routeParams: Params) => SimpleState;
-}
-/**
- * Type-safe interceptor callback.
- * Receives `next` (the next function in the chain) followed by the method's original parameters.
- */
-type InterceptorFn<M extends keyof InterceptableMethodMap> = (next: InterceptableMethodMap[M], ...args: Parameters<InterceptableMethodMap[M]>) => ReturnType<InterceptableMethodMap[M]>;
-/**
- * Writer object returned by {@link PluginApi.claimContextNamespace}. Holds
- * exclusive ownership of a single `state.context.<namespace>` key for the
- * lifetime of the owning plugin.
- *
- * @description
- * A plugin obtains a claim by calling `api.claimContextNamespace("ns")` at
- * registration, then publishes per-navigation data via {@link write} from a
- * lifecycle hook (typically `onTransitionSuccess`) or from an interceptor.
- * The plugin must call {@link release} in its `teardown()` so another plugin
- * can reclaim the same namespace.
- *
- * The core runtime enforces one invariant: a namespace can be held by at most
- * one claim at a time. Double-claiming throws `CONTEXT_NAMESPACE_ALREADY_CLAIMED`.
- *
- * @example
- * ```typescript
- * const navigationPlugin: PluginFactory = (router) => {
- *   const api = getPluginApi(router);
- *   const claim = api.claimContextNamespace("navigation");
- *
- *   return {
- *     onTransitionSuccess(toState, fromState) {
- *       claim.write(toState, { direction: detectDirection(fromState, toState) });
- *     },
- *     teardown() {
- *       claim.release();
- *     },
- *   };
- * };
- * ```
- *
- * @see {@link PluginApi.claimContextNamespace}
- * @see {@link State.context}
- */
-interface ContextNamespaceClaim<T = unknown> {
-  write: (state: State, value: T) => void;
-  release: () => void;
-}
-/**
- * Plugin API — for plugins and infrastructure packages.
- * Hides plugin-internal methods from public autocomplete.
- */
-interface PluginApi {
-  makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput) => State<P>;
-  buildState: (routeName: string, routeParams: Params) => RouteTreeState | undefined;
-  forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
-  matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
-  /**
-   * Navigate to a fully-built `State`, skipping the redundant
-   * `forwardState`/`buildPath` round-trip in `buildNavigateState`.
-   *
-   * Plugin-only entry point for browser-initiated navigation: a plugin
-   * receives a URL event, resolves it via `api.matchPath(url)`, then commits
-   * the resulting `State` directly via `api.navigateToState(state, opts)`.
-   *
-   * Semantics vs `router.navigate(name, params, opts)`:
-   * - `forwardState` is NOT re-applied (matchPath already ran it).
-   * - `buildPath` is NOT re-run; `state.path` is used verbatim, preserving
-   *   `trailingSlash:"preserve"` source-URL output.
-   * - `forwardState`/`buildPath` interceptors do NOT run on this path; the
-   *   URL the user navigated to is the source of truth.
-   * - Pipeline: SAME_STATES check, FSM transition, guards, `subscribeLeave`,
-   *   `completeTransition`, plugin lifecycle hooks — all unchanged.
-   *
-   * Programmatic / userland navigation should keep using
-   * `router.navigate(name, params, opts)` so interceptors apply.
-   */
-  navigateToState: (state: State, options?: NavigationOptions) => Promise<State>;
-  setRootPath: (rootPath: string) => void;
-  getRootPath: () => string;
-  addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
-  buildNavigationState: (name: string, params?: Params) => State | undefined;
-  getOptions: () => Options;
-  getTree: () => unknown;
-  addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
-  extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;
-  /**
-   * Emits a `$$error` event without going through the navigation pipeline.
-   *
-   * Used by plugins that detect an error outside a running transition (e.g.,
-   * an unmatched URL on popstate in strict mode). The event reaches any
-   * `onTransitionError` plugin hook and any `$$error` listener so developers
-   * can observe errors raised by the plugin layer.
-   *
-   * The current router state is used as `fromState`; `toState` is `undefined`
-   * because no transition was attempted. Safe to call at any FSM state —
-   * delegates to `sendFailSafe` internally (direct emit when not READY).
-   */
-  emitTransitionError: (error: Error) => void;
-  claimContextNamespace: {
-    <K extends keyof StateContext & string>(namespace: K): ContextNamespaceClaim<StateContext[K]>;
-    (namespace: string): ContextNamespaceClaim;
-  };
-  getRouteConfig: (name: string) => Record<string, unknown> | undefined;
-}
-/**
- * Routes API — for dynamic route mutation.
- */
-interface RoutesApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  add: (routes: Route<Dependencies>[] | Route<Dependencies>, options?: {
-    parent?: string;
-  }) => void;
-  remove: (name: string) => void;
-  /**
-   * Patch an existing route's configuration in place (no tree rebuild).
-   *
-   * Applies the structural/guard fields and any plugin-defined custom fields
-   * (lifecycle hooks, `preload`, `searchSchema`, …) from the patch. Fields are
-   * shallow-merged by key; `null` removes a field, `undefined` is a no-op.
-   * `name`/`path`/`children` are immutable — use `remove` + `add` to
-   * restructure. See {@link RouteConfigUpdate} for the full semantics and the
-   * plugin augmentation pattern.
-   */
-  update: (name: string, updates: RouteConfigUpdate<Dependencies>) => void;
-  clear: () => void;
-  replace: (routes: Route<Dependencies>[] | Route<Dependencies>) => void;
-  has: (name: string) => boolean;
-  get: (name: string) => Route<Dependencies> | undefined;
-  /**
-   * Subscribe to structural route-tree mutations (`add` / `remove` / `update`
-   * with structural fields / `replace` / `clear`). Fire-and-forget: the handler
-   * cannot cancel the mutation, runs after the atomic commit, and sees the
-   * post-mutation tree via `get()` / `has()`.
-   *
-   * Duplicate-registration semantics are **lenient** (mirrors
-   * `router.subscribe`): each call registers an independent listener and
-   * returns its own unsubscribe.
-   *
-   * @returns Unsubscribe function for this specific registration.
-   */
-  subscribeChanges: (handler: (event: TreeChangedEvent<Dependencies>) => void) => Unsubscribe;
-}
-/**
- * Dependencies API — CRUD for dependency injection.
- */
-interface DependenciesApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  get: <K extends keyof Dependencies>(key: K) => Dependencies[K];
-  getAll: () => Partial<Dependencies>;
-  set: <K extends keyof Dependencies & string>(name: K, value: Dependencies[K]) => void;
-  setAll: (deps: Dependencies) => void;
-  remove: (name: keyof Dependencies) => void;
-  reset: () => void;
-  has: (name: keyof Dependencies) => boolean;
-}
-/**
- * Lifecycle API — guard registration (addActivateGuard, addDeactivateGuard, etc.)
- */
-interface LifecycleApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
-  addActivateGuard: (name: string, canActivateHandler: GuardFnFactory<Dependencies> | boolean) => void;
-  addDeactivateGuard: (name: string, canDeactivateHandler: GuardFnFactory<Dependencies> | boolean) => void;
-  removeActivateGuard: (name: string) => void;
-  removeDeactivateGuard: (name: string) => void;
-}
-//#endregion
-export { State as $, LeaveFn as A, PluginFactory as B, PluginMethod as C, ForwardToCallback as D, DefaultRouteCallback as E, LogLevelConfig as F, SubscribeFn as G, RouteConfigUpdate as H, LoggerConfig as I, LimitsConfig as J, SubscribeState as K, Navigator as L, Listener as M, LogCallback as N, GuardFn as O, LogLevel as P, SimpleState as Q, Options as R, EventsKeys as S, DefaultParamsCallback as T, Router as U, Route as V, RouterLogger as W, Params as X, NavigationOptions as Y, RouterError as Z, ErrorCodeValues as _, LifecycleApi as a, Unsubscribe as at, EventToNameMap as b, TreeChangedAdd as c, RouteParams as ct, TreeChangedRemove as d, StateContext as et, TreeChangedReplace as f, ErrorCodeToValueMap as g, ErrorCodeKeys as h, InterceptorFn as i, TransitionReason as it, LeaveState as j, GuardFnFactory as k, TreeChangedClear as l, RouteTreeState as lt, TreeStructuralPatch as m, DependenciesApi as n, TransitionMeta as nt, PluginApi as o, QueryParamsMode as ot, TreeChangedUpdate as p, Subscription as q, InterceptableMethodMap as r, TransitionPhase as rt, RoutesApi as s, QueryParamsOptions as st, ContextNamespaceClaim as t, StateMetaInput as tt, TreeChangedEvent as u, EventMethodMap as v, DefaultDependencies as w, EventToPluginMap as x, EventName as y, Plugin as z };
-//# sourceMappingURL=index-CAnGQpnz.d.mts.map