@real-router/core 0.80.0 → 0.82.0

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

@@ -1,6 +1,5 @@
-import { RouteTreeState } from "./route-node-types.mjs";
-import { Params, SimpleState, State, StateMetaInput, Unsubscribe } from "./base.mjs";
-import { DefaultDependencies, GuardFnFactory, Options, Plugin, Route, RouteConfigUpdate } from "./router.mjs";
+import { Params, SearchParams, SimpleState, State, Unsubscribe } from "./base.mjs";
+import { AnyOptions, DefaultDependencies, GuardFnFactory, Plugin, Route, RouteConfigUpdate } from "./router.mjs";
 import { EventMethodMap, EventName } from "./constants.mjs";
 import { TreeChangedEvent } from "./tree-changed.mjs";
 import { NavigationOptions, StateContext } from "../types.mjs";
@@ -11,14 +10,14 @@ import { NavigationOptions, StateContext } from "../types.mjs";
  *
  * To add a new interceptable method:
  * 1. Add its signature here
- * 2. Wrap it with `createInterceptable()` / `createBinaryInterceptable()` in
+ * 2. Wrap it with `createInterceptable()` / `createTernaryInterceptable()` in
  *    the `registerInternals` block of the Router constructor
  *    (`packages/core/src/Router.ts`)
  */
 interface InterceptableMethodMap {
   start: (path?: string) => Promise<State>;
-  buildPath: (route: string, params?: Params) => string;
-  forwardState: (routeName: string, routeParams: Params) => SimpleState;
+  buildPath: (route: string, params?: Params, search?: SearchParams) => string;
+  forwardState: (routeName: string, routeParams: Params, routeSearch?: SearchParams) => SimpleState;
 }
 /**
  * Type-safe interceptor callback.
@@ -69,9 +68,8 @@ interface ContextNamespaceClaim<T = unknown> {
  * Hides plugin-internal methods from public autocomplete.
  */
 interface PluginApi {
-  makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput) => State<P>;
-  buildState: (routeName: string, routeParams: Params) => RouteTreeState | undefined;
-  forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+  makeState: <P extends Params = Params, S extends SearchParams = SearchParams>(name: string, params?: P, search?: S, path?: string) => State<P, S>;
+  forwardState: <P extends Params = Params, S extends SearchParams = SearchParams>(routeName: string, routeParams: P, routeSearch?: S) => SimpleState<P, S>;
   matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
   /**
    * Navigate to a fully-built `State`, skipping the redundant
@@ -97,8 +95,19 @@ interface PluginApi {
   setRootPath: (rootPath: string) => void;
   getRootPath: () => string;
   addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
-  buildNavigationState: (name: string, params?: Params) => State | undefined;
-  getOptions: () => Options;
+  /**
+   * Builds the State `navigate` would commit, without committing it: resolves
+   * `forwardTo`, checks existence (`undefined` = unknown route) and merges the
+   * route defaults.
+   *
+   * `search` is the query channel (#1571). It was the ONE pipeline entry point
+   * without the slot — `navigate` / `buildPath` / `canNavigateTo` /
+   * `isActiveRoute` / `makeState` all take one — so a query intent could only
+   * be spelled by riding declared keys in the `params` bag. An explicit value
+   * beats such a twin, matching the other five.
+   */
+  buildNavigationState: (name: string, params?: Params, search?: SearchParams) => State | undefined;
+  getOptions: () => AnyOptions;
   getTree: () => unknown;
   addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
   extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.mts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;;UAqCiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,YAAY,eAAe,SAAS;EACpC,eAAe,mBAAmB,aAAa,WAAW;;;;;;KAOhD,cAAc,gBAAgB,2BACxC,MAAM,uBAAuB,OAC1B,MAAM,WAAW,uBAAuB,QACxC,WAAW,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqCtB,sBAAsB;EACrC,QAAQ,OAAO,OAAO,OAAO;EAC7B;;;;;;UAOe;EACf,YAAY,UAAU,SAAS,QAC7B,cACA,SAAS,GACT,eACA,OAAO,mBACJ,MAAM;EAEX,aACE,mBACA,aAAa,WACV;EAEL,eAAe,UAAU,SAAS,QAChC,mBACA,aAAa,MACV,YAAY;EAEjB,YAAY,UAAU,SAAS,QAAQ,iBAAiB,MAAM;;;;;;;;;;;;;;;;;;;;;EAsB9D,kBACE,OAAO,OACP,UAAU,sBACP,QAAQ;EAEb,cAAc;EACd;EAEA,mBAAmB,UAAU,WAC3B,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;EAEL,uBAAuB,cAAc,SAAS,WAAW;EAEzD,kBAAkB;EAElB;EAEA,iBAAiB,gBAAgB,wBAC/B,QAAQ,GACR,IAAI,cAAc,OACf;EAEL,eAAe,YAAY,4BAA4B;;;;;;;;;;;;;EAcvD,sBAAsB,OAAO;EAE7B;KAEG,gBAAgB,uBACf,WAAW,IACV,sBAAsB,aAAa;KACrC,oBAAoB;;EAGvB,iBAAiB,iBAAiB;;;;;UAMnB,UACf,qBAAqB,sBAAsB;EAE3C,MACE,QAAQ,MAAM,kBAAkB,MAAM,eACtC;IAAY;;EAGd,SAAS;;;;;;;;;;;EAYT,SAAS,cAAc,SAAS,kBAAkB;EAElD;EAEA,UAAU,QAAQ,MAAM,kBAAkB,MAAM;EAEhD,MAAM;EAEN,MAAM,iBAAiB,MAAM;;;;;;;;;;;;;EAc7B,mBACE,UAAU,OAAO,iBAAiB,2BAC/B;;;;;UAMU,gBACf,qBAAqB,sBAAsB;EAE3C,MAAM,gBAAgB,cAAc,KAAK,MAAM,aAAa;EAC5D,cAAc,QAAQ;EACtB,MAAM,gBAAgB,uBACpB,MAAM,GACN,OAAO,aAAa;EAEtB,SAAS,MAAM;EACf,SAAS,YAAY;EACrB;EACA,MAAM,YAAY;;;;;UAMH,aACf,qBAAqB,sBAAsB;EAE3C,mBACE,cACA,oBAAoB,eAAe;EAErC,qBACE,cACA,sBAAsB,eAAe;EAEvC,sBAAsB;EACtB,wBAAwB"}
+{"version":3,"file":"api.d.mts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;UAoCiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,YAAY,eAAe,SAAS,QAAQ,SAAS;EACrD,eACE,mBACA,aAAa,QACb,cAAc,iBACX;;;;;;KAOK,cAAc,gBAAgB,2BACxC,MAAM,uBAAuB,OAC1B,MAAM,WAAW,uBAAuB,QACxC,WAAW,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqCtB,sBAAsB;EACrC,QAAQ,OAAO,OAAO,OAAO;EAC7B;;;;;;UAOe;EACf,YAAY,UAAU,SAAS,QAAQ,UAAU,eAAe,cAC9D,cACA,SAAS,GACT,SAAS,GACT,kBACG,MAAM,GAAG;EAEd,eACE,UAAU,SAAS,QACnB,UAAU,eAAe,cAEzB,mBACA,aAAa,GACb,cAAc,MACX,YAAY,GAAG;EAEpB,YAAY,UAAU,SAAS,QAAQ,iBAAiB,MAAM;;;;;;;;;;;;;;;;;;;;;EAsB9D,kBACE,OAAO,OACP,UAAU,sBACP,QAAQ;EAEb,cAAc;EACd;EAEA,mBAAmB,UAAU,WAC3B,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;;;;;;;;;;;;EAaL,uBACE,cACA,SAAS,QACT,SAAS,iBACN;EAEL,kBAAkB;EAElB;EAEA,iBAAiB,gBAAgB,wBAC/B,QAAQ,GACR,IAAI,cAAc,OACf;EAEL,eAAe,YAAY,4BAA4B;;;;;;;;;;;;;EAcvD,sBAAsB,OAAO;EAE7B;KAEG,gBAAgB,uBACf,WAAW,IACV,sBAAsB,aAAa;KACrC,oBAAoB;;EAGvB,iBAAiB,iBAAiB;;;;;UAMnB,UACf,qBAAqB,sBAAsB;EAE3C,MACE,QAAQ,MAAM,kBAAkB,MAAM,eACtC;IAAY;;EAGd,SAAS;;;;;;;;;;;EAYT,SAAS,cAAc,SAAS,kBAAkB;EAElD;EAEA,UAAU,QAAQ,MAAM,kBAAkB,MAAM;EAEhD,MAAM;EAEN,MAAM,iBAAiB,MAAM;;;;;;;;;;;;;EAc7B,mBACE,UAAU,OAAO,iBAAiB,2BAC/B;;;;;UAMU,gBACf,qBAAqB,sBAAsB;EAE3C,MAAM,gBAAgB,cAAc,KAAK,MAAM,aAAa;EAC5D,cAAc,QAAQ;EACtB,MAAM,gBAAgB,uBACpB,MAAM,GACN,OAAO,aAAa;EAEtB,SAAS,MAAM;EACf,SAAS,YAAY;EACrB;EACA,MAAM,YAAY;;;;;UAMH,aACf,qBAAqB,sBAAsB;EAE3C,mBACE,cACA,oBAAoB,eAAe;EAErC,qBACE,cACA,sBAAsB,eAAe;EAEvC,sBAAsB;EACtB,wBAAwB"}

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

@@ -10,9 +10,15 @@ import { StateContext } from "../types.mjs";
  * has no additional effect after the first call.
  */
 type Unsubscribe = () => void;
-interface SimpleState<P extends Params = Params> {
+interface SimpleState<P extends Params = Params, S extends SearchParams = SearchParams> {
   name: string;
   params: P;
+  /**
+   * Query channel — see {@link SearchParams}. Split out of the former single
+   * `params` bag (RFC-4 M2 / #1548). Always present: a frozen empty object when
+   * there are no query params.
+   */
+  search: S;
 }
 type TransitionPhase = "deactivating" | "activating";
 type TransitionReason = "success" | "blocked" | "cancelled" | "error";
@@ -30,9 +36,15 @@ interface TransitionMeta {
     intersection: string;
   };
 }
-interface State<P extends Params = Params> {
+interface State<P extends Params = Params, S extends SearchParams = SearchParams> {
   name: string;
   params: P;
+  /**
+   * Query channel — see {@link SearchParams}. Holds ONLY query-string params;
+   * path params live in {@link State.params} (RFC-4 M2 / #1548). Always present:
+   * a frozen empty object when there are no query params.
+   */
+  search: S;
   path: string;
   transition: TransitionMeta;
   /**
@@ -57,8 +69,36 @@ interface State<P extends Params = Params> {
    */
   context: StateContext & Record<string, unknown>;
 }
-interface StateMetaInput<P extends Params = Params> {
+/**
+ * Descriptor form of a navigation target (RFC-4 M2 / #1548). The two-channel
+ * counterpart to the positional `navigate(name, params, search, opts)` form:
+ * `params` is the path channel, `search` the query channel. Passed as the first
+ * argument to `router.navigate(target, opts?)` / `router.buildPath(target)` /
+ * `router.isActiveRoute(target)` and as the `to` prop of framework `<Link>`s,
+ * so a target can be threaded as one value instead of positional arguments.
+ */
+interface NavigationTarget<P extends Params = Params, S extends SearchParams = SearchParams> {
+  name: string;
+  params?: P;
+  search?: S;
+}
+/**
+ * The two navigation channels a per-route codec operates on (RFC-4 M2 / #1548):
+ * `params` is the path channel, `search` the query channel. Used as **both** the
+ * input and the output of {@link Route.encodeParams} / {@link Route.decodeParams}
+ * — a codec transforms whichever channel(s) it owns and returns the other channel
+ * unchanged (it must be passed through explicitly).
+ *
+ * @remarks
+ * v1 ran the whole (path + query) bag through both callbacks, so a query value
+ * reached `decodeParams`. This two-channel shape preserves that reach: the query
+ * arrives in `search` rather than merged into `params`. Value semantics are
+ * unchanged — only the storage location differs (M2 keeps query parsing/printing
+ * exactly as v1).
+ */
+interface ParamsSearch<P extends Params = Params, S extends SearchParams = SearchParams> {
   params: P;
+  search: S;
 }
 /**
  * Parsed shape produced by `serializeRouterState()` (`@real-router/ssr-utils`,
@@ -90,6 +130,25 @@ interface RouterError extends Error {
 interface Params {
   [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
 }
+/**
+ * Query-parameter primitive values. Mirrors the engine's `QueryParamPrimitive`
+ * (`engine/search-params/types.ts`) — the value form is identical to v1's query
+ * half (the union produced across `queryParamsMode` formats).
+ */
+type SearchParamPrimitive = string | number | boolean | null;
+/**
+ * A single query-parameter value — a primitive or an array of primitives.
+ */
+type SearchParamValue = SearchParamPrimitive | SearchParamPrimitive[];
+/**
+ * Query-parameter bag carried by {@link State.search} — the query channel,
+ * split out of the former single `params` bag in M2 (RFC-4 M2 / #1548). Only
+ * the storage location changes vs v1; value semantics (modes, `queryParamsMode`,
+ * ternary arrays) are unchanged. Structurally matches the engine's internal
+ * `SearchParams` (`engine/search-params/types.ts`), so match results flow into
+ * `State.search` without conversion.
+ */
+type SearchParams = Record<string, SearchParamValue | undefined>;
 //#endregion
-export { Params, RouterError, SerializedRouterState, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export { NavigationTarget, Params, ParamsSearch, RouterError, SearchParamPrimitive, SearchParamValue, SearchParams, SerializedRouterState, SimpleState, State, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
 //# sourceMappingURL=base.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"base.d.mts","names":[],"sources":["../../../src/types/base.ts"],"mappings":";;;;;;;;;;;KAmBY;UAEK,YAAY,UAAU,SAAS;EAC9C;EACA,QAAQ;;KAGE;KAEA;UAEK;EACf,OAAO;EACP,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;;;UAIa,MAAM,UAAU,SAAS;EACxC;EACA,QAAQ;EACR;EACA,YAAY;;;;;;;;;;;;;;;;;;;;;EAqBZ,SAAS,eAAe;;UAGT,eAAe,UAAU,SAAS;EACjD,QAAQ;;;;;;;;;;KAWE,sBAAsB,UAAU,SAAS,UAAU,KAC7D,MAAM;;;;;;;UAUS,oBAAoB;GAClC;WACQ;WACA;WACA;EACT,UAAU;EACV,mBAAmB,KAAK;EACxB,sBAAsB,QAAQ;EAC9B,WAAW;EACX,WAAW;EACX,cAAc;;UAGC;GACd,4EAOG,SACA,WACA"}
+{"version":3,"file":"base.d.mts","names":[],"sources":["../../../src/types/base.ts"],"mappings":";;;;;;;;;;;KAmBY;UAEK,YACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,QAAQ;;;;;;EAMR,QAAQ;;KAGE;KAEA;UAEK;EACf,OAAO;EACP,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;;;UAIa,MACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,QAAQ;;;;;;EAMR,QAAQ;EACR;EACA,YAAY;;;;;;;;;;;;;;;;;;;;;EAqBZ,SAAS,eAAe;;;;;;;;;;UAWT,iBACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,SAAS;EACT,SAAS;;;;;;;;;;;;;;;;UAiBM,aACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB,QAAQ;EACR,QAAQ;;;;;;;;;;KAWE,sBAAsB,UAAU,SAAS,UAAU,KAC7D,MAAM;;;;;;;UAUS,oBAAoB;GAClC;WACQ;WACA;WACA;EACT,UAAU;EACV,mBAAmB,KAAK;EACxB,sBAAsB,QAAQ;EAC9B,WAAW;EACX,WAAW;EACX,cAAc;;UAGC;GACd,4EAOG,SACA,WACA;;;;;;;KAUM;;;;KAKA,mBAAmB,uBAAuB;;;;;;;;;KAU1C,eAAe,eAAe"}

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

@@ -66,6 +66,7 @@ interface ErrorCodeToValueMap {
   CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED";
   REENTRANT_NAVIGATION: "REENTRANT_NAVIGATION";
   REENTRANT_TREE_MUTATION: "REENTRANT_TREE_MUTATION";
+  WRONG_CHANNEL: "WRONG_CHANNEL";
 }
 //#endregion
 export { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod };

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

@@ -1 +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"}
+{"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;EACA"}

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

@@ -1,5 +1,5 @@
 import { QueryParamsMode, QueryParamsOptions } from "./route-node-types.mjs";
-import { Params, RouterError, State, Unsubscribe } from "./base.mjs";
+import { NavigationTarget, Params, ParamsSearch, RouterError, SearchParams, State, Unsubscribe } from "./base.mjs";
 import { LimitsConfig } from "./limits.mjs";
 import { NavigationOptions } from "../types.mjs";
 //#region src/types/router.d.ts
@@ -18,7 +18,7 @@ interface LoggerConfig {
  * 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
+ * concrete `RouterLogger` class lives in core's `utils/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).
  */
@@ -42,26 +42,60 @@ type ForwardToCallback<Dependencies = object> = (getDependency: <K extends keyof
  * Receives a dependency getter function to access router dependencies.
  */
 type DefaultParamsCallback<Dependencies = object> = (getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K]) => Params;
+/**
+ * Callback function for dynamically resolving the default query params.
+ * Receives a dependency getter function to access router dependencies.
+ */
+type DefaultSearchCallback<Dependencies = object> = (getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K]) => SearchParams;
 /**
  * Router configuration options.
  *
  * Note: For input, use `Partial<Options>` as all fields have defaults.
  * After initialization, `getOptions()` returns resolved `Options` with all fields populated.
+ *
+ * Generic over the router's dependency map so the three resolver callbacks
+ * (`defaultRoute` / `defaultParams` / `defaultSearch`) receive a TYPED
+ * `getDependency`. Code that cannot know that map — anything plugin-facing,
+ * and every consumer that reads configuration rather than resolving it —
+ * takes {@link AnyOptions} instead of infecting itself with the parameter.
  */
-interface Options {
+interface Options<Dependencies extends DefaultDependencies = DefaultDependencies> {
   /**
    * Default route to navigate to on start.
    * Empty string means no default route.
    *
    * @default ""
    */
-  defaultRoute: string | DefaultRouteCallback;
+  defaultRoute: string | DefaultRouteCallback<Dependencies>;
   /**
-   * Default parameters for the default route.
+   * Default **path** parameters for the default route.
+   *
+   * Query defaults belong in {@link defaultSearch} — the two are separate
+   * channels (RFC-4 M2 / #1548), exactly as on a route's own config. Until that
+   * twin existed, a query-declared name written here reached the URL only
+   * because the `forwardState` seam still re-channelled the bag on its way
+   * through; that repair is scheduled for removal, so this slot is for path
+   * params and arbitrary app-level data, nothing else.
    *
    * @default {}
    */
-  defaultParams: Params | DefaultParamsCallback;
+  defaultParams: Params | DefaultParamsCallback<Dependencies>;
+  /**
+   * Default **query** parameters for the default route (RFC-4 M2 / #1548) —
+   * the query-channel twin of {@link defaultParams}, and the router-level
+   * counterpart of a route's own `defaultSearch`.
+   *
+   * Passed to `navigateToDefault()` in the query slot, so it is merged into
+   * `state.search` and, subject to `queryParamsMode`, printed into the URL
+   * query string. Like `defaultRoute` / `defaultParams`, it may be a callback,
+   * re-evaluated on every `navigateToDefault()` — the default route can itself
+   * be chosen dynamically, so its query defaults have to be able to follow.
+   * `Options` is generic over the dependency map, so the callback's
+   * `getDependency` is typed against the router's OWN dependencies.
+   *
+   * @default {}
+   */
+  defaultSearch: SearchParams | DefaultSearchCallback<Dependencies>;
   /**
    * How to handle trailing slashes in URLs.
    * - "strict": Route must match exactly
@@ -144,6 +178,21 @@ interface Options {
    */
   limits?: Partial<LimitsConfig>;
 }
+/**
+ * `Options` as seen by code that cannot know the router's dependency map —
+ * `PluginApi.getOptions()`, the matcher, the URL builders.
+ *
+ * `Options<never>` rather than `Options<object>`, and the difference is the
+ * whole point: `keyof never` is `PropertyKey`, so the erased `getDependency`
+ * accepts ANY key and returns `never` — a wider parameter and a narrower
+ * return, which is exactly what contravariance needs for `Options<D>` to flow
+ * in for every `D`. `Options<object>` erases `keyof` to `never` instead and
+ * therefore accepts NOTHING but itself (verified: the assignment fails).
+ *
+ * Every field stays visible; only the callbacks become uncallable, which is
+ * honest — a plugin has no dependency map to resolve them against.
+ */
+type AnyOptions = Options<never>;
 type GuardFn = (toState: State, fromState: State | undefined, signal?: AbortSignal) => boolean | Promise<boolean>;
 type DefaultDependencies = object;
 interface Plugin {
@@ -186,10 +235,13 @@ interface Subscription {
  * For full router access, use the Router interface directly or the useRouter() hook.
  */
 interface Navigator {
-  navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
+  navigate: {
+    (target: NavigationTarget, options?: NavigationOptions): Promise<State>;
+    (routeName: string, routeParams?: Params, routeSearch?: SearchParams, options?: NavigationOptions): Promise<State>;
+  };
   getState: () => State | undefined;
-  isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
-  canNavigateTo: (name: string, params?: Params) => boolean;
+  isActiveRoute: (name: string, params?: Params, search?: SearchParams, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+  canNavigateTo: (name: string, params?: Params, search?: SearchParams) => boolean;
   subscribe: (listener: SubscribeFn) => Unsubscribe;
   subscribeLeave: (listener: LeaveFn) => Unsubscribe;
   isLeaveApproved: () => boolean;
@@ -203,8 +255,8 @@ interface Navigator {
  */
 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;
+  isActiveRoute: (name: string, params?: Params, search?: SearchParams, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+  buildPath: (route: string, params?: Params, search?: SearchParams) => string;
   getState: <P extends Params = Params>() => State<P> | undefined;
   getPreviousState: () => State | undefined;
   areStatesEqual: (state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean) => boolean;
@@ -213,12 +265,15 @@ interface Router<D extends DefaultDependencies = DefaultDependencies> {
   start: (startPath: string) => Promise<State>;
   stop: () => this;
   dispose: () => void;
-  canNavigateTo: (name: string, params?: Params) => boolean;
+  canNavigateTo: (name: string, params?: Params, search?: SearchParams) => 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>;
+  navigate: {
+    (target: NavigationTarget, options?: NavigationOptions): Promise<State>;
+    (routeName: string, routeParams?: Params, routeSearch?: SearchParams, options?: NavigationOptions): Promise<State>;
+  };
   navigateToDefault: (options?: NavigationOptions) => Promise<State>;
   navigateToNotFound: (path?: string) => State;
 }
@@ -257,17 +312,49 @@ interface Route<Dependencies extends DefaultDependencies = DefaultDependencies>
   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.
+   * Encodes the state channels to URL channels before path building (RFC-4 M2 /
+   * #1548). Receives `{ params, search }` and returns `{ params, search }` —
+   * transform whichever channel you own and pass the other through. The path
+   * slots are built from the returned `params`, the query string from the
+   * returned `search`.
+   */
+  encodeParams?: (channels: ParamsSearch) => ParamsSearch;
+  /**
+   * Decodes the matched URL channels to state channels (RFC-4 M2 / #1548).
+   * Receives `{ params, search }` (path params + parsed query) and returns
+   * `{ params, search }`. Runs inside `matchPath`, **before** any search-schema
+   * plugin validation — the v1 transformation order (engine codec → plugin).
+   */
+  decodeParams?: (channels: ParamsSearch) => ParamsSearch;
+  /**
+   * Default **path** parameters for this route (and arbitrary app-level
+   * defaults). Merged into `state.params`; missing path params are filled from
+   * here. Query defaults belong in {@link defaultSearch} (RFC-4 M2 / #1548).
+   *
+   * ⚠ **The slot IS the channel** — `ba0f6b18b` retired the routing #1549
+   * introduced, and this doc described it for one release. A name the route
+   * declares with `?` written here is NOT re-routed to the query string: it is
+   * REFUSED at registration, so `createRouter` / `add` / `replace` / `update` /
+   * `setRootPath` throw, naming the key and telling you to move it to
+   * {@link defaultSearch}. Without that check the router would build a state out
+   * of config it had just accepted and its own always-on channel guard would
+   * reject it on `start()`.
    *
-   * These values are merged into state.params when creating route states.
-   * Missing URL params are filled from defaultParams.
+   * A key the route declares NOWHERE is legitimate here and stays in
+   * `state.params` as app-level data — it never reaches the URL, which
+   * `@real-router/validation-plugin` reports once per route+key (#1579).
    */
   defaultParams?: Params;
+  /**
+   * Default **query** (search) parameters for this route (RFC-4 M2 / #1548) —
+   * the query-channel twin of {@link defaultParams}. Merged into `state.search`
+   * and, subject to `queryParamsMode`, printed into the URL query string. A key
+   * the route does not declare as a query param (`?name`) follows the same
+   * `queryParamsMode` rules as a runtime `search` value (loose prints,
+   * default/strict drops).
+   */
+  defaultSearch?: SearchParams;
 }
 /**
  * Configuration update options for `updateRoute()`.
@@ -299,15 +386,17 @@ interface RouteConfigUpdate<Dependencies extends DefaultDependencies = DefaultDe
   forwardTo?: string | ForwardToCallback<Dependencies> | null;
   /** Set to null to remove defaultParams */
   defaultParams?: Params | null;
+  /** Set to null to remove defaultSearch (RFC-4 M2 / #1548) */
+  defaultSearch?: SearchParams | null;
   /** Set to null to remove decoder */
-  decodeParams?: ((params: Params) => Params) | null;
+  decodeParams?: ((channels: ParamsSearch) => ParamsSearch) | null;
   /** Set to null to remove encoder */
-  encodeParams?: ((params: Params) => Params) | null;
+  encodeParams?: ((channels: ParamsSearch) => ParamsSearch) | 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 };
+export { AnyOptions, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DefaultSearchCallback, 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

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

@@ -8,7 +8,7 @@ import { DefaultDependencies, Route, RouteConfigUpdate } from "./router.mjs";
  * 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">;
+type TreeStructuralPatch<Dependencies extends DefaultDependencies = DefaultDependencies> = Pick<RouteConfigUpdate<Dependencies>, "forwardTo" | "defaultParams" | "defaultSearch" | "encodeParams" | "decodeParams">;
 interface TreeChangedAdd<Dependencies extends DefaultDependencies = DefaultDependencies> {
   readonly op: "add";
   /** Top-level routes that were added (deep-cloned + frozen; caller untouched). */

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

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

package/dist/esm/types.d.mts

@@ -1,7 +1,7 @@
 import { QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState } from "./types/route-node-types.mjs";
-import { Params, RouterError, SerializedRouterState, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe } from "./types/base.mjs";
+import { NavigationTarget, Params, ParamsSearch, RouterError, SearchParamPrimitive, SearchParamValue, SearchParams, SerializedRouterState, SimpleState, State, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe } from "./types/base.mjs";
 import { LimitsConfig } from "./types/limits.mjs";
-import { DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ForwardToCallback, GuardFn, GuardFnFactory, LeaveFn, LeaveState, Listener, LogCallback, LogLevel, LogLevelConfig, LoggerConfig, Navigator, Options, Plugin, PluginFactory, Route, RouteConfigUpdate, Router, RouterLogger, SubscribeFn, SubscribeState, Subscription } from "./types/router.mjs";
+import { AnyOptions, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DefaultSearchCallback, ForwardToCallback, GuardFn, GuardFnFactory, LeaveFn, LeaveState, Listener, LogCallback, LogLevel, LogLevelConfig, LoggerConfig, Navigator, Options, Plugin, PluginFactory, Route, RouteConfigUpdate, Router, RouterLogger, SubscribeFn, SubscribeState, Subscription } from "./types/router.mjs";
 import { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod } from "./types/constants.mjs";
 import { TreeChangedAdd, TreeChangedClear, TreeChangedEvent, TreeChangedRemove, TreeChangedReplace, TreeChangedUpdate, TreeStructuralPatch } from "./types/tree-changed.mjs";
 import { ContextNamespaceClaim, DependenciesApi, InterceptableMethodMap, InterceptorFn, LifecycleApi, PluginApi, RoutesApi } from "./types/api.mjs";
@@ -55,7 +55,7 @@ interface NavigationOptions {
    *
    * @example
    * // Redirect after login - prevent back button to login page
-   * router.navigate('dashboard', {}, { replace: true });
+   * router.navigate('dashboard', {}, undefined, { replace: true });
    *
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState}
    */
@@ -97,13 +97,22 @@ interface NavigationOptions {
    * @default false
    *
    * @example
-   * // Refresh current page data
-   * router.navigate(currentRoute.name, currentRoute.params, { reload: true });
+   * // Refresh current page data. Options sit at slot 4 since RFC-4 M2
+   * // (#1548) — slot 3 is the query channel, so the pre-M2 three-argument
+   * // spelling puts `{ reload: true }` in `search`: the reload never happens
+   * // and the page's own query is rebuilt from an object that does not have
+   * // it (measured: `/search?term=react` → `/search`).
+   * router.navigate(
+   *   currentRoute.name,
+   *   currentRoute.params,
+   *   currentRoute.search,
+   *   { 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 });
+   * // Force re-fetch on the same route with a different query. The query is
+   * // its own channel now — pass it at slot 3, not inside the path bag.
+   * router.navigate('search', {}, { term: 'react' }, { reload: true });
    *
    * @see {@link force} for alternative that forces transition
    * @see {@link Router.areStatesEqual} for state comparison logic
@@ -130,7 +139,7 @@ interface NavigationOptions {
    *
    * @example
    * // Force transition for tracking even if params didn't change
-   * router.navigate('analytics', { event: 'pageview' }, { force: true });
+   * router.navigate('analytics', {}, { event: 'pageview' }, { force: true });
    *
    * @see {@link reload} for semantic equivalent (preferred for refresh scenarios)
    */
@@ -159,7 +168,7 @@ interface NavigationOptions {
    * @example
    * // Force logout even with unsaved changes
    * function forceLogout() {
-   *   router.navigate('login', {}, {
+   *   router.navigate('login', {}, undefined, {
    *     forceDeactivate: true,
    *     replace: true
    *   });
@@ -204,5 +213,5 @@ interface NavigationOptions {
   signal?: AbortSignal | undefined;
 }
 //#endregion
-export { type ContextNamespaceClaim, type DefaultDependencies, type DefaultParamsCallback, type DefaultRouteCallback, type DependenciesApi, type ErrorCodeKeys, type ErrorCodeToValueMap, type ErrorCodeValues, type EventMethodMap, type EventName, type EventToNameMap, type EventToPluginMap, type EventsKeys, type ForwardToCallback, type GuardFn, type GuardFnFactory, type InterceptableMethodMap, type InterceptorFn, type LeaveFn, type LeaveState, type LifecycleApi, type LimitsConfig, type Listener, type LogCallback, type LogLevel, type LogLevelConfig, type LoggerConfig, NavigationOptions, type Navigator, type Options, type Params, type Plugin, type PluginApi, type PluginFactory, type PluginMethod, type QueryParamsMode, type QueryParamsOptions, type Route, type RouteConfigUpdate, type RouteParams, type RouteTreeState, type Router, type RouterError, type RouterLogger, type RoutesApi, type SerializedRouterState, type SimpleState, type State, StateContext, type StateMetaInput, type SubscribeFn, type SubscribeState, type Subscription, type TransitionMeta, type TransitionPhase, type TransitionReason, type TreeChangedAdd, type TreeChangedClear, type TreeChangedEvent, type TreeChangedRemove, type TreeChangedReplace, type TreeChangedUpdate, type TreeStructuralPatch, type Unsubscribe };
+export { type AnyOptions, type ContextNamespaceClaim, type DefaultDependencies, type DefaultParamsCallback, type DefaultRouteCallback, type DefaultSearchCallback, type DependenciesApi, type ErrorCodeKeys, type ErrorCodeToValueMap, type ErrorCodeValues, type EventMethodMap, type EventName, type EventToNameMap, type EventToPluginMap, type EventsKeys, type ForwardToCallback, type GuardFn, type GuardFnFactory, type InterceptableMethodMap, type InterceptorFn, type LeaveFn, type LeaveState, type LifecycleApi, type LimitsConfig, type Listener, type LogCallback, type LogLevel, type LogLevelConfig, type LoggerConfig, NavigationOptions, type NavigationTarget, type Navigator, type Options, type Params, type ParamsSearch, type Plugin, type PluginApi, type PluginFactory, type PluginMethod, type QueryParamsMode, type QueryParamsOptions, type Route, type RouteConfigUpdate, type RouteParams, type RouteTreeState, type Router, type RouterError, type RouterLogger, type RoutesApi, type SearchParamPrimitive, type SearchParamValue, type SearchParams, type SerializedRouterState, type SimpleState, type State, StateContext, type SubscribeFn, type SubscribeState, type Subscription, type TransitionMeta, type TransitionPhase, type TransitionReason, type TreeChangedAdd, type TreeChangedClear, type TreeChangedEvent, type TreeChangedRemove, type TreeChangedReplace, type TreeChangedUpdate, type TreeStructuralPatch, type Unsubscribe };
 //# sourceMappingURL=types.d.mts.map

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

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

package/dist/esm/validation.mjs

@@ -1,2 +1,2 @@
-import{a as e,i as t,n,r,u as i}from"./buildParamMeta-bOLhLF9h.mjs";function a(e,t){return TypeError(`[router.${e}] ${t}`)}function o(e,t,n,r){let i=new Set;for(let o of e){if(i.has(o))throw a(n,`Invalid path for route "${t}": duplicate parameter name ':${o}' in "${r}" (a param name must be unique within a route — the second binding would overwrite the first)`);i.add(o)}}function s(e,t,r,i,o){let s=new Set(e);for(let e of t){if(n.test(e))throw a(i,`Invalid path for route "${r}": invalid query-param name "${e}" in "${o}" (a query-param name cannot contain '<' or '>' — it would never round-trip; rename the query param)`);if(s.has(e))throw a(i,`Invalid path for route "${r}": "${e}" is declared as both a path param and a query param in "${o}" — buildPath would emit its value twice (rename one)`)}}function c(e){let t=!0,n=!1;for(let r of e){if(r===`/`){t=!0;continue}if(t&&=(n=r===`:`||r===`*`,!1),!n&&r.codePointAt(0)>=128)return!0}return!1}function l(e,t,n){switch(e){case`name-less`:case`trailing-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') without a name in "${n}"`;case`fused-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') must begin a segment, but "${n}" fuses one to a static prefix (use a boundary marker like "/a/:b")`}}function u(e,t){return e.code===`optional-removed`?`Invalid path for route "${t}": optional params are not supported — "${e.segment}". Declare two sibling routes instead: "${e.withoutSegment}" and "${e.requiredForm}" (the route hierarchy already expresses optionality)`:`Invalid path for route "${t}": regex constraints are not supported — '<' and '>' are reserved in path segments ("${e.segment}"). Match the segment as a plain string and validate the value in a guard (canActivate) or app code`}function d(n,i,d,f){if(typeof n!=`string`){let e;throw e=n===null?`null`:Array.isArray(n)?`array`:typeof n,a(d,`Route path must be a string, got ${e}`)}if(n===``)return;if(/\s/.test(n))throw a(d,`Invalid path for route "${i}": whitespace not allowed in "${n}"`);if(!/^([/?~]|[^/]+$)/.test(n))throw a(d,`Route "${i}" has invalid path format: "${n}". Path should start with '/', '~', '?' or be a relative segment.`);if(n.includes(`//`))throw a(d,`Invalid path for route "${i}": double slashes not allowed in "${n}"`);let{pathPattern:p,urlParams:m,queryParams:h}=r(n);o(m,i,d,n),s(m,h,i,d,n);let g=t(p);if(g!==void 0)throw a(d,u(g,i));let _=e(p);if(_!==void 0)throw a(d,l(_,i,n));if(c(p))throw a(d,`Invalid path for route "${i}": non-ASCII static segment in "${n}" — match compares static segments raw and rejects non-ASCII input, so this route would never match. Percent-encode it (e.g. '/caf%C3%A9') or use a param`);let v=f&&f.paramMeta.urlParams.length>0;if(n.startsWith(`~`)&&v)throw a(d,`Absolute path "${n}" cannot be used under parent route with URL parameters`)}const f=/^[A-Z_a-z][\w-]*$/,p=/\S/,m=1e4;function h(e){if(e===null)return`null`;if(typeof e==`object`){try{let t=e.constructor;if(typeof t==`function`&&t.name!==`Object`)return t.name||`object`}catch{}return`object`}return typeof e}function g(e){for(let t of Object.keys(e)){let n=Object.getOwnPropertyDescriptor(e,t);if(n&&(n.get||n.set))return!0}return!1}function _(e,t){if(!e||typeof e!=`object`)throw TypeError(`[router.${t}] Route must be an object, got ${h(e)}`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`[router.${t}] Route must be a plain object, got ${h(e)}`);if(g(e))throw TypeError(`[router.${t}] Route must not have getters or setters`)}function v(e,t){if(e.encodeParams!==void 0&&typeof e.encodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" encodeParams must be a function`)}function y(e,t){if(e.decodeParams!==void 0&&typeof e.decodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" decodeParams must be a function`)}function b(e,t){if(typeof e.name!=`string`)throw TypeError(`[router.${t}] Route name must be a string, got ${h(e.name)}`);let n=e.name;if(n===``)throw TypeError(`[router.${t}] Route name cannot be empty`);if(!p.test(n))throw TypeError(`[router.${t}] Route name cannot contain only whitespace`);if(n.length>m)throw TypeError(`[router.${t}] Route name exceeds maximum length of ${m} characters`);if(!n.startsWith(`@@`)){if(n.includes(`.`))throw TypeError(`[router.${t}] Route name "${n}" cannot contain dots. Use children array or { parent } option in addRoute() instead.`);if(!f.test(n))throw TypeError(`[router.${t}] Invalid route name "${n}". Name must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens.`)}}function x(e,t){if(!t.includes(`.`))return e.children.get(t);let n=e;for(let e of t.split(`.`))if(n=n.children.get(e),!n)return;return n}function S(e,t,n){if(x(e,t))throw Error(`[router.${n}] Route "${t}" already exists`)}function C(e,t,n){if(e.has(t))throw Error(`[router.${n}] Duplicate route "${t}" in batch`);e.add(t)}function w(e,t,n,r){let i=t===``?e:x(e,t);if(i){for(let e of i.children.values())if(e.path===n)throw Error(`[router.${r}] Path "${n}" is already defined`)}}function T(e,t,n,r){let i=e.get(t);if(i?.has(n))throw Error(`[router.${r}] Path "${n}" is already defined`);i?i.add(n):e.set(t,new Set([n]))}function E(e,t,n,r=``,i,a){_(e,t);let o=e;b(o,t),d(o.path,o.name,t,n),v(o,t),y(o,t);let s=o.name,c=r?`${r}.${s}`:s;n&&c&&S(n,c,t),i&&C(i,c,t);let l=o.path,u=r;if(n&&w(n,u,l,t),a&&T(a,u,l,t),o.children!==void 0){if(!Array.isArray(o.children))throw TypeError(`[router.${t}] Route "${s}" children must be an array, got ${h(o.children)}`);for(let e of o.children)E(e,t,n,c,i,a)}}export{i as getInternals,E as validateRoute};
+import{a as e,i as t,n,r,u as i}from"./buildParamMeta-D8td47fL.mjs";function a(e,t){return TypeError(`[router.${e}] ${t}`)}function o(e,t,n,r){let i=new Set;for(let o of e){if(i.has(o))throw a(n,`Invalid path for route "${t}": duplicate parameter name ':${o}' in "${r}" (a param name must be unique within a route — the second binding would overwrite the first)`);i.add(o)}}function s(e,t,r,i){for(let o of e)if(n.test(o))throw a(r,`Invalid path for route "${t}": invalid query-param name "${o}" in "${i}" (a query-param name cannot contain '<' or '>' — it would never round-trip; rename the query param)`)}function c(e){let t=!0,n=!1;for(let r of e){if(r===`/`){t=!0;continue}if(t&&=(n=r===`:`||r===`*`,!1),!n&&r.codePointAt(0)>=128)return!0}return!1}function l(e,t,n){switch(e){case`name-less`:case`trailing-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') without a name in "${n}"`;case`fused-marker`:return`Invalid path for route "${t}": parameter marker (':' or '*') must begin a segment, but "${n}" fuses one to a static prefix (use a boundary marker like "/a/:b")`}}function u(e,t){return e.code===`optional-removed`?`Invalid path for route "${t}": optional params are not supported — "${e.segment}". Declare two sibling routes instead: "${e.withoutSegment}" and "${e.requiredForm}" (the route hierarchy already expresses optionality)`:`Invalid path for route "${t}": regex constraints are not supported — '<' and '>' are reserved in path segments ("${e.segment}"). Match the segment as a plain string and validate the value in a guard (canActivate) or app code`}function d(n,i,d,f){if(typeof n!=`string`){let e;throw e=n===null?`null`:Array.isArray(n)?`array`:typeof n,a(d,`Route path must be a string, got ${e}`)}if(n===``)return;if(/\s/.test(n))throw a(d,`Invalid path for route "${i}": whitespace not allowed in "${n}"`);if(!/^([/?~]|[^/]+$)/.test(n))throw a(d,`Route "${i}" has invalid path format: "${n}". Path should start with '/', '~', '?' or be a relative segment.`);if(n.includes(`//`))throw a(d,`Invalid path for route "${i}": double slashes not allowed in "${n}"`);let{pathPattern:p,urlParams:m,queryParams:h}=r(n);o(m,i,d,n),s(h,i,d,n);let g=t(p);if(g!==void 0)throw a(d,u(g,i));let _=e(p);if(_!==void 0)throw a(d,l(_,i,n));if(c(p))throw a(d,`Invalid path for route "${i}": non-ASCII static segment in "${n}" — match compares static segments raw and rejects non-ASCII input, so this route would never match. Percent-encode it (e.g. '/caf%C3%A9') or use a param`);let v=f&&f.paramMeta.urlParams.length>0;if(n.startsWith(`~`)&&v)throw a(d,`Absolute path "${n}" cannot be used under parent route with URL parameters`)}const f=/^[A-Z_a-z][\w-]*$/,p=/\S/,m=1e4;function h(e){if(e===null)return`null`;if(typeof e==`object`){try{let t=e.constructor;if(typeof t==`function`&&t.name!==`Object`)return t.name||`object`}catch{}return`object`}return typeof e}function g(e){for(let t of Object.keys(e)){let n=Object.getOwnPropertyDescriptor(e,t);if(n&&(n.get||n.set))return!0}return!1}function _(e,t){if(!e||typeof e!=`object`)throw TypeError(`[router.${t}] Route must be an object, got ${h(e)}`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`[router.${t}] Route must be a plain object, got ${h(e)}`);if(g(e))throw TypeError(`[router.${t}] Route must not have getters or setters`)}function v(e,t){if(e.encodeParams!==void 0&&typeof e.encodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" encodeParams must be a function`)}function y(e,t){if(e.decodeParams!==void 0&&typeof e.decodeParams!=`function`)throw TypeError(`[router.${t}] Route "${String(e.name)}" decodeParams must be a function`)}function b(e,t){if(typeof e.name!=`string`)throw TypeError(`[router.${t}] Route name must be a string, got ${h(e.name)}`);let n=e.name;if(n===``)throw TypeError(`[router.${t}] Route name cannot be empty`);if(!p.test(n))throw TypeError(`[router.${t}] Route name cannot contain only whitespace`);if(n.length>m)throw TypeError(`[router.${t}] Route name exceeds maximum length of ${m} characters`);if(!n.startsWith(`@@`)){if(n.includes(`.`))throw TypeError(`[router.${t}] Route name "${n}" cannot contain dots. Use children array or { parent } option in addRoute() instead.`);if(!f.test(n))throw TypeError(`[router.${t}] Invalid route name "${n}". Name must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens.`)}}function x(e,t){if(!t.includes(`.`))return e.children.get(t);let n=e;for(let e of t.split(`.`))if(n=n.children.get(e),!n)return;return n}function S(e,t,n){if(x(e,t))throw Error(`[router.${n}] Route "${t}" already exists`)}function C(e,t,n){if(e.has(t))throw Error(`[router.${n}] Duplicate route "${t}" in batch`);e.add(t)}function w(e,t,n,r){let i=t===``?e:x(e,t);if(i){for(let e of i.children.values())if(e.path===n)throw Error(`[router.${r}] Path "${n}" is already defined`)}}function T(e,t,n,r){let i=e.get(t);if(i?.has(n))throw Error(`[router.${r}] Path "${n}" is already defined`);i?i.add(n):e.set(t,new Set([n]))}function E(e,t,n,r=``,i,a){_(e,t);let o=e;b(o,t),d(o.path,o.name,t,n),v(o,t),y(o,t);let s=o.name,c=r?`${r}.${s}`:s;n&&c&&S(n,c,t),i&&C(i,c,t);let l=o.path,u=r;if(n&&w(n,u,l,t),a&&T(a,u,l,t),o.children!==void 0){if(!Array.isArray(o.children))throw TypeError(`[router.${t}] Route "${s}" children must be an array, got ${h(o.children)}`);for(let e of o.children)E(e,t,n,c,i,a)}}export{i as getInternals,E as validateRoute};
 //# sourceMappingURL=validation.mjs.map