@stealthscale/provider-router 0.1.0 → 0.4.1

package/dist/index.d.ts

@@ -1,82 +1,117 @@
 import { ComponentProps, FunctionComponent, ReactNode } from "react";
-export * from "@tanstack/react-router";
-//#region src/declaration.d.ts
+import { AnyRoute, AnyRoute as AnyRoute$1, AnyRouter, ErrorComponentProps, ErrorRouteComponent, ErrorRouteComponent as ErrorRouteComponent$1, Link, Navigate, NotFoundRouteComponent, NotFoundRouteProps, Outlet, RouterContextProvider, RouterHistory, RouterProvider, createLink, createMemoryHistory, createRootRoute, createRootRouteWithContext, createRoute, createRouter, isNotFound, isRedirect, notFound, redirect, useChildMatches, useLinkProps, useLocation, useMatches, useNavigate, useRouteContext, useRouter, useRouterState } from "@tanstack/react-router";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/basepath.d.ts
+/**
+ * Derives the path a router mounts its routes under from where the documents are served.
+ */
 /**
- * Loads a page on first navigation, rather than with the bundle that declared it.
+ * Derives the router's base path from the base the bundler was given.
  *
  * @remarks
- *   A wrapper rather than a bare function, because a React component is a function too and nothing
- *   at run time separates one from an importer.
+ *   The bundler's base locates the assets: a path under the application's origin for an ordinary
+ *   deployment, an absolute URL for one whose assets are served from another host. The router's
+ *   base path locates the documents, which is always a path on the application's origin. A
+ *   path-only base locates both, so its path becomes the router's without the trailing slash the
+ *   bundler writes. A base naming a host says nothing about the documents, so the router mounts at
+ *   the root.
+ * @param base - Base the bundler was given, which is `import.meta.env.BASE_URL` in a page.
+ * @param documents - Path the documents are served under, for a deployment whose assets are served
+ *   from another host. Omitted, the base decides.
+ * @returns The path the router mounts under, with a leading slash and no trailing slash.
+ */
+export declare function basepathOf(base: string, documents?: string): string;
+//#endregion
+//#region src/reference.d.ts
+/**
+ * Types a reference to a route, which contains no path, no module and no address.
  */
-interface LazyPage {
+/**
+ * The parameters of a route whose reference has no parameter type.
+ */
+type AnyParams = Readonly<Record<string, string>>;
+/**
+ * Points at a route by the id it was declared under, with its parameters and its search in the
+ * type alone.
+ *
+ * @remarks
+ *   The type is structural, so a plugin SDK's own reference type satisfies it, and this package
+ *   does not depend on that SDK. A reference contains no path, because whoever composes the
+ *   application chooses the path, and a link written against a path would break when they placed
+ *   the route elsewhere. No code reads `~types` at run time. A link that passes `id` to a route
+ *   whose path has `invoice` fails to compile because of it, and a page reads its search typed.
+ */
+interface RouteRef<Params extends AnyParams = AnyParams, Search = unknown> {
   /**
-   * The export the page is published under. The module's default export where it states none.
+   * The parameters and the search, in the type alone.
    */
-  readonly export?: string | undefined;
+  readonly "~types"?: {
+    /**
+     * The parameters of the route's path, which a link fills.
+     */
+    readonly params: Params;
+    /**
+     * The search that the route's validator returns, which a page reads and a link writes.
+     */
+    readonly search: Search;
+  };
   /**
-   * Imports the module holding the page.
+   * The full id the route was declared under.
    */
-  readonly load: () => Promise<Readonly<Record<string, FunctionComponent>>>;
+  readonly id: string;
 }
 /**
- * Reports one fault a schema found.
+ * Points at a route, either by a reference or by the bare id of one.
  */
-interface SearchIssue {
-  /**
-   * The fault, in words a person can read.
-   */
-  readonly message: string;
-}
+type RouteTarget<Params extends AnyParams = AnyParams, Search = unknown> = RouteRef<Params, Search> | string;
 /**
- * Reports that a value was refused, and why.
+ * Reports whether a link to a route must pass parameters: true where the parameters have a
+ * required key.
+ *
+ * @remarks
+ *   A bare id and an untyped reference take `AnyParams`, whose keys are any string, so a link to
+ *   either passes parameters at will. A reference to a path without parameters, or with optional
+ *   ones alone, has no required key.
  */
-interface SearchRefused {
-  /**
-   * Each fault the schema found.
-   */
-  readonly issues: readonly SearchIssue[];
-}
+type RequiresParams<Params extends AnyParams> = string extends keyof Params ? false : Partial<Params> extends Params ? false : true;
 /**
- * Reports that a value was accepted, and what it read as.
+ * Describes the parameters argument of a function that resolves a link: required where
+ * `RequiresParams` is true, and optional otherwise.
  */
-interface SearchRead {
-  /**
-   * Nothing, which is how a reader tells an acceptance from a refusal.
-   */
-  readonly issues?: undefined;
-  /**
-   * The value, as the schema read it.
-   */
-  readonly value: unknown;
-}
+type ParamsArgument<Params extends AnyParams> = RequiresParams<Params> extends true ? [params: Params] : [params?: Params | undefined];
+//#endregion
+//#region src/declaration.d.ts
 /**
- * Checks a value against a schema, in the shape Standard Schema settled on.
+ * Loads a page on the first navigation to it.
+ *
+ * @remarks
+ *   The importer is a member of an object, because a React component is a function too and nothing
+ *   at run time tells one from an importer.
  */
-interface StandardSurface {
+interface LazyPage {
+  /**
+   * The export the page is published under. The module's default export where it states none.
+   */
+  readonly export?: string | undefined;
   /**
-   * Checks a value and returns what it read, or why it refused.
+   * Imports the module that exports the page.
    */
-  readonly validate: (value: unknown) => Promise<SearchRead | SearchRefused> | SearchRead | SearchRefused;
+  readonly load: () => Promise<Readonly<Record<string, FunctionComponent>>>;
 }
 /**
- * Reads a search string into the values a route draws with.
+ * Validates a route's search string and types the values its page reads.
  *
  * @remarks
- *   Stated structurally rather than by the library's own name, so a declaration carries a validator
- *   from any library that implements Standard Schema without this package depending on any of them.
+ *   Any library that implements Standard Schema provides one. This package depends on the
+ *   specification's types alone, so a declaration takes a validator from any such library.
  */
-interface SearchValidator {
-  /**
-   * The Standard Schema surface, which is the whole of what the library reads.
-   */
-  readonly "~standard": StandardSurface;
-}
+type SearchValidator<Search = unknown> = StandardSchemaV1<unknown, Search>;
 /**
- * Draws a frame around whatever a route below it draws.
+ * Describes the props of a layout, which renders a frame around the route below it.
  */
 interface LayoutProps {
   /**
-   * The route drawn inside the frame, which React supplies.
+   * The route below the layout, which React renders inside the frame.
    */
   readonly children?: ReactNode | undefined;
   /**
@@ -84,6 +119,35 @@ interface LayoutProps {
    */
   readonly options?: Readonly<Record<string, unknown>> | undefined;
 }
+/**
+ * Lists what a declared route's loader receives.
+ */
+interface RouteLoaderArgs {
+  /**
+   * The route's context, which contains whatever the application put in the router's context.
+   */
+  readonly context: unknown;
+  /**
+   * The parameters the route's path names.
+   */
+  readonly params: AnyParams;
+  /**
+   * True where the router loads the route ahead of a navigation.
+   */
+  readonly preload: boolean;
+  /**
+   * The route's search, as its validator returned it.
+   */
+  readonly search: unknown;
+  /**
+   * Signal that aborts when a later navigation supersedes this one.
+   */
+  readonly signal: AbortSignal;
+}
+/**
+ * Loads a route's data before its page renders.
+ */
+type RouteLoader = (args: RouteLoaderArgs) => Promise<void> | void;
 /**
  * Describes one route a host declares, in the form the compiler takes.
  *
@@ -94,7 +158,7 @@ interface LayoutProps {
  */
 interface RouteDeclaration<Condition = unknown> {
   /**
-   * Draws the page, either directly or loaded on first navigation.
+   * The page, as a component or as a module that loads on the first navigation to it.
    */
   readonly component: FunctionComponent | LazyPage;
   /**
@@ -102,19 +166,25 @@ interface RouteDeclaration<Condition = unknown> {
    */
   readonly id: string;
   /**
-   * The layouts it is drawn in, outermost first. Drawn bare where it names none.
+   * The layouts the page renders in, by name, outermost first. The page renders in none where the
+   * list is absent.
    */
   readonly layout?: readonly string[] | undefined;
   /**
    * Passed to each layout untouched, for whatever the layout reads.
    */
   readonly layoutOptions?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Loads the route's data before its page renders, and again when its search changes.
+   */
+  readonly loader?: RouteLoader | undefined;
   /**
    * The menu entry a menu reads, which the compiler writes onto the route without reading.
    */
   readonly navigation?: unknown;
   /**
-   * The pane it is drawn in, which this package refuses because it draws no panes.
+   * The pane the page renders in, which the compiler refuses, because a matched route renders the
+   * whole screen.
    */
   readonly outlet?: string | undefined;
   /**
@@ -130,7 +200,7 @@ interface RouteDeclaration<Condition = unknown> {
    */
   readonly sample?: Readonly<Record<string, string>> | undefined;
   /**
-   * Reads the search string this route draws with.
+   * Validates the route's search string, and types the values its page reads.
    */
   readonly search?: SearchValidator | undefined;
   /**
@@ -139,12 +209,12 @@ interface RouteDeclaration<Condition = unknown> {
   readonly when?: Condition | undefined;
 }
 /**
- * Carries the name a route goes by, and whatever a menu reads off it.
+ * Describes the id a compiled route is named by, and the menu entry a menu reads from it.
  *
  * @remarks
- *   Written onto the route's `staticData`, which the library hands back on every match. A menu, a
- *   breadcrumb or a telemetry hook therefore reads the name off the page it is drawing rather than
- *   holding a second copy of the list.
+ *   The compiler writes it into the route's `staticData`, which the library returns with every
+ *   match. A menu, a breadcrumb or a telemetry hook reads the id from the match of the page on
+ *   screen, and keeps no second copy of the list.
  */
 interface DeclaredRoute {
   /**
@@ -152,99 +222,79 @@ interface DeclaredRoute {
    */
   readonly id: string;
   /**
-   * The menu entry the declaration carried, passed through untouched.
+   * The menu entry the declaration stated, passed through untouched.
    */
   readonly navigation?: unknown;
 }
 /**
- * Reports whether a route's condition holds for whoever is asking.
+ * Describes the address a navigation enters, as an evaluator reads it.
+ */
+interface EnteredLocation {
+  /**
+   * The path, the search and the hash of the address, without its origin.
+   */
+  readonly href: string;
+}
+/**
+ * Returns whether a route's condition is true for the router whose context is given.
  *
  * @remarks
- *   Returning false makes the route a 404, because a route nobody may reach does not exist. An
- *   evaluator wanting anything else, such as sending an unauthenticated person to sign in, throws
- *   the library's own `redirect` instead.
- */
-type Evaluate<Condition = unknown> = (when: Condition) => boolean;
-import * as import__tanstack_react_router from "@tanstack/react-router";
+ *   Returning false makes the route not found, because a route nobody may open does not exist. An
+ *   evaluator that wants anything else, such as sending an unauthenticated person to sign in,
+ *   throws the library's own `redirect` instead, and reads the address to return to from
+ *   `location`. The context is the route's, as `beforeLoad` receives it, so the evaluator reads the
+ *   state of the router it runs in, and one tree serves every router built from it. A caller that
+ *   evaluates outside a navigation, such as a menu, passes no location.
+ */
+type Evaluate<Condition = unknown, Context = unknown> = (when: Condition, context: Context, location?: EnteredLocation) => boolean;
 //#endregion
 //#region src/compile.d.ts
 /**
  * Describes what one compilation needs beyond the declarations themselves.
  */
-interface CompileOptions<Condition = unknown> {
+interface CompileOptions<Condition = unknown, Context = unknown> {
   /**
-   * Draws a page whose own component threw or failed to load, named per declaration.
+   * Builds the error component of each declaration's route, which renders when the page throws or
+   * fails to load.
    */
-  readonly errorComponent?: ((declaration: RouteDeclaration<Condition>) => tanstack_d_exports.ErrorRouteComponent) | undefined;
+  readonly errorComponent?: ((declaration: RouteDeclaration<Condition>) => ErrorRouteComponent$1) | undefined;
   /**
-   * Reports whether a route's condition holds. Required where any declaration states one.
+   * Returns whether a route's condition is true. Required where any declaration states one.
    */
-  readonly evaluate?: Evaluate<Condition> | undefined;
+  readonly evaluate?: Evaluate<Condition, Context> | undefined;
   /**
    * The layouts a declaration may name.
    */
   readonly layouts?: Readonly<Record<string, FunctionComponent<LayoutProps>>> | undefined;
+  /**
+   * Renders in a compiled route's place where its page, its loader or its condition throws the
+   * router's not-found. Where it is absent, the not-found renders at the nearest route above that
+   * states one.
+   */
+  readonly notFoundComponent?: NotFoundRouteComponent | undefined;
   /**
    * The route every compiled route hangs under, which this compilation never changes.
    */
-  readonly parent: tanstack_d_exports.AnyRoute;
+  readonly parent: AnyRoute$1;
 }
 /**
  * Compiles declarations into routes under the parent a caller states.
  *
  * @remarks
- *   Pure with respect to the caller. It creates routes and never mutates the parent, so a second
- *   call returns a second set of routes sharing no object with the first. That is what keeps two
- *   routers in one process from reading each other's tree through the library's process-wide cache.
- *   Compile every contributor's declarations in one call. Two calls under one parent cannot see
- *   each other's paths, and `routeMap` reports the collision once the tree is assembled.
+ *   The compiler creates routes and never mutates the parent, so a second call returns a second set
+ *   of routes that shares no object with the first. Two routers in one process therefore never read
+ *   each other's tree through the library's process-wide cache. Compile every contributor's
+ *   declarations in one call: two calls under one parent cannot see each other's paths, and
+ *   `routeMap` reports the collision once the tree is assembled.
  * @param declarations - The routes to compile, in any order.
  * @param options - The parent, and what the declarations may name.
  * @returns The routes to place in the parent's own `addChildren` call.
  * @throws {@link Error} Where two declarations share an id, where one names a parent or a layout
- *   nothing provides, where one names a layout a route above it already draws, where parents form a
- *   cycle, where one states a condition and no evaluator was given, or where one states an outlet.
- */
-export declare function compileRoutes<Condition = unknown>(declarations: ReadonlyArray<RouteDeclaration<Condition>>, options: CompileOptions<Condition>): readonly tanstack_d_exports.AnyRoute[];
-//#endregion
-//#region src/reference.d.ts
-/**
- * Points at a route without naming a path, a module or an address.
- */
-/**
- * The parameters a route names where its reference states none.
- */
-type AnyParams = Readonly<Record<string, string>>;
-/**
- * Points at a route by the id it was declared under, carrying the parameters its path names.
- *
- * @remarks
- *   Stated structurally rather than imported, so a plugin SDK's own reference type satisfies it
- *   without this package depending on that SDK. A reference carries no path, because the path is
- *   whoever composed the application's to choose and a link written against one would move when
- *   they re-placed the route.
- *   The parameters live in the type alone. Nothing reads `~types` at run time, and it is there so
- *   a link to a route filling `id` is refused where the route names `invoice`.
- */
-interface RouteRef<Params extends AnyParams = AnyParams> {
-  /**
-   * The parameters, in the type alone.
-   */
-  readonly "~types"?: {
-    /**
-     * The parameters the route's path names, which a link fills.
-     */
-    readonly params: Params;
-  };
-  /**
-   * The full id the route was declared under.
-   */
-  readonly id: string;
-}
-/**
- * Points at a route, either by a reference or by the bare id one carries.
+ *   nothing provides, where one names a layout a route above it already renders, where parents form
+ *   a cycle, where one states a condition and no evaluator was given, or where one states an
+ *   outlet.
  */
-type RouteTarget<Params extends AnyParams = AnyParams> = RouteRef<Params> | string;
+export declare function compileRoutes<Condition = unknown, Context = unknown>(declarations: ReadonlyArray<RouteDeclaration<Condition>>, options: CompileOptions<Condition, Context>): readonly AnyRoute$1[];
 //#endregion
 //#region src/declared.d.ts
 /**
@@ -252,51 +302,68 @@ type RouteTarget<Params extends AnyParams = AnyParams> = RouteRef<Params> | stri
  */
 interface MatchedRoute {
   /**
-   * The data the route was given to carry, which the library hands back untouched.
+   * The static data the route was created with, which the library returns untouched.
    */
   readonly staticData: object;
 }
 /**
- * Reads the id and the menu entry a matched route carries, or nothing where it carries neither.
+ * Reads the id and the menu entry a matched route stores, or nothing where it stores neither.
  *
  * @remarks
- *   A route carries its id in `staticData`, which is where the library keeps whatever a route wants
- *   to carry. The compiler writes it for a route built from a declaration and `namedRoute` writes
- *   it for one written in code, so a menu, a breadcrumb or a telemetry hook reads what it needs off
- *   the match either way. The shape is checked rather than trusted, because `staticData` is untyped
- *   by design and a route may carry anything under the same name. The checked object itself is
- *   returned, so every read of one route gives one reference.
+ *   A route stores its id in `staticData`, the library's place for data a route is created with.
+ *   The compiler writes it for a route built from a declaration, and `namedRoute` writes it for one
+ *   written in code, so a menu, a breadcrumb or a telemetry hook reads the id from the match either
+ *   way. The function checks the shape, because `staticData` is untyped and a route may store
+ *   anything under the same name. It returns the checked object itself, so every read of one route
+ *   returns one reference.
  * @param match - A match, as `useMatches` returns one.
- * @returns The id and the menu entry it carries, or nothing.
+ * @returns The id and the menu entry, or nothing.
  */
 export declare function declaredOf(match: MatchedRoute): DeclaredRoute | undefined;
 /**
- * Reads the name the deepest named route the page is on goes by.
+ * Reads the id of the deepest named route the page is on.
  *
  * @remarks
- *   The deepest match rather than the first, because a named route nested under another is the page
- *   a person is looking at. A page drawn entirely from unnamed routes returns nothing.
- *   The selector returns the object the route carries rather than a copy of it. A route's static
- *   data is fixed once the tree is built, so the reference is the same one until a different route
- *   matches, and a navigation that left the page alone re-renders nothing.
- * @returns The id and the menu entry, or nothing where no matched route carries either.
+ *   The hook reads the deepest match, because a named route nested under another is the page a
+ *   person is looking at. A page rendered from unnamed routes alone returns nothing. The selector
+ *   returns the object the route stores, not a copy. A route's static data is fixed once the tree
+ *   is built, so the reference changes only when a different route matches, and a navigation that
+ *   keeps the page does not render it again.
+ * @returns The id and the menu entry, or nothing where no matched route has an id.
  */
 export declare function useDeclaredRoute(): DeclaredRoute | undefined;
 /**
- * Reads the parameters of the page being drawn, typed by the reference the caller holds.
+ * Reads the parameters of the page being rendered, typed by the reference the caller passes.
  *
  * @remarks
- *   A compiled route is outside the tree an application registered, so `useParams` types against a
- *   tree the route is not in. The parameters are read off the match instead, and the reference
- *   carries their names. This checks at run time that the page really is the route the reference
- *   names before it makes the claim.
- *   The selector returns the id and the parameters alone, which are strings. Structural sharing
- *   compares them, so a navigation that changed neither re-renders nothing.
- * @param to - A reference to the route the calling component draws.
- * @returns The parameters the route's path named.
- * @throws {@link Error} Where the page being drawn is not the route the reference names.
+ *   A compiled route is outside the tree an application registered, so `useParams` types the
+ *   parameters against a tree the route is not in. The hook reads them from the match instead, and
+ *   the reference types them. It checks at run time that the page is the route of the reference,
+ *   and throws where it is not. The selector returns the id and the parameters alone, which are
+ *   strings. Structural sharing compares them, so a navigation that changes neither does not render
+ *   the page again.
+ * @param to - A reference to the route the calling component renders.
+ * @returns The parameters of the route's path.
+ * @throws {@link Error} Where the page being rendered is not the route of the reference.
  */
 export declare function useRouteParams<Params extends AnyParams>(to: RouteRef<Params>): Params;
+/**
+ * Reads the search of the page being rendered, typed by the reference the caller passes.
+ *
+ * @remarks
+ *   A compiled route is outside the tree an application registered, so `useSearch` types the search
+ *   against a tree the route is not in. The hook reads it from the match instead, and the reference
+ *   types it. It checks at run time that the page is the route of the reference, and throws where
+ *   it is not. The value is the match's `_strictSearch`: what the validators of the route and the
+ *   routes above it returned. The hook leaves out the keys of the address that the validators left
+ *   out, so the page never receives a value the validator refused under the validator's type.
+ *   Structural sharing compares the search, so the page does not render again after a navigation
+ *   that left it equal.
+ * @param to - A reference to the route the calling component renders.
+ * @returns The search the route's validator returned.
+ * @throws {@link Error} Where the page being rendered is not the route of the reference.
+ */
+export declare function useRouteSearch<Search>(to: RouteRef<AnyParams, Search>): Search;
 //#endregion
 //#region src/defaults.d.ts
 /**
@@ -313,126 +380,153 @@ export declare function useRouteParams<Params extends AnyParams>(to: RouteRef<Pa
  *   already replaced.
  *   Scroll position is restored on the way back, because a person returning to a list expects to be
  *   where they left it rather than at the top.
+ *   The window is moved in one step, on the way back and to the top of a new page alike. The
+ *   library moves it with the page's own scroll behaviour by default, and the foundation sets that
+ *   to smooth for a link into the page, so a page opened from a scrolled one glided in from above.
  */
 export declare const routerDefaults: {
   readonly defaultPreload: "intent";
   readonly defaultPreloadStaleTime: 0;
   readonly scrollRestoration: true;
+  readonly scrollRestorationBehavior: "instant";
 };
 //#endregion
 //#region src/map.d.ts
 /**
- * Every id anything links by, against the route that draws it.
+ * Maps every id that a link can point at to the route that renders it.
  */
-type RouteMap = ReadonlyMap<string, tanstack_d_exports.AnyRoute>;
+type RouteMap = ReadonlyMap<string, AnyRoute$1>;
 /**
- * Carries a route's name where the library hands it back on every match.
+ * Describes the static data that contains a route's name, which the library returns with every
+ * match.
  */
 interface StaticName {
   /**
-   * The static data the route carries, which `declaredOf` reads the name out of.
+   * The static data of the route, from which `declaredOf` reads the name.
    */
   readonly staticData: Readonly<Record<"declared", DeclaredRoute>>;
 }
 /**
- * Gives a route written in code the id everything else links to it by.
+ * Gives a route written in code the id that everything else links to it by.
  *
  * @remarks
- *   A route carries its id in `staticData`, which is where the compiler writes the id of a route
- *   built from a declaration. One mechanism names both, so a link does not need to know which of
- *   the two it is pointing at.
+ *   A route keeps its id in `staticData`, where the compiler writes the id of a route built from a
+ *   declaration. The same field identifies both kinds, so a link does not need to know which kind
+ *   it points at.
  * @param id - The id to name the route under.
  * @returns The static data to spread into `createRoute`.
  */
 export declare function namedRoute(id: string): StaticName;
 /**
- * Reads every id a tree names, against the route that draws it.
+ * Reads every id of a tree, against the route that renders it.
  *
  * @remarks
- *   Derived from the tree rather than collected beside it, so a route written in code and a route
- *   built from a declaration reach the map the same way. The walk also reports two routes that
- *   serve one URL, which a development build reports as a duplicate route and a production build
- *   resolves by keeping the first and dropping the rest in silence.
+ *   The map derives from the tree and is not collected beside it, so a route written in code and a
+ *   route built from a declaration enter the map the same way. The walk also reports two routes
+ *   that serve one URL. A development build reports them as a duplicate route, and a production
+ *   build keeps the first and drops the rest without a report.
  * @param tree - The assembled tree, as `createRouter` takes it.
  * @returns Every id, against its route.
- * @throws {@link Error} Where two routes carry one id, or where two serve one path under a shared
+ * @throws {@link Error} Where two routes have one id, or where two serve one path under a shared
  *   parent.
  */
-export declare function routeMap(tree: tanstack_d_exports.AnyRoute): RouteMap;
+export declare function routeMap(tree: AnyRoute$1): RouteMap;
 //#endregion
 //#region src/href.d.ts
 /**
- * Resolves a declared id to a path, with the parameters the path names filled in.
+ * Resolves a declared id to a path, with the parameters of the path filled in.
  *
  * @remarks
- *   Throwing is deliberate in all three cases. Interpolation otherwise returns a path with a
- *   literal `$id` still in it, and a route the library has not worked a full path out for yet
- *   returns the site root. A link that navigates somewhere wrong is worse than one that fails where
- *   somebody wrote it.
+ *   The parameters are required where a typed reference's path has a required one, so the compiler
+ *   refuses such a call without them. A bare id takes them at will, and the call throws where one
+ *   is missing.
  * @param map - The map every route is named in.
- * @param to - A reference to the route, or the bare id one carries.
- * @param params - The parameters the path names, typed by the reference where one was given.
+ * @param to - A reference to the route, or the bare id of one.
+ * @param params - The parameters of the path, typed by the reference where one was given.
  * @returns The path, ready to navigate to.
- * @throws {@link Error} Where the map holds no such id, where no router has processed the tree the
- *   route was placed in, or where a parameter the path names is missing.
+ * @throws {@link Error} Where the map contains no such id, where no router has processed the tree
+ *   the route was placed in, or where a parameter of the path is missing.
  */
-export declare function routeHref<Params extends AnyParams>(map: RouteMap, to: RouteTarget<Params>, params?: Params): string;
+export declare function routeHref<Params extends AnyParams>(map: RouteMap, to: RouteTarget<Params>, ...params: ParamsArgument<Params>): string;
 /**
  * Reads the map every route is named in, from the router's own context.
  *
  * @remarks
- *   The map reaches a component through the router's own context rather than a provider of this
- *   package's own, so an application mounts nothing extra to make a link by id work.
- *   Take the map rather than a resolved path where the route is chosen after the render: a hook
- *   cannot run inside an event handler, and `routeHref` can.
+ *   The router's own context passes the map to a component, so an application mounts no provider
+ *   of this package's own to make a link by id work. Where the route is chosen after the render,
+ *   pass the map to `routeHref` inside the event handler, because a hook cannot run there.
  * @returns Every id the router knows, against the route that serves it.
  * @throws {@link Error} Where the router was built without one.
  */
 export declare function useRouteMap(): RouteMap;
 /**
- * Resolves a reference to a path, through the map the router context holds.
+ * Resolves a reference to a path, through the map in the router context.
  *
  * @remarks
  *   A hook, so the route has to be known while the component renders. Use `useRouteMap` where the
- *   route is chosen later, such as in the handler of a row a person clicked.
- * @param to - A reference to the route, or the bare id one carries.
- * @param params - The parameters the path names, typed by the reference where one was given.
+ *   route is chosen later, such as in the handler of a row a person clicked. The parameters are
+ *   required as `routeHref` requires them.
+ * @param to - A reference to the route, or the bare id of one.
+ * @param params - The parameters of the path, typed by the reference where one was given.
  * @returns The path, ready to navigate to.
- * @throws {@link Error} Where no map is in the router context, where it holds no such id, or where
- *   a parameter the path names is missing.
+ * @throws {@link Error} Where no map is in the router context, where the map contains no such id,
+ *   or where a parameter of the path is missing.
  */
-export declare function useRouteHref<Params extends AnyParams>(to: RouteTarget<Params>, params?: Params): string;
+export declare function useRouteHref<Params extends AnyParams>(to: RouteTarget<Params>, ...params: ParamsArgument<Params>): string;
 //#endregion
 //#region src/link.d.ts
 /**
- * Describes a link to a declared route.
- *
- * @remarks
- *   Everything the library's own `Link` takes passes through, so a declared link is styled,
- *   labelled and given an active state the way any other link is. Only `to` and `params` are
- *   restated, because a declared id is not a path the compiler knows.
+ * Describes the props of a link other than its parameters.
  */
-type RouteLinkProps<Params extends AnyParams = AnyParams> = {
+type LinkProps<Params extends AnyParams, Search> = {
   /**
-   * The parameters the route's path names, typed by the reference where one was given.
+   * The search to open the route with, typed by the reference where one was given.
    */
-  readonly params?: Params | undefined;
+  readonly search?: NoInfer<Search> | undefined;
   /**
-   * A reference to the route, or the bare id one carries.
+   * A reference to the route, or the bare id of one.
    */
-  readonly to: RouteTarget<Params>;
-} & Omit<ComponentProps<typeof tanstack_d_exports.Link>, "params" | "to">;
+  readonly to: RouteTarget<Params, Search>;
+} & Omit<ComponentProps<typeof Link>, "params" | "search" | "to">;
+/**
+ * Describes the `params` prop of a link: required where the reference's path has a required
+ * parameter, and optional otherwise.
+ */
+type ParamsProp<Params extends AnyParams> = RequiresParams<Params> extends true ? {
+  /**
+   * The parameters of the route's path, typed by the reference.
+   */
+  readonly params: Params;
+} : {
+  /**
+   * The parameters of the route's path, typed by the reference where one was given.
+   */
+  readonly params?: Params | undefined;
+};
+/**
+ * Describes a link to a declared route.
+ *
+ * @remarks
+ *   Everything the library's own `Link` takes passes through, so a declared link is styled,
+ *   labelled and given an active state the way any other link is. Only `to`, `params` and `search`
+ *   are restated, because a declared id is not a path the compiler knows. The reference types the
+ *   parameters and the search, so a link without a required parameter, and a search that the
+ *   route's validator does not return, fail to compile.
+ */
+type RouteLinkProps<Params extends AnyParams = AnyParams, Search = unknown> = LinkProps<Params, Search> & ParamsProp<Params>;
 /**
  * Links to a route by the id a manifest declared it under.
  *
  * @remarks
  *   A declared route is outside the tree an application registered, so `Link` refuses its path at
- *   compile time. This resolves the id at run time and hands the library a plain string, which is
- *   the one place in this package where a path is not checked by the compiler.
- * @param props - The declared id, its parameters, and whatever else the library's `Link` takes.
+ *   compile time. This resolves the id at run time and passes the library a plain string, which is
+ *   the one place in this package where the compiler does not check a path. The search passes to
+ *   the library's `Link` beside the path.
+ * @param props - The declared id, its parameters, its search, and whatever else the library's
+ *   `Link` takes.
  * @returns An anchor to the resolved path.
  */
-export declare function RouteLink<Params extends AnyParams>({ params, to, ...rest }: RouteLinkProps<Params>): ReactNode;
+export declare function RouteLink<Params extends AnyParams, Search>(props: RouteLinkProps<Params, Search>): ReactNode;
 //#endregion
 //#region src/options.d.ts
 /**
@@ -473,7 +567,7 @@ export declare function routerOptions<Context extends object>(context: Context):
 //#endregion
 //#region src/root.d.ts
 /**
- * Builds a root route whose context holds whatever the application states and the route map.
+ * Builds a root route whose context contains whatever the application states and the route map.
  *
  * @remarks
  *   Calling the library's `createRootRoute` instead leaves the context typed as empty, and the
@@ -481,9 +575,6 @@ export declare function routerOptions<Context extends object>(context: Context):
  *   then names the router rather than the root, which is the file that has to change.
  * @returns The root route factory, to call with the route's own options.
  */
-export declare function createAppRootRoute<Context extends object = RoutesContext>(): ReturnType<typeof tanstack_d_exports.createRootRouteWithContext<Context>>;
-declare namespace index_d_exports {
-  export { AnyParams, AppRouterOptions, CompileOptions, DeclaredRoute, Evaluate, LayoutProps, LazyPage, MatchedRoute, RouteDeclaration, RouteLink, RouteLinkProps, RouteMap, RouteRef, RouteTarget, RoutesContext, SearchValidator, StaticName, compileRoutes, createAppRootRoute, declaredOf, namedRoute, routeHref, routeMap, routerDefaults, routerOptions, useDeclaredRoute, useRouteHref, useRouteMap, useRouteParams };
-}
+export declare function createAppRootRoute<Context extends object = RoutesContext>(): ReturnType<typeof createRootRouteWithContext<Context>>;
 //#endregion
-export type { AnyParams, AppRouterOptions, CompileOptions, DeclaredRoute, Evaluate, LayoutProps, LazyPage, MatchedRoute, RouteDeclaration, RouteLinkProps, RouteMap, RouteRef, RouteTarget, RoutesContext, SearchValidator, StaticName };
+export { type AnyParams, type AnyRoute, type AnyRouter, type AppRouterOptions, type CompileOptions, type DeclaredRoute, type EnteredLocation, type ErrorComponentProps, type ErrorRouteComponent, type Evaluate, type LayoutProps, type LazyPage, type MatchedRoute, Navigate, type NotFoundRouteProps, Outlet, type RouteDeclaration, type RouteLinkProps, type RouteLoader, type RouteLoaderArgs, type RouteMap, type RouteRef, type RouteTarget, RouterContextProvider, type RouterHistory, RouterProvider, type RoutesContext, type SearchValidator, type StaticName, createLink, createMemoryHistory, createRootRoute, createRoute, createRouter, isNotFound, isRedirect, notFound, redirect, useChildMatches, useLinkProps, useLocation, useMatches, useNavigate, useRouteContext, useRouter, useRouterState };