@echojs-ecosystem/router 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+<div align="center">
+
+# @echojs-ecosystem/router
+
+**Typed SPA routing — routes as signal-backed objects, not components.**
+
+[![npm](https://img.shields.io/npm/v/@echojs-ecosystem/router)](https://www.npmjs.com/package/@echojs-ecosystem/router)
+[![docs](https://img.shields.io/badge/docs-echojs.dev-blue)](https://echojs.dev/docs/packages/router)
+
+</div>
+
+---
+
+Programmatic router for EchoJS. Syncs **URL ↔ route state** with guards, lazy loading, layouts, and Hyperdom bindings (`Link`, `NavLink`).
+
+## Features
+
+- **Route views** — `createRouteView`, `createLayoutView`, `createLazyRouteView`
+- **Signal-backed state** — `$path`, `$params`, `$query`, `$activePage`, `$pending`, `$error`
+- **Guards & redirects** — `authorizationGuard`, `guardRoute`, `redirect`, `chainRoute`
+- **History adapters** — `browser`, `hash`, `memory`, or custom
+- **Hyperdom** — `@echojs-ecosystem/router/hyperdom` for `Link`, `NavLink`, `createRouter`
+
+## Install
+
+```bash
+npm install @echojs-ecosystem/router @echojs-ecosystem/reactivity @echojs-ecosystem/hyperdom
+```
+
+## Quick start
+
+```ts
+import { createRouteView, createRoutes, createRouter } from "@echojs-ecosystem/router";
+
+const homePage = createRouteView({
+  name: "home",
+  view: () => "Home",
+});
+
+const router = createRouter({
+  history: "browser",
+  routes: createRoutes([{ path: "/", name: "home", routeView: homePage }]),
+});
+
+router.start();
+router.go("/");
+```
+
+### Hyperdom
+
+```ts
+import { createRouter, NavLink } from "@echojs-ecosystem/router/hyperdom";
+
+const router = createRouter({ history: "browser", routes });
+router.start();
+
+NavLink({ to: homePage, activeClass: "active", children: "Home" });
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `createRouter` | Router instance |
+| `createRoutes` | Route tree builder |
+| `createRouteView` / `createLayoutView` | Page & layout views |
+| `createLazyRouteView` | Code-split routes |
+| `createRoute` | Legacy imperative routes |
+| `guardRoute`, `redirect`, `chainRoute` | Route operators |
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| [`@echojs-ecosystem/url-state`](https://www.npmjs.com/package/@echojs-ecosystem/url-state) | Typed search params |
+| [`@echojs-ecosystem/framework`](https://www.npmjs.com/package/@echojs-ecosystem/framework) | App bootstrap with router provider |
+
+## Documentation
+
+[echojs.dev/docs/packages/router](https://echojs.dev/docs/packages/router)

package/dist/index.d.ts

@@ -0,0 +1,455 @@
+import { ReadonlySignal } from '@echojs-ecosystem/reactivity';
+import { Child } from '@echojs-ecosystem/hyperdom';
+import { RouterBoundQueryParams } from '@echojs-ecosystem/url-state';
+
+type RouterHistoryKind = "browser" | "hash" | "memory";
+type MemoryHistoryConfig = {
+    readonly type: "memory";
+    readonly initial?: string;
+};
+type RouterHistoryConfig = RouterHistoryKind | MemoryHistoryConfig | RouterHistory;
+declare const resolveHistory: (config: RouterHistoryConfig) => RouterHistory;
+
+type RouteViewConfig<P extends string = string, N extends string = string, TRouteView = AnyPage> = {
+    readonly path: P;
+    readonly name: N;
+    readonly routeView: TRouteView;
+};
+type RedirectConfig<P extends string = string, N extends string = string, TRoute = AnyRoute> = {
+    readonly path: P;
+    readonly name: N;
+    readonly route: TRoute;
+    readonly children?: readonly RouteTreeNode[];
+};
+type LayoutViewConfig<P extends string = string, N extends string = string, TLayoutView extends LayoutPage = LayoutPage> = {
+    readonly path: P;
+    readonly name: N;
+    readonly layoutView: TLayoutView;
+    readonly children: readonly RouteTreeNode[];
+};
+/** Discriminated route-tree node for `createRoutes()`. */
+type RouteTreeNode = RouteViewConfig | LayoutViewConfig | RedirectConfig;
+/** @deprecated Use RouteTreeNode */
+type RouteTreeInput = RouteTreeNode;
+type JoinPaths<Parent extends string, Child extends string> = Child extends "/" | "" ? Parent : Child extends `/${infer Rest}` ? Rest extends "" ? "/" : `/${Rest}` : Parent extends "/" ? `/${Child}` : `${Parent}/${Child}`;
+type EntryPathsFrom<Parent extends string, Entries extends readonly RouteTreeBranch[]> = Entries[number] extends infer Entry ? Entry extends {
+    path: infer P extends string;
+} ? JoinPaths<Parent, P> | (Entry extends {
+    children: infer C extends readonly RouteTreeBranch[];
+} ? EntryPathsFrom<JoinPaths<Parent, P>, C> : never) : never : never;
+type EntryFullPath<Entry> = Entry extends {
+    path: infer P extends string;
+} ? Entry extends {
+    children: infer C extends readonly RouteTreeBranch[];
+} ? JoinPaths<"/", P> | EntryPathsFrom<JoinPaths<"/", P>, C> : JoinPaths<"/", P> : never;
+type RouteTreeBranch = RouteTreeEntry | RouteTreeNode;
+type CollectRoutePaths<TRoutes extends readonly RouteTreeBranch[]> = TRoutes[number] extends infer Entry ? EntryFullPath<Entry> : never;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type ConfigNamed<E, T> = E extends {
+    readonly name: infer N extends string;
+} ? string extends N ? Record<string, never> : {
+    readonly [K in N]: T;
+} : Record<string, never>;
+type RouteViewNamed<E> = E extends {
+    routeView: infer V extends AnyRoute;
+} ? ConfigNamed<E, V> : Record<string, never>;
+type LayoutViewNamed<E> = E extends {
+    layoutView: infer L extends AnyRoute;
+} ? ConfigNamed<E, L> : Record<string, never>;
+type RedirectRouteNamed<E> = E extends {
+    route: infer R extends AnyRoute;
+} ? ConfigNamed<E, R> : Record<string, never>;
+type EntryNames<E> = RouteViewNamed<E> & LayoutViewNamed<E> & RedirectRouteNamed<E>;
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
+type EntryNamesDeep<E, D extends number> = D extends 0 ? Record<string, never> : EntryNames<E> & (E extends {
+    children: readonly RouteTreeBranch[];
+} ? UnionToIntersection<EntryNamesDeep<E["children"][number], PrevDepth[D]>> : Record<string, never>);
+type NamedRoutesFromTree<TRoutes extends readonly RouteTreeBranch[]> = UnionToIntersection<EntryNamesDeep<TRoutes[number], 16>>;
+type CollectNamedRoutes<TRoutes> = TRoutes extends readonly RouteTreeBranch[] ? NamedRoutesFromTree<TRoutes> extends infer R ? keyof R extends never ? Record<string, never> : R : Record<string, never> : Record<string, never>;
+type RouteViewEntry<P extends string = string, N extends string = string, TRouteView = AnyPage> = RouteViewConfig<P, N, TRouteView>;
+type LayoutViewEntry<P extends string = string, N extends string = string, TLayoutView extends LayoutPage = LayoutPage> = LayoutViewConfig<P, N, TLayoutView>;
+type RedirectRouteEntry<P extends string = string, N extends string = string, TRoute = AnyRoute> = RedirectConfig<P, N, TRoute>;
+/** @deprecated Use RouteViewEntry */
+type PageRouteEntry<P extends string = string, N extends string = string, TPage = AnyPage> = RouteViewEntry<P, N, TPage>;
+/** @deprecated Use LayoutViewEntry */
+type LayoutRouteEntry<P extends string = string, N extends string = string> = LayoutViewEntry<P, N>;
+type RouteTreeEntry<P extends string = string, N extends string = string> = RouteViewEntry<P, N, AnyPage> | RedirectRouteEntry<P, N> | LayoutViewEntry<P, N>;
+
+type RouteEvent<T> = {
+    subscribe(listener: (payload: T) => void): () => void;
+};
+type RouteOpenedPayload<Params, Query> = {
+    params: Params;
+    query: Query;
+    path: string;
+    fullPath: string;
+};
+type GoOptions<Query> = {
+    query?: Query;
+    replace?: boolean;
+};
+/** @deprecated Use GoOptions */
+type OpenOptions<Query> = GoOptions<Query>;
+type NamedRoute<Name extends string, Params = Record<string, never>, Query = Record<string, never>> = Route<Params, Query> & {
+    readonly name: Name;
+};
+type NamedPage<Name extends string, Params = Record<string, never>, Query = Record<string, never>, Data = void> = Page<Params, Query, Data> & {
+    readonly name: Name;
+};
+type Route<Params = Record<string, never>, Query = Record<string, never>> = {
+    readonly name?: string;
+    readonly $isOpened: ReadonlySignal<boolean>;
+    readonly $params: ReadonlySignal<Params | null>;
+    readonly $query: ReadonlySignal<Query>;
+    readonly $path: ReadonlySignal<string | null>;
+    readonly $fullPath: ReadonlySignal<string | null>;
+    go(...args: keyof Params extends never ? [params?: Params, options?: GoOptions<Query>] : [params: Params, options?: GoOptions<Query>]): void;
+    /** @deprecated Alias for `go()` */
+    open(...args: keyof Params extends never ? [params?: Params, options?: GoOptions<Query>] : [params: Params, options?: GoOptions<Query>]): void;
+    close(): void;
+    readonly opened: RouteEvent<RouteOpenedPayload<Params, Query>>;
+    readonly closed: RouteEvent<void>;
+};
+type PageLoaderContext<Params, Query> = {
+    params: Params;
+    query: Query;
+    navigationId?: number;
+};
+type RouteViewContext<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = {
+    params: Params;
+    query: Query;
+    outlet: () => Child;
+    data: Data | null;
+    /** Set when the view is used as a router-level or per-route error UI. */
+    error?: unknown;
+};
+/** @deprecated Use RouteViewContext */
+type PageRenderContext<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = RouteViewContext<Params, Query, Data>;
+type RouteView<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = (context: RouteViewContext<Params, Query, Data>) => unknown;
+/** @deprecated Use RouteView */
+type PageComponent<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = RouteView<Params, Query, Data>;
+type RouteLoadingView = (context: {
+    params: Record<string, unknown>;
+    query: Record<string, unknown>;
+}) => unknown;
+/** @deprecated Use RouteLoadingView */
+type PageViewComponent = RouteLoadingView;
+type RouteErrorView = (context: {
+    error: unknown;
+    params: Record<string, unknown>;
+    query: Record<string, unknown>;
+}) => unknown;
+/** @deprecated Use RouteErrorView */
+type PageErrorComponent = RouteErrorView;
+type Page<Params = Record<string, never>, Query = Record<string, never>, Data = void> = Route<Params, Query> & {
+    readonly $pending: ReadonlySignal<boolean>;
+    readonly $error: ReadonlySignal<unknown | null>;
+    readonly $data: ReadonlySignal<Data | null>;
+    readonly beforeLoad?: (ctx: PageLoaderContext<Params, Query>) => Data | Promise<Data>;
+    /** @deprecated Use `beforeLoad` */
+    readonly loader?: (ctx: PageLoaderContext<Params, Query>) => Data | Promise<Data>;
+    readonly loadingView?: RouteLoadingView;
+    readonly errorView?: RouteErrorView;
+    replace(...args: keyof Params extends never ? [params?: Params, options?: GoOptions<Query>] : [params: Params, options?: GoOptions<Query>]): void;
+    resolve(params?: Params, options?: {
+        query?: Record<string, unknown>;
+    }): string;
+    isActive(): boolean;
+    preload?(): void;
+};
+type PageViewRenderContext<Params = Record<string, unknown>, Query = Record<string, unknown>> = Omit<PageRenderContext<Params, Query, void>, "data">;
+/** @deprecated Use PageComponent */
+type PageViewRenderer<Params = Record<string, unknown>, Query = Record<string, unknown>> = (context: PageViewRenderContext<Params, Query>) => unknown;
+
+/** @deprecated Use RouteTreeEntry */
+type RouterRouteDefinition = RouteTreeEntry;
+
+type LayoutPage = AnyPage & {
+    readonly __layout?: unique symbol;
+};
+type RouteConfig = {
+    path: string;
+    route: AnyRoute;
+    children?: RouteConfig[];
+};
+type RouterHistory = {
+    getLocation(): string;
+    push(path: string): void;
+    replace(path: string): void;
+    listen(callback: (path: string) => void): () => void;
+    back(): void;
+    forward(): void;
+};
+type AuthorizationGuardRedirectContext = {
+    readonly pathname: string;
+    readonly authorized: boolean;
+};
+/** Resolves a redirect path when the user must leave the current URL. */
+type AuthorizationGuardRedirect<Paths extends string = string> = (context: AuthorizationGuardRedirectContext) => Paths;
+type AuthorizationGuardRedirectTarget<Paths extends string = string> = Paths | AuthorizationGuardRedirect<Paths>;
+type AuthorizationGuardOptions<Paths extends string = string> = {
+    isAuthorized: () => boolean;
+    allowedUnauthorizedPaths: readonly Paths[];
+    allowedAuthorizedPaths?: readonly Paths[];
+    redirectTo?: AuthorizationGuardRedirectTarget<Paths>;
+    redirectWhenAuthorized?: AuthorizationGuardRedirectTarget<Paths>;
+};
+type CreateRouterOptions<TRoutes extends readonly RouteTreeNode[] = readonly RouteTreeNode[]> = {
+    history: RouterHistoryConfig;
+    routes: TRoutes;
+    authorizationGuard?: AuthorizationGuardOptions<CollectRoutePaths<TRoutes>>;
+    loadingView?: RouteLoadingView | AnyPage;
+    errorView?: RouteErrorView | AnyPage;
+    notFoundView?: RouterNotFoundView | AnyPage;
+};
+type RouterNotFoundView = (context: RouteViewContext<Record<string, unknown>, Record<string, unknown>, void>) => unknown;
+/** @deprecated Use RouterNotFoundView */
+type RouterNotFoundComponent = RouterNotFoundView;
+type AnyRoute = Route<any, any>;
+type AnyPage = Page<any, any, any>;
+type RouterViewComponent = () => unknown;
+/** Default shape of `router.routes` when the route tree is not inferred. */
+type RouterRoutes = Readonly<Record<string, AnyRoute>>;
+type RouterBase = {
+    readonly $path: ReadonlySignal<string>;
+    readonly $query: ReadonlySignal<Record<string, string>>;
+    readonly $fullPath: ReadonlySignal<string>;
+    readonly $activeRoute: ReadonlySignal<AnyRoute | null>;
+    readonly $activePage: ReadonlySignal<AnyPage | null>;
+    readonly $activeRoutes: ReadonlySignal<AnyRoute[]>;
+    readonly $matched: ReadonlySignal<AnyRoute[]>;
+    readonly $params: ReadonlySignal<Record<string, string>>;
+    readonly $pending: ReadonlySignal<boolean>;
+    readonly $error: ReadonlySignal<unknown | null>;
+    readonly View: RouterViewComponent;
+    start(): void;
+    stop(): void;
+    go(path: string, options?: {
+        replace?: boolean;
+    }): void;
+    /** @deprecated Use `go()` */
+    navigate(path: string, options?: {
+        replace?: boolean;
+    }): void;
+    replace(path: string): void;
+    back(): void;
+    forward(): void;
+    reload(): void;
+    resolve(route: AnyRoute, params?: Record<string, string>, options?: {
+        query?: Record<string, unknown>;
+    }): string;
+    isActive(route: AnyRoute): boolean;
+    view(): RouterViewComponent;
+    closeRoute(route: AnyRoute): void;
+};
+type Router<TRoutes extends RouterRoutes = RouterRoutes> = RouterBase & {
+    readonly routes: TRoutes;
+};
+type MatchResult = {
+    matched: boolean;
+    params: Record<string, string>;
+};
+type ChainedRoute<Params, Query, Result = void> = {
+    readonly $isOpened: ReadonlySignal<boolean>;
+    readonly $pending: ReadonlySignal<boolean>;
+    readonly $error: ReadonlySignal<unknown | null>;
+    readonly $params: ReadonlySignal<Params | null>;
+    readonly $query: ReadonlySignal<Query>;
+    readonly $result: ReadonlySignal<Result | null>;
+};
+
+declare const createRoute: <const Name extends string, Params = Record<string, never>, Query = Record<string, never>>(name: Name) => NamedRoute<Name, Params, Query>;
+
+type FlatRouteEntry = {
+    path: string;
+    route: AnyRoute;
+    parent: FlatRouteEntry | null;
+};
+declare const flattenRouteTree: (configs: RouteConfig[], parentPath?: string, parent?: FlatRouteEntry | null) => FlatRouteEntry[];
+type RouteMatchChain = {
+    leaf: FlatRouteEntry;
+    chain: FlatRouteEntry[];
+    leafParams: Record<string, string>;
+};
+declare const matchRouteChain: (pathname: string, flatRoutes: FlatRouteEntry[]) => RouteMatchChain | null;
+
+type LazyRouteViewModule<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = {
+    default: RouteView<Params, Query, Data>;
+};
+type LazyRouteViewLoader<Params = Record<string, unknown>, Query = Record<string, unknown>, Data = void> = () => Promise<LazyRouteViewModule<Params, Query, Data>>;
+declare const isLazyRouteView: (page: AnyPage) => boolean;
+
+type BeforeLoadContext<Params, Query> = PageLoaderContext<Params, Query> & {
+    navigationId: number;
+};
+declare const isPage: (value: Route<any, any>) => value is Page<any, any, any>;
+declare const isLayoutPage: (value: Route<any, any>) => value is Page<any, any, any>;
+declare const assertPage: (value: Route<any, any>, label?: string) => Page;
+type CreateRouteViewOptions<Params, Query, Data> = {
+    name?: string;
+    view?: RouteView<Params, Query, Data>;
+    viewLoader?: LazyRouteViewLoader<Params, Query, Data>;
+    beforeLoad?: (ctx: BeforeLoadContext<Params, Query>) => Data | Promise<Data>;
+    /** @deprecated Use `beforeLoad` */
+    loader?: (ctx: PageLoaderContext<Params, Query>) => Data | Promise<Data>;
+    loadingView?: RouteLoadingView;
+    errorView?: RouteErrorView;
+};
+
+type RouteViewOptionsConstraint = CreateRouteViewOptions<unknown, unknown, unknown> & {
+    readonly name: string;
+};
+type RouteViewNameFromOptions<O extends RouteViewOptionsConstraint> = O extends {
+    readonly name: infer N extends string;
+} ? string extends N ? never : N : never;
+type RouteViewParamsFromOptions<O extends RouteViewOptionsConstraint> = O extends CreateRouteViewOptions<infer P, unknown, unknown> ? P : Record<string, never>;
+type RouteViewQueryFromOptions<O extends RouteViewOptionsConstraint> = O extends CreateRouteViewOptions<unknown, infer Q, unknown> ? Q : Record<string, never>;
+type RouteViewDataFromOptions<O extends RouteViewOptionsConstraint> = O extends CreateRouteViewOptions<unknown, unknown, infer D> ? D : void;
+
+declare function createRouteView<const O extends RouteViewOptionsConstraint>(options: O): NamedPage<RouteViewNameFromOptions<O>, RouteViewParamsFromOptions<O>, RouteViewQueryFromOptions<O>, RouteViewDataFromOptions<O>>;
+declare function createRouteView<Params = Record<string, never>, Query = Record<string, never>, Data = void>(options: CreateRouteViewOptions<Params, Query, Data> & {
+    readonly name: string;
+}): NamedPage<string, Params, Query, Data>;
+
+type LazyRouteViewOptionsConstraint = {
+    readonly name: string;
+    view: LazyRouteViewLoader<unknown, unknown, unknown>;
+    beforeLoad?: (ctx: BeforeLoadContext<unknown, unknown>) => unknown | Promise<unknown>;
+    loadingView?: CreateRouteViewOptions<unknown, unknown, unknown>["loadingView"];
+    errorView?: CreateRouteViewOptions<unknown, unknown, unknown>["errorView"];
+};
+type LazyRouteViewNameFromOptions<O extends LazyRouteViewOptionsConstraint> = O extends {
+    readonly name: infer N extends string;
+} ? string extends N ? never : N : never;
+type LazyRouteViewParamsFromOptions<O extends LazyRouteViewOptionsConstraint> = O extends {
+    beforeLoad?: (ctx: BeforeLoadContext<infer P, unknown>) => unknown;
+} ? P : Record<string, never>;
+type LazyRouteViewQueryFromOptions<O extends LazyRouteViewOptionsConstraint> = O extends {
+    beforeLoad?: (ctx: BeforeLoadContext<unknown, infer Q>) => unknown;
+} ? Q : Record<string, never>;
+type LazyRouteViewDataFromOptions<O extends LazyRouteViewOptionsConstraint> = O extends {
+    beforeLoad?: (ctx: BeforeLoadContext<unknown, unknown>) => infer D;
+} ? Awaited<D> : void;
+
+type CreateLazyRouteViewOptions<Params = Record<string, never>, Query = Record<string, never>, Data = void> = {
+    name?: string;
+    /** Dynamic import — module must `export default` a route view function. */
+    view: LazyRouteViewLoader<Params, Query, Data>;
+    beforeLoad?: (ctx: BeforeLoadContext<Params, Query>) => Data | Promise<Data>;
+    loadingView?: RouteLoadingView;
+    errorView?: RouteErrorView;
+};
+declare function createLazyRouteView<const O extends LazyRouteViewOptionsConstraint>(options: O): NamedPage<LazyRouteViewNameFromOptions<O>, LazyRouteViewParamsFromOptions<O>, LazyRouteViewQueryFromOptions<O>, LazyRouteViewDataFromOptions<O>>;
+declare function createLazyRouteView<Params = Record<string, never>, Query = Record<string, never>, Data = void>(options: CreateLazyRouteViewOptions<Params, Query, Data> & {
+    readonly name: string;
+}): NamedPage<string, Params, Query, Data>;
+
+type NamedLayoutView<Name extends string, Params = Record<string, never>, Query = Record<string, never>, Data = void> = LayoutPage & NamedPage<Name, Params, Query, Data>;
+declare const createLayoutView: <const O extends RouteViewOptionsConstraint>(options: O) => NamedLayoutView<RouteViewNameFromOptions<O>, RouteViewParamsFromOptions<O>, RouteViewQueryFromOptions<O>, RouteViewDataFromOptions<O>>;
+
+declare const createRouter$1: <const TRoutes extends readonly RouteTreeBranch[]>(options: CreateRouterOptions<TRoutes>) => Router<CollectNamedRoutes<TRoutes>>;
+
+type HyperdomRouter<TRoutes extends Router["routes"] = Router["routes"]> = Omit<Router<TRoutes>, "View"> & {
+    readonly View: () => Child;
+    createQueryParams: RouterBoundQueryParams;
+};
+declare const createRouter: <const TRoutes extends readonly RouteTreeBranch[]>(options: CreateRouterOptions<TRoutes>) => HyperdomRouter<CollectNamedRoutes<TRoutes>>;
+
+type QueryPrimitive = string | number | boolean;
+type QueryValue = QueryPrimitive | QueryPrimitive[] | null | undefined;
+type QueryRecord = Record<string, QueryValue>;
+declare const parseQuery: (search: string) => Record<string, string>;
+declare const parseQueryValues: (search: string) => Record<string, string | string[]>;
+declare const stringifyQuery: (query: QueryRecord) => string;
+
+type LinkProps<Params = Record<string, string>, Query = QueryRecord> = {
+    to?: Route<Params, Query>;
+    href?: string;
+    params?: Params;
+    query?: Query;
+    replace?: boolean;
+    children?: Child;
+};
+declare const Link: <Params = Record<string, string>, Query = QueryRecord>(props: LinkProps<Params, Query>) => Child;
+
+type NavLinkProps<Params = Record<string, string>, Query = QueryRecord> = LinkProps<Params, Query> & {
+    activeClass?: string;
+    class?: string;
+};
+declare const NavLink: <Params = Record<string, string>, Query = QueryRecord>(props: NavLinkProps<Params, Query>) => Child;
+
+declare const ROUTER_KEY: unique symbol;
+type RouterLike = Pick<Router, "View" | "start" | "stop">;
+type RouterProviderHost = {
+    provide?<T>(key: symbol, value: T): unknown;
+};
+type RouterProviderOptions = {
+    /** @default true */
+    autoStart?: boolean;
+};
+/** Provider shape accepted by `createEchoApp().use(...)`. */
+type RouterProvider = {
+    name: "router";
+    setup: (app: RouterProviderHost) => void;
+    resolveRoot: () => Child;
+};
+/** @deprecated Use {@link RouterProvider} */
+type RouterPlugin = RouterProvider;
+declare const isRouterLike: (value: unknown) => value is RouterLike;
+declare const createRouterProvider: (router: RouterLike, options?: RouterProviderOptions) => RouterProvider;
+/** @deprecated Use {@link createRouterProvider} */
+declare const routerPlugin: (router: RouterLike, options?: RouterProviderOptions) => RouterProvider;
+
+/**
+ * Builds a typed route tree for `createRouter({ routes })`.
+ * Use `routeView`, `layoutView`, and `route` (redirect) on each entry.
+ */
+declare function createRoutes<const TRoutes extends readonly RouteTreeNode[]>(routes: TRoutes): TRoutes;
+type RoutesFromConfig<TRoutes extends readonly RouteTreeNode[]> = CollectNamedRoutes<TRoutes>;
+
+declare const normalizePathname: (pathname: string) => string;
+declare const joinRoutePaths: (parentPath: string, childPath: string) => string;
+declare const matchPath: (pattern: string, pathname: string) => MatchResult;
+declare const buildPath: (pattern: string, params?: Record<string, string>) => string;
+declare const splitLocation: (location: string) => {
+    pathname: string;
+    search: string;
+};
+declare const joinLocation: (pathname: string, search: string) => string;
+
+type NamedRoutesMap = Readonly<Record<string, AnyRoute>>;
+/** Flat `router.routes` keyed by route config `name` (not URL segments). */
+declare const buildNamedRoutes: (entries: readonly RouteTreeEntry[]) => NamedRoutesMap;
+
+declare const createBrowserHistory: () => RouterHistory;
+
+declare const createMemoryHistory: (initialPath?: string) => RouterHistory;
+
+declare const createHashHistory: () => RouterHistory;
+
+type GuardRouteOptions = {
+    route: Route<any, any>;
+    canOpen: () => boolean;
+    otherwise: Route<any, any>;
+};
+
+declare const guardRoute: (options: GuardRouteOptions) => (() => void);
+
+type RedirectOptions<FromParams = Record<string, unknown>, FromQuery = Record<string, unknown>, ToParams = FromParams, ToQuery = FromQuery> = {
+    from: Route<FromParams, FromQuery>;
+    to: Route<ToParams, ToQuery>;
+    mapParams?: (params: FromParams) => ToParams;
+    mapQuery?: (query: FromQuery) => ToQuery;
+};
+declare const redirect: <FromParams = Record<string, unknown>, FromQuery = Record<string, unknown>, ToParams = FromParams, ToQuery = FromQuery>(options: RedirectOptions<FromParams, FromQuery, ToParams, ToQuery>) => (() => void);
+
+type ChainRouteOptions<Params, Query, Result = void> = {
+    route: Route<Params, Query>;
+    beforeOpen: (context: {
+        params: Params;
+        query: Query;
+    }) => Result | Promise<Result>;
+};
+declare const chainRoute: <Params, Query, Result = void>(options: ChainRouteOptions<Params, Query, Result>) => ChainedRoute<Params, Query, Result>;
+
+export { type AnyPage, type AuthorizationGuardOptions, type AuthorizationGuardRedirect, type AuthorizationGuardRedirectContext, type AuthorizationGuardRedirectTarget, type BeforeLoadContext, type ChainRouteOptions, type ChainedRoute, type CollectNamedRoutes, type CollectRoutePaths, type CreateLazyRouteViewOptions, type CreateRouteViewOptions, type CreateRouterOptions, type GoOptions, type GuardRouteOptions, type HyperdomRouter, type JoinPaths, type LayoutPage, type LayoutRouteEntry, type LayoutViewConfig, type LayoutViewEntry, type LazyRouteViewLoader, type LazyRouteViewModule, Link, type LinkProps, type MatchResult, type MemoryHistoryConfig, type NamedLayoutView, type NamedPage, type NamedRoute, type NamedRoutesMap, NavLink, type NavLinkProps, type OpenOptions, type Page, type PageComponent, type PageErrorComponent, type PageLoaderContext, type PageRenderContext, type PageRouteEntry, type PageViewComponent, type PageViewRenderer, ROUTER_KEY, type RedirectConfig, type RedirectOptions, type RedirectRouteEntry, type Route, type RouteConfig, type RouteErrorView, type RouteEvent, type RouteLoadingView, type RouteOpenedPayload, type RouteTreeBranch, type RouteTreeEntry, type RouteTreeInput, type RouteTreeNode, type RouteView, type RouteViewConfig, type RouteViewContext, type RouteViewEntry, type Router, type RouterBase, type RouterHistory, type RouterHistoryConfig, type RouterHistoryKind, type RouterLike, type RouterNotFoundComponent, type RouterNotFoundView, type RouterPlugin, type RouterProvider, type RouterRouteDefinition, type RouterRoutes, type RouterViewComponent, type RoutesFromConfig, assertPage, buildNamedRoutes, buildPath, chainRoute, createBrowserHistory, createHashHistory, createLayoutView, createLazyRouteView, createMemoryHistory, createRoute, createRouteView, createRouter, createRouter$1 as createRouterCore, createRouterProvider, createRoutes, flattenRouteTree, guardRoute, isLayoutPage, isLazyRouteView, isPage, isRouterLike, joinLocation, joinRoutePaths, matchPath, matchRouteChain, normalizePathname, parseQuery, parseQueryValues, redirect, resolveHistory, routerPlugin, splitLocation, stringifyQuery };