@real-router/types 0.11.0 → 0.13.0

package/dist/cjs/index.d.ts

@@ -3,7 +3,7 @@
  *
  * This module exports ONLY the essential types used by real-router:
  * - QueryParamsMode, QueryParamsOptions
- * - RouteTreeState
+ * - RouteParams, RouteTreeState
  *
  * These types are copied from route-node to avoid circular dependencies.
  *
@@ -44,18 +44,30 @@ interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
+type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
 interface State<P extends Params = Params, MP extends Params = Params> {
     name: string;
     params: P;
     path: string;
     meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
 }
 interface StateMeta<P extends Params = Params> {
     id: number;
     params: P;
     options: NavigationOptions;
-    redirected: boolean;
-    source?: string | undefined;
 }
 /**
  * Input type for makeState meta parameter.
@@ -216,7 +228,7 @@ interface NavigationOptions {
      * @description
      * Automatically set by the router when a navigation is triggered by a redirect from
      * middleware or lifecycle hooks. This flag is used internally to track redirect chains
-     * and is stored in state.meta.redirected.
+     * and is stored in state.meta.options.redirected.
      *
      * @default false (auto-set by router during redirects)
      *
@@ -232,14 +244,14 @@ interface NavigationOptions {
      * @example
      * // Accessing redirect flag in lifecycle
      * router.addActivateGuard('dashboard', (toState, fromState) => {
-     *   if (toState.meta?.redirected) {
+     *   if (toState.meta?.options?.redirected) {
      *     console.log('This navigation is from a redirect');
      *   }
      *   return true;
      * });
      *
      * @see {@link Router.navigate} for redirect handling implementation
-     * @see {@link State.meta.redirected} for redirect flag in state
+     * @see {@link NavigationOptions.redirected} for the input mechanism
      */
     redirected?: boolean | undefined;
 }
@@ -280,6 +292,13 @@ interface LimitsConfig {
      * @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 depth of nested event propagation.
      * Prevents infinite recursion in event handling chains.
@@ -511,6 +530,15 @@ interface Router {
      * @returns true if navigation is allowed, false otherwise
      */
     canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * Dispose the router and release all resources.
+     *
+     * Stops the router if active, calls plugin teardown, clears all event
+     * listeners, middleware, routes, and dependencies. After disposal, all
+     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
+     * call multiple times.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -528,11 +556,11 @@ type EventsKeys = "ROUTER_START" | "ROUTER_STOP" | "TRANSITION_START" | "TRANSIT
 /**
  * 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";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
 /**
  * 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";
+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";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -568,6 +596,7 @@ interface ErrorCodeToValueMap {
     CANNOT_ACTIVATE: "CANNOT_ACTIVATE";
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
+    ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/cjs/metafile-cjs.json

@@ -1 +1 @@
-{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1226,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1298,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/dist/esm/index.d.mts

@@ -3,7 +3,7 @@
  *
  * This module exports ONLY the essential types used by real-router:
  * - QueryParamsMode, QueryParamsOptions
- * - RouteTreeState
+ * - RouteParams, RouteTreeState
  *
  * These types are copied from route-node to avoid circular dependencies.
  *
@@ -44,18 +44,30 @@ interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
+type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
 interface State<P extends Params = Params, MP extends Params = Params> {
     name: string;
     params: P;
     path: string;
     meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
 }
 interface StateMeta<P extends Params = Params> {
     id: number;
     params: P;
     options: NavigationOptions;
-    redirected: boolean;
-    source?: string | undefined;
 }
 /**
  * Input type for makeState meta parameter.
@@ -216,7 +228,7 @@ interface NavigationOptions {
      * @description
      * Automatically set by the router when a navigation is triggered by a redirect from
      * middleware or lifecycle hooks. This flag is used internally to track redirect chains
-     * and is stored in state.meta.redirected.
+     * and is stored in state.meta.options.redirected.
      *
      * @default false (auto-set by router during redirects)
      *
@@ -232,14 +244,14 @@ interface NavigationOptions {
      * @example
      * // Accessing redirect flag in lifecycle
      * router.addActivateGuard('dashboard', (toState, fromState) => {
-     *   if (toState.meta?.redirected) {
+     *   if (toState.meta?.options?.redirected) {
      *     console.log('This navigation is from a redirect');
      *   }
      *   return true;
      * });
      *
      * @see {@link Router.navigate} for redirect handling implementation
-     * @see {@link State.meta.redirected} for redirect flag in state
+     * @see {@link NavigationOptions.redirected} for the input mechanism
      */
     redirected?: boolean | undefined;
 }
@@ -280,6 +292,13 @@ interface LimitsConfig {
      * @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 depth of nested event propagation.
      * Prevents infinite recursion in event handling chains.
@@ -511,6 +530,15 @@ interface Router {
      * @returns true if navigation is allowed, false otherwise
      */
     canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * Dispose the router and release all resources.
+     *
+     * Stops the router if active, calls plugin teardown, clears all event
+     * listeners, middleware, routes, and dependencies. After disposal, all
+     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
+     * call multiple times.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -528,11 +556,11 @@ type EventsKeys = "ROUTER_START" | "ROUTER_STOP" | "TRANSITION_START" | "TRANSIT
 /**
  * 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";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
 /**
  * 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";
+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";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -568,6 +596,7 @@ interface ErrorCodeToValueMap {
     CANNOT_ACTIVATE: "CANNOT_ACTIVATE";
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
+    ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/esm/metafile-esm.json

@@ -1 +1 @@
-{"inputs":{"src/index.ts":{"bytes":1226,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"src/index.ts":{"bytes":1298,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@real-router/types",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -13,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",

package/src/base.ts

@@ -0,0 +1,259 @@
+// packages/core-types/modules/base.ts
+
+// Note: RouteTreeState is exported from route-node-types.ts
+// It uses RouteParams as default type parameter.
+// Real Router code should use RouteTreeState<Params> when needed.
+
+export type Unsubscribe = () => void;
+
+export interface SimpleState<P extends Params = Params> {
+  name: string;
+  params: P;
+}
+
+export type TransitionPhase = "deactivating" | "activating" | "middleware";
+
+export type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+
+export interface TransitionMeta {
+  phase: TransitionPhase;
+  from?: string;
+  reason: TransitionReason;
+  blocker?: string;
+  segments: {
+    deactivated: string[];
+    activated: string[];
+    intersection: string;
+  };
+}
+
+export interface State<P extends Params = Params, MP extends Params = Params> {
+  name: string;
+  params: P;
+  path: string;
+  meta?: StateMeta<MP> | undefined;
+  transition?: TransitionMeta | undefined;
+}
+
+export interface StateMeta<P extends Params = Params> {
+  id: number;
+  params: P;
+  options: NavigationOptions;
+}
+
+/**
+ * Input type for makeState meta parameter.
+ * Omits `id` since it's auto-generated by makeState.
+ */
+export type StateMetaInput<P extends Params = Params> = Omit<
+  StateMeta<P>,
+  "id"
+>;
+
+/**
+ * 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.
+ */
+export interface RouterError extends Error {
+  [key: string]: unknown;
+  readonly code: string;
+  readonly segment: string | undefined;
+  readonly path: string | undefined;
+  readonly redirect: State | 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. The options object is stored in state.meta.options and is
+ * available to middleware, guards, and event listeners.
+ *
+ * @see {@link Router.navigate} for navigation method that accepts these options
+ * @see {@link State.meta} for where options are stored after navigation
+ */
+export interface NavigationOptions {
+  [key: string]:
+    | string
+    | number
+    | boolean
+    | Record<string, unknown>
+    | undefined;
+
+  /**
+   * 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;
+
+  /**
+   * 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 or middleware execute
+   * - No events are fired
+   *
+   * With `reload`:
+   * - Full transition executes (deactivate → activate → middleware)
+   * - 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 and middleware 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) → middleware → success
+   *
+   * // With forceDeactivate: true
+   * [skip deactivate] → activate(toSegments) → middleware → 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 from
+   * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+   * and is stored in state.meta.options.redirected.
+   *
+   * @default false (auto-set by router during redirects)
+   *
+   * @example
+   * // Middleware triggers automatic redirect
+   * router.useMiddleware((toState, fromState, opts) => {
+   *   if (!isAuthenticated && toState.name !== 'login') {
+   *     // Router will automatically set redirected: true
+   *     return { name: 'login', params: { next: toState.path } };
+   *   }
+   * });
+   *
+   * @example
+   * // Accessing redirect flag in lifecycle
+   * router.addActivateGuard('dashboard', (toState, fromState) => {
+   *   if (toState.meta?.options?.redirected) {
+   *     console.log('This navigation is from a redirect');
+   *   }
+   *   return true;
+   * });
+   *
+   * @see {@link Router.navigate} for redirect handling implementation
+   * @see {@link NavigationOptions.redirected} for the input mechanism
+   */
+  redirected?: boolean | undefined;
+}
+
+export interface Params {
+  [key: string]:
+    | string
+    | string[]
+    | number
+    | number[]
+    | boolean
+    | boolean[]
+    | Params
+    | Params[]
+    | Record<string, string | number | boolean>
+    | null
+    | undefined;
+}

package/src/constants.ts

@@ -0,0 +1,104 @@
+// packages/core-types/modules/constants.ts
+
+/**
+ * Plugin lifecycle method names
+ */
+export type PluginMethod =
+  | "onStart"
+  | "onStop"
+  | "onTransitionStart"
+  | "onTransitionCancel"
+  | "onTransitionSuccess"
+  | "onTransitionError";
+
+/**
+ * Router event names
+ */
+export type EventName =
+  | "$start"
+  | "$stop"
+  | "$$start"
+  | "$$cancel"
+  | "$$success"
+  | "$$error";
+
+/**
+ * Event type keys
+ */
+export type EventsKeys =
+  | "ROUTER_START"
+  | "ROUTER_STOP"
+  | "TRANSITION_START"
+  | "TRANSITION_CANCEL"
+  | "TRANSITION_SUCCESS"
+  | "TRANSITION_ERROR";
+
+/**
+ * Error code values
+ */
+export type ErrorCodeValues =
+  | "NOT_STARTED"
+  | "NO_START_PATH_OR_STATE"
+  | "ALREADY_STARTED"
+  | "ROUTE_NOT_FOUND"
+  | "SAME_STATES"
+  | "CANNOT_DEACTIVATE"
+  | "CANNOT_ACTIVATE"
+  | "TRANSITION_ERR"
+  | "CANCELLED"
+  | "DISPOSED";
+
+/**
+ * Error code keys
+ */
+export 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";
+
+/**
+ * Mapping of event keys to plugin methods
+ */
+export interface EventToPluginMap {
+  readonly ROUTER_START: "onStart";
+  readonly ROUTER_STOP: "onStop";
+  readonly TRANSITION_START: "onTransitionStart";
+  readonly TRANSITION_CANCEL: "onTransitionCancel";
+  readonly TRANSITION_SUCCESS: "onTransitionSuccess";
+  readonly TRANSITION_ERROR: "onTransitionError";
+}
+
+/**
+ * Mapping of event keys to event names
+ */
+export interface EventToNameMap {
+  ROUTER_START: "$start";
+  ROUTER_STOP: "$stop";
+  TRANSITION_START: "$$start";
+  TRANSITION_CANCEL: "$$cancel";
+  TRANSITION_SUCCESS: "$$success";
+  TRANSITION_ERROR: "$$error";
+}
+
+/**
+ * Mapping of error code keys to their values
+ */
+export 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";
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// packages/core-types/modules/index.ts
+
+// Route node types
+export type {
+  QueryParamsMode,
+  QueryParamsOptions,
+  RouteParams,
+  RouteTreeState,
+} from "./route-node-types";
+
+// Base types
+export type {
+  Params,
+  State,
+  StateMeta,
+  StateMetaInput,
+  SimpleState,
+  NavigationOptions,
+  Unsubscribe,
+  RouterError,
+  TransitionPhase,
+  TransitionReason,
+  TransitionMeta,
+} from "./base";
+
+// Router types (base types without Router dependency)
+// Note: Route, RouteConfigUpdate, ActivationFnFactory, MiddlewareFactory,
+// PluginFactory, BuildStateResultWithSegments are in @real-router/core
+export type {
+  Options,
+  DefaultRouteCallback,
+  ForwardToCallback,
+  DefaultParamsCallback,
+  ActivationFn,
+  DefaultDependencies,
+  Config,
+  Plugin,
+  Middleware,
+  SubscribeState,
+  SubscribeFn,
+  Listener,
+  Subscription,
+  Navigator,
+  Router,
+} from "./router";
+
+// Limits configuration
+export type { LimitsConfig } from "./limits";
+
+export type {
+  PluginMethod,
+  EventName,
+  EventsKeys,
+  ErrorCodeValues,
+  ErrorCodeKeys,
+  EventToPluginMap,
+  EventToNameMap,
+  ErrorCodeToValueMap,
+} from "./constants";
+
+// Note: RouterError type is a forward declaration matching the class in real-router package
+// Use import { RouterError } from "real-router" for the actual class implementation

package/src/limits.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration for router resource limits.
+ * Controls maximum allowed values for various router operations to prevent resource exhaustion.
+ */
+export 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 middleware functions in the navigation pipeline.
+   * Controls middleware chain length to prevent stack overflow and performance issues.
+   *
+   * @default 50
+   */
+  maxMiddleware: 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 depth of nested event propagation.
+   * Prevents infinite recursion in event handling chains.
+   *
+   * @default 5
+   */
+  maxEventDepth: number;
+
+  /**
+   * Maximum number of lifecycle handlers (canActivate/canDeactivate) per route.
+   * Controls guard function stack to prevent excessive validation overhead.
+   *
+   * @default 200
+   */
+  maxLifecycleHandlers: number;
+}

package/src/route-node-types.ts

@@ -0,0 +1,73 @@
+// packages/core-types/modules/route-node-types.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
+ */
+
+// =============================================================================
+// Search Params Types
+// =============================================================================
+
+type ArrayFormat = "none" | "brackets" | "index" | "comma";
+type BooleanFormat = "none" | "string" | "empty-true";
+type NullFormat = "default" | "hidden";
+
+/**
+ * Options for query parameter parsing and building.
+ */
+export interface QueryParamsOptions {
+  arrayFormat?: ArrayFormat;
+  booleanFormat?: BooleanFormat;
+  nullFormat?: NullFormat;
+}
+
+// =============================================================================
+// Mode Types
+// =============================================================================
+
+/**
+ * Controls how query parameters are handled during matching.
+ */
+export type QueryParamsMode = "default" | "strict" | "loose";
+
+// =============================================================================
+// Route State Types
+// =============================================================================
+
+type ParamSource = "url" | "query";
+type ParamTypeMap = Record<string, ParamSource>;
+type RouteTreeStateMeta = Record<string, ParamTypeMap>;
+
+export 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.
+ */
+export interface RouteTreeState<
+  P extends Record<string, unknown> = RouteParams,
+> {
+  name: string;
+  params: P;
+  meta: RouteTreeStateMeta;
+}

package/src/router.ts

@@ -0,0 +1,302 @@
+// packages/core-types/modules/router.ts
+
+/**
+ * Base router types without Router class dependency.
+ *
+ * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
+ * MiddlewareFactory, PluginFactory) are defined in @real-router/core
+ * to avoid circular dependencies.
+ */
+
+import type {
+  State,
+  Params,
+  NavigationOptions,
+  RouterError,
+  Unsubscribe,
+} from "./base";
+import type { LimitsConfig } from "./limits";
+import type { QueryParamsMode, QueryParamsOptions } from "./route-node-types";
+
+// Logger types (duplicated from @real-router/logger to avoid dependency)
+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;
+}
+
+/**
+ * Callback function for dynamically resolving the default route.
+ * Receives a dependency getter function to access router dependencies.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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 as provided
+   *
+   * @default "preserve"
+   */
+  trailingSlash: "strict" | "never" | "always" | "preserve";
+
+  /**
+   * 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 path on successful match.
+   *
+   * @default false
+   */
+  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>;
+
+  /**
+   * Disables argument validation in public router methods.
+   * Use in production for performance. Keep false in development for early error detection.
+   *
+   * @default false
+   */
+  noValidate?: boolean;
+}
+
+export type ActivationFn = (
+  toState: State,
+  fromState: State | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+) => boolean | Promise<boolean | State | void> | State | void;
+
+export type DefaultDependencies = object;
+
+export interface Config {
+  decoders: Record<string, (params: Params) => Params>;
+  encoders: Record<string, (params: Params) => Params>;
+  defaultParams: Record<string, Params>;
+  forwardMap: Record<string, string>;
+}
+
+export interface Plugin {
+  onStart?: () => void;
+  onStop?: () => void;
+  onTransitionStart?: (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;
+}
+
+// eslint-disable-next-line sonarjs/redundant-type-aliases
+export type Middleware = ActivationFn;
+
+export interface SubscribeState {
+  route: State;
+  previousRoute?: State | undefined;
+}
+
+export type SubscribeFn = (state: SubscribeState) => void;
+
+export interface Listener {
+  [key: string]: unknown;
+  next: (val: unknown) => void;
+  error?: (err: unknown) => void;
+  complete?: () => void;
+}
+
+export 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.
+ */
+export 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;
+}
+
+/**
+ * Router interface - public API for route navigation and lifecycle management.
+ *
+ * Defines the contract for router implementations. The actual Router class in
+ * @real-router/core implements this interface with full functionality.
+ *
+ * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * dependencies. The concrete Router class in @real-router/core narrows this to
+ * `ActivationFnFactory | boolean` for more precise type checking.
+ */
+export interface Router {
+  /**
+   * Register an activation guard for a route.
+   *
+   * @param name - Route name
+   * @param guard - Guard function or boolean
+   * @returns this for method chaining
+   */
+  addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+
+  /**
+   * Register a deactivation guard for a route.
+   *
+   * @param name - Route name
+   * @param guard - Guard function or boolean
+   * @returns this for method chaining
+   */
+  addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+
+  /**
+   * Remove an activation guard from a route.
+   *
+   * @param name - Route name
+   */
+  removeActivateGuard: (name: string) => void;
+
+  /**
+   * Remove a deactivation guard from a route.
+   *
+   * @param name - Route name
+   */
+  removeDeactivateGuard: (name: string) => void;
+
+  /**
+   * Check if navigation to a route is allowed without performing actual navigation.
+   *
+   * Synchronously checks all activation and deactivation guards in the transition path.
+   * Async guards return false with a console warning.
+   *
+   * @param name - Route name to check
+   * @param params - Route parameters (optional)
+   * @returns true if navigation is allowed, false otherwise
+   */
+  canNavigateTo: (name: string, params?: Params) => boolean;
+
+  /**
+   * Dispose the router and release all resources.
+   *
+   * Stops the router if active, calls plugin teardown, clears all event
+   * listeners, middleware, routes, and dependencies. After disposal, all
+   * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
+   * call multiple times.
+   */
+  dispose: () => void;
+}