@real-router/core 0.79.0 → 0.80.0

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

@@ -0,0 +1,72 @@
+//#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
+export { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod };
+//# sourceMappingURL=constants.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.mts","names":[],"sources":["../../../src/types/constants.ts"],"mappings":";;;;KAGY;;;;KAYA;;;;KAYA;;;;KAYA;;;;KAiBA;;;;UAmBK;WACN;WACA;WACA;WACA;WACA;WACA;WACA;;;;;UAMM;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;KAOU,oBACT,KAAK,cAAc,eAAe,KAAK,iBAAiB;;;;UAM1C;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA"}

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

@@ -0,0 +1,9 @@
+import { LimitsConfig } from "./limits.mjs";
+//#region src/types/internal.d.ts
+/**
+ * Immutable limits configuration type.
+ */
+type Limits = Readonly<LimitsConfig>;
+//#endregion
+export { Limits };
+//# sourceMappingURL=internal.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.mts","names":[],"sources":["../../../src/types/internal.ts"],"mappings":";;;;;KAwDY,SAAS,SAAS"}

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

@@ -0,0 +1,45 @@
+//#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
+export { LimitsConfig };
+//# sourceMappingURL=limits.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.mts","names":[],"sources":["../../../src/types/limits.ts"],"mappings":";;;;;UAIiB;;;;;;;EAOf;;;;;;;EAQA;;;;;;;EAQA;;;;;;;EAQA;;;;;;;EAQA"}

package/dist/esm/types/route-node-types.d.mts

@@ -0,0 +1,46 @@
+//#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
+export { QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState };
+//# sourceMappingURL=route-node-types.d.mts.map

package/dist/esm/types/route-node-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-node-types.d.mts","names":[],"sources":["../../../src/types/route-node-types.ts"],"mappings":";;;;;;;;;;;;KAgBK;KACA;KACA;KACA;;;;UAKY;EACf,cAAc;EACd,gBAAgB;EAChB,aAAa;EACb,eAAe;;;;;KAUL;KAMP;KACA,eAAe,eAAe;KAC9B,qBAAqB,eAAe;UAExB;GACd,4EAOG,cACA,gBACA;;;;;UAQW,eACf,UAAU,0BAA0B;EAEpC;EACA,QAAQ;EACR,MAAM"}

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

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

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

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

package/dist/esm/types/tree-changed.d.mts

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

package/dist/esm/types/tree-changed.d.mts.map

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