@real-router/types 0.15.0 → 0.16.0

package/dist/cjs/index.d.ts

@@ -300,11 +300,11 @@ interface LimitsConfig {
 }
 
 /**
- * Base router types without Router class dependency.
+ * Router types and interfaces.
  *
- * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * PluginFactory) are defined in @real-router/core
- * to avoid circular dependencies.
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) use self-referencing Router<D>
+ * within this single file to resolve circular dependencies.
  */
 
 type LogLevel = "log" | "warn" | "error";
@@ -416,7 +416,6 @@ interface Options {
      */
     noValidate?: boolean;
 }
-type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
 type GuardFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean>;
 type DefaultDependencies = object;
 interface Config {
@@ -465,64 +464,94 @@ interface Navigator {
     subscribe: (listener: SubscribeFn) => Unsubscribe;
 }
 /**
- * Router interface - public API for route navigation and lifecycle management.
+ * Router interface — full 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 `GuardFn | boolean` for guard types to avoid circular
- * dependencies. The concrete Router class in @real-router/core narrows this to
- * `GuardFnFactory | boolean` for more precise type checking.
+ * 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 {
-    /**
-     * 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: GuardFn | 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: GuardFn | 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;
+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, MP extends Params = Params>() => State<P, MP> | 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>[]) => Unsubscribe;
+    subscribe: (listener: SubscribeFn) => Unsubscribe;
+    navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
+    navigateToDefault: (options?: NavigationOptions) => Promise<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>;
     /**
-     * Check if navigation to a route is allowed without performing actual navigation.
+     * Redirects navigation to another route.
      *
-     * Synchronously checks all activation and deactivation guards in the transition path.
-     * Async guards return false with a console warning.
+     * 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.
      *
-     * @param name - Route name to check
-     * @param params - Route parameters (optional)
-     * @returns true if navigation is allowed, false otherwise
+     * This matches Vue Router and Angular Router behavior.
      */
-    canNavigateTo: (name: string, params?: Params) => boolean;
+    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;
     /**
-     * Dispose the router and release all resources.
+     * Default parameters for this route.
      *
-     * Stops the router if active, calls plugin teardown, clears all event
-     * listeners, routes, and dependencies. After disposal, all
-     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
-     * call multiple times.
+     * These values are merged into state.params when creating route states.
+     * Missing URL params are filled from defaultParams.
      */
-    dispose: () => void;
+    defaultParams?: Params;
+}
+/**
+ * Configuration update options for updateRoute().
+ * All properties are optional. Set to null to remove the configuration.
+ */
+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;
 }
 
 /**
@@ -567,6 +596,13 @@ interface EventToNameMap {
     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
  */
@@ -583,4 +619,64 @@ interface ErrorCodeToValueMap {
     ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+/**
+ * API interfaces for modular router access.
+ * These interfaces are implemented by standalone API functions in @real-router/core.
+ */
+
+/**
+ * Plugin API — for plugins and infrastructure packages.
+ * Hides plugin-internal methods from public autocomplete.
+ */
+interface PluginApi {
+    makeState: <P extends Params = Params, MP extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput<MP>, forceId?: number) => State<P, MP>;
+    buildState: (routeName: string, routeParams: Params) => RouteTreeState | undefined;
+    forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+    matchPath: <P extends Params = Params, MP extends Params = Params>(path: string) => State<P, MP> | undefined;
+    setRootPath: (rootPath: string) => void;
+    getRootPath: () => string;
+    navigateToState: (toState: State, fromState: State | undefined, opts: NavigationOptions) => Promise<State>;
+    addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
+    buildNavigationState: (name: string, params?: Params) => State | undefined;
+    getOptions: () => Options;
+    getTree: () => unknown;
+    getForwardState: () => <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+    setForwardState: (fn: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>) => void;
+}
+/**
+ * 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;
+    update: (name: string, updates: RouteConfigUpdate<Dependencies>) => void;
+    clear: () => void;
+    has: (name: string) => boolean;
+    get: (name: string) => Route<Dependencies> | undefined;
+    getConfig: (name: string) => Record<string, unknown> | undefined;
+}
+/**
+ * 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;
+}
+
+export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, 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":1276,"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":1349,"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

@@ -300,11 +300,11 @@ interface LimitsConfig {
 }
 
 /**
- * Base router types without Router class dependency.
+ * Router types and interfaces.
  *
- * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * PluginFactory) are defined in @real-router/core
- * to avoid circular dependencies.
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) use self-referencing Router<D>
+ * within this single file to resolve circular dependencies.
  */
 
 type LogLevel = "log" | "warn" | "error";
@@ -416,7 +416,6 @@ interface Options {
      */
     noValidate?: boolean;
 }
-type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
 type GuardFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean>;
 type DefaultDependencies = object;
 interface Config {
@@ -465,64 +464,94 @@ interface Navigator {
     subscribe: (listener: SubscribeFn) => Unsubscribe;
 }
 /**
- * Router interface - public API for route navigation and lifecycle management.
+ * Router interface — full 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 `GuardFn | boolean` for guard types to avoid circular
- * dependencies. The concrete Router class in @real-router/core narrows this to
- * `GuardFnFactory | boolean` for more precise type checking.
+ * 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 {
-    /**
-     * 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: GuardFn | 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: GuardFn | 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;
+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, MP extends Params = Params>() => State<P, MP> | 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>[]) => Unsubscribe;
+    subscribe: (listener: SubscribeFn) => Unsubscribe;
+    navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
+    navigateToDefault: (options?: NavigationOptions) => Promise<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>;
     /**
-     * Check if navigation to a route is allowed without performing actual navigation.
+     * Redirects navigation to another route.
      *
-     * Synchronously checks all activation and deactivation guards in the transition path.
-     * Async guards return false with a console warning.
+     * 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.
      *
-     * @param name - Route name to check
-     * @param params - Route parameters (optional)
-     * @returns true if navigation is allowed, false otherwise
+     * This matches Vue Router and Angular Router behavior.
      */
-    canNavigateTo: (name: string, params?: Params) => boolean;
+    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;
     /**
-     * Dispose the router and release all resources.
+     * Default parameters for this route.
      *
-     * Stops the router if active, calls plugin teardown, clears all event
-     * listeners, routes, and dependencies. After disposal, all
-     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
-     * call multiple times.
+     * These values are merged into state.params when creating route states.
+     * Missing URL params are filled from defaultParams.
      */
-    dispose: () => void;
+    defaultParams?: Params;
+}
+/**
+ * Configuration update options for updateRoute().
+ * All properties are optional. Set to null to remove the configuration.
+ */
+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;
 }
 
 /**
@@ -567,6 +596,13 @@ interface EventToNameMap {
     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
  */
@@ -583,4 +619,64 @@ interface ErrorCodeToValueMap {
     ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+/**
+ * API interfaces for modular router access.
+ * These interfaces are implemented by standalone API functions in @real-router/core.
+ */
+
+/**
+ * Plugin API — for plugins and infrastructure packages.
+ * Hides plugin-internal methods from public autocomplete.
+ */
+interface PluginApi {
+    makeState: <P extends Params = Params, MP extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput<MP>, forceId?: number) => State<P, MP>;
+    buildState: (routeName: string, routeParams: Params) => RouteTreeState | undefined;
+    forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+    matchPath: <P extends Params = Params, MP extends Params = Params>(path: string) => State<P, MP> | undefined;
+    setRootPath: (rootPath: string) => void;
+    getRootPath: () => string;
+    navigateToState: (toState: State, fromState: State | undefined, opts: NavigationOptions) => Promise<State>;
+    addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
+    buildNavigationState: (name: string, params?: Params) => State | undefined;
+    getOptions: () => Options;
+    getTree: () => unknown;
+    getForwardState: () => <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+    setForwardState: (fn: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>) => void;
+}
+/**
+ * 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;
+    update: (name: string, updates: RouteConfigUpdate<Dependencies>) => void;
+    clear: () => void;
+    has: (name: string) => boolean;
+    get: (name: string) => Route<Dependencies> | undefined;
+    getConfig: (name: string) => Record<string, unknown> | undefined;
+}
+/**
+ * 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;
+}
+
+export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/esm/metafile-esm.json

@@ -1 +1 @@
-{"inputs":{"src/index.ts":{"bytes":1276,"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":1349,"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,6 +1,6 @@
 {
   "name": "@real-router/types",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",

package/src/api.ts

@@ -0,0 +1,145 @@
+// packages/core-types/modules/api.ts
+
+/**
+ * API interfaces for modular router access.
+ * These interfaces are implemented by standalone API functions in @real-router/core.
+ */
+
+import type {
+  Params,
+  State,
+  SimpleState,
+  StateMetaInput,
+  NavigationOptions,
+  Unsubscribe,
+} from "./base";
+import type { EventMethodMap, EventName } from "./constants";
+import type { RouteTreeState } from "./route-node-types";
+import type {
+  DefaultDependencies,
+  GuardFnFactory,
+  Options,
+  Plugin,
+  Route,
+  RouteConfigUpdate,
+} from "./router";
+
+/**
+ * Plugin API — for plugins and infrastructure packages.
+ * Hides plugin-internal methods from public autocomplete.
+ */
+export interface PluginApi {
+  makeState: <P extends Params = Params, MP extends Params = Params>(
+    name: string,
+    params?: P,
+    path?: string,
+    meta?: StateMetaInput<MP>,
+    forceId?: number,
+  ) => State<P, MP>;
+
+  buildState: (
+    routeName: string,
+    routeParams: Params,
+  ) => RouteTreeState | undefined;
+
+  forwardState: <P extends Params = Params>(
+    routeName: string,
+    routeParams: P,
+  ) => SimpleState<P>;
+
+  matchPath: <P extends Params = Params, MP extends Params = Params>(
+    path: string,
+  ) => State<P, MP> | undefined;
+
+  setRootPath: (rootPath: string) => void;
+  getRootPath: () => string;
+
+  navigateToState: (
+    toState: State,
+    fromState: State | undefined,
+    opts: NavigationOptions,
+  ) => Promise<State>;
+
+  addEventListener: <E extends EventName>(
+    eventName: E,
+    cb: Plugin[EventMethodMap[E]],
+  ) => Unsubscribe;
+
+  buildNavigationState: (name: string, params?: Params) => State | undefined;
+
+  getOptions: () => Options;
+
+  getTree: () => unknown;
+
+  getForwardState: () => <P extends Params = Params>(
+    routeName: string,
+    routeParams: P,
+  ) => SimpleState<P>;
+
+  setForwardState: (
+    fn: <P extends Params = Params>(
+      routeName: string,
+      routeParams: P,
+    ) => SimpleState<P>,
+  ) => void;
+}
+
+/**
+ * Routes API — for dynamic route mutation.
+ */
+export interface RoutesApi<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  add: (
+    routes: Route<Dependencies>[] | Route<Dependencies>,
+    options?: { parent?: string },
+  ) => void;
+
+  remove: (name: string) => void;
+
+  update: (name: string, updates: RouteConfigUpdate<Dependencies>) => void;
+
+  clear: () => void;
+
+  has: (name: string) => boolean;
+
+  get: (name: string) => Route<Dependencies> | undefined;
+
+  getConfig: (name: string) => Record<string, unknown> | undefined;
+}
+
+/**
+ * Dependencies API — CRUD for dependency injection.
+ */
+export 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.)
+ */
+export 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;
+}

package/src/constants.ts

@@ -87,6 +87,14 @@ export interface EventToNameMap {
   TRANSITION_ERROR: "$$error";
 }
 
+/**
+ * Mapping of event names to plugin method names.
+ * Type-level computation from EventToNameMap + EventToPluginMap.
+ */
+export type EventMethodMap = {
+  [K in EventsKeys as EventToNameMap[K]]: EventToPluginMap[K];
+};
+
 /**
  * Mapping of error code keys to their values
  */

package/src/index.ts

@@ -23,25 +23,26 @@ export type {
   TransitionMeta,
 } from "./base";
 
-// Router types (base types without Router dependency)
-// Note: Route, RouteConfigUpdate, ActivationFnFactory,
-// PluginFactory, BuildStateResultWithSegments are in @real-router/core
+// Router types, factory types, and route config types
 export type {
+  Router,
+  Navigator,
+  Route,
+  Plugin,
+  Listener,
   Options,
   DefaultRouteCallback,
   ForwardToCallback,
   DefaultParamsCallback,
-  ActivationFn,
   GuardFn,
   DefaultDependencies,
   Config,
-  Plugin,
   SubscribeState,
   SubscribeFn,
-  Listener,
   Subscription,
-  Navigator,
-  Router,
+  PluginFactory,
+  GuardFnFactory,
+  RouteConfigUpdate,
 } from "./router";
 
 // Limits configuration
@@ -56,7 +57,16 @@ export type {
   EventToPluginMap,
   EventToNameMap,
   ErrorCodeToValueMap,
+  EventMethodMap,
 } from "./constants";
 
+// API interfaces (modular router access)
+export type {
+  PluginApi,
+  RoutesApi,
+  DependenciesApi,
+  LifecycleApi,
+} from "./api";
+
 // 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/router.ts

@@ -1,11 +1,11 @@
 // packages/core-types/modules/router.ts
 
 /**
- * Base router types without Router class dependency.
+ * Router types and interfaces.
  *
- * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * PluginFactory) are defined in @real-router/core
- * to avoid circular dependencies.
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) use self-referencing Router<D>
+ * within this single file to resolve circular dependencies.
  */
 
 import type {
@@ -155,12 +155,6 @@ export interface Options {
   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 GuardFn = (
   toState: State,
   fromState: State | undefined,
@@ -238,67 +232,152 @@ export interface Navigator {
 }
 
 /**
- * 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.
+ * Router interface — full public API for route navigation and lifecycle management.
  *
- * This interface uses `GuardFn | boolean` for guard types to avoid circular
- * dependencies. The concrete Router class in @real-router/core narrows this to
- * `GuardFnFactory | boolean` for more precise type checking.
+ * Generic parameter D constrains dependency injection types.
+ * Factory types (PluginFactory, GuardFnFactory) self-reference this interface
+ * within the same file to avoid circular dependencies.
  */
-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: GuardFn | boolean) => this;
+export interface Router<D extends DefaultDependencies = DefaultDependencies> {
+  // Plugins add properties at runtime (e.g. browser-plugin adds buildUrl, matchUrl).
+  // Index signature allows property access when module augmentation isn't in scope.
+  [key: string]: unknown;
 
-  /**
-   * 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: GuardFn | boolean) => this;
+  isActiveRoute: (
+    name: string,
+    params?: Params,
+    strictEquality?: boolean,
+    ignoreQueryParams?: boolean,
+  ) => boolean;
 
-  /**
-   * Remove an activation guard from a route.
-   *
-   * @param name - Route name
-   */
-  removeActivateGuard: (name: string) => void;
+  buildPath: (route: string, params?: Params) => string;
 
-  /**
-   * Remove a deactivation guard from a route.
-   *
-   * @param name - Route name
-   */
-  removeDeactivateGuard: (name: string) => void;
+  getState: <P extends Params = Params, MP extends Params = Params>() =>
+    | State<P, MP>
+    | 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>[]) => Unsubscribe;
+
+  subscribe: (listener: SubscribeFn) => Unsubscribe;
+
+  navigate: (
+    routeName: string,
+    routeParams?: Params,
+    options?: NavigationOptions,
+  ) => Promise<State>;
+
+  navigateToDefault: (options?: NavigationOptions) => Promise<State>;
+}
+
+// =============================================================================
+// Factory Types (self-reference Router<D>)
+// =============================================================================
+
+/**
+ * Factory function for creating plugins.
+ * Receives the router instance and a dependency getter.
+ */
+export 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.
+ */
+export type GuardFnFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
+) => GuardFn;
+
+// =============================================================================
+// Route Configuration Types (use GuardFnFactory<D> + ForwardToCallback<D>)
+// =============================================================================
 
+/**
+ * Route configuration.
+ */
+export 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>;
   /**
-   * Check if navigation to a route is allowed without performing actual navigation.
+   * Redirects navigation to another route.
    *
-   * Synchronously checks all activation and deactivation guards in the transition path.
-   * Async guards return false with a console warning.
+   * 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.
    *
-   * @param name - Route name to check
-   * @param params - Route parameters (optional)
-   * @returns true if navigation is allowed, false otherwise
+   * This matches Vue Router and Angular Router behavior.
    */
-  canNavigateTo: (name: string, params?: Params) => boolean;
-
+  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;
   /**
-   * Dispose the router and release all resources.
+   * Default parameters for this route.
    *
-   * Stops the router if active, calls plugin teardown, clears all event
-   * listeners, routes, and dependencies. After disposal, all
-   * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
-   * call multiple times.
+   * These values are merged into state.params when creating route states.
+   * Missing URL params are filled from defaultParams.
    */
-  dispose: () => void;
+  defaultParams?: Params;
+}
+
+/**
+ * Configuration update options for updateRoute().
+ * All properties are optional. Set to null to remove the configuration.
+ */
+export 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;
 }