@solidjs/router 1.0.0 → 2.0.0-next.12

package/dist/index.jsx

@@ -1,6 +1,6 @@
 export * from "./routers/index.js";
-export * from "./components.jsx";
 export * from "./lifecycle.js";
-export { useHref, useIsRouting, useLocation, useMatch, useCurrentMatches, useNavigate, useParams, useResolvedPath, useSearchParams, useBeforeLeave, usePreloadRoute, RouterContextObj as RouterContext } from "./routing.js";
+export { useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, usePreloadRoute, useParams, useResolvedPath, useRouteMatches, useSearchParams, RouterContextObj as RouterContext } from "./routing.js";
 export { mergeSearchString as _mergeSearchString } from "./utils.js";
+export { int } from "./paths.js";
 export * from "./data/index.js";

package/dist/lifecycle.d.ts

@@ -1,5 +1,30 @@
-import { BeforeLeaveLifecycle, LocationChange } from "./types.js";
+import type { BeforeLeaveEventArgs, BeforeLeaveLifecycle } from "./types.js";
 export declare function createBeforeLeave(): BeforeLeaveLifecycle;
-export declare function saveCurrentDepth(): void;
-export declare function keepDepth(state: any): any;
-export declare function notifyIfNotBlocked(notify: (value?: string | LocationChange) => void, block: (delta: number | null) => boolean): () => void;
+/**
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ *
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ *
+ * @example
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
+ * ```
+ */
+export declare const useBeforeLeave: (listener: (e: BeforeLeaveEventArgs) => void) => void;

package/dist/lifecycle.js

@@ -1,4 +1,5 @@
-import { isServer } from "solid-js/web";
+import { onCleanup } from "solid-js";
+import { useLocation, useNavigate, useRouter } from "./routing.js";
 export function createBeforeLeave() {
     let listeners = new Set();
     function subscribe(listener) {
@@ -38,39 +39,41 @@ export function createBeforeLeave() {
         confirm
     };
 }
-// The following supports browser initiated blocking (eg back/forward)
-let depth;
-export function saveCurrentDepth() {
-    if (!window.history.state || window.history.state._depth == null) {
-        window.history.replaceState({ ...window.history.state, _depth: window.history.length - 1 }, "");
-    }
-    depth = window.history.state._depth;
-}
-if (!isServer) {
-    saveCurrentDepth();
-}
-export function keepDepth(state) {
-    return {
-        ...state,
-        _depth: window.history.state && window.history.state._depth
-    };
-}
-export function notifyIfNotBlocked(notify, block) {
-    let ignore = false;
-    return () => {
-        const prevDepth = depth;
-        saveCurrentDepth();
-        const delta = prevDepth == null ? null : depth - prevDepth;
-        if (ignore) {
-            ignore = false;
-            return;
-        }
-        if (delta && block(delta)) {
-            ignore = true;
-            window.history.go(-delta);
-        }
-        else {
-            notify();
-        }
-    };
-}
+/**
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ *
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ *
+ * @example
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
+ * ```
+ */
+export const useBeforeLeave = (listener) => {
+    // Installing the guard here (instead of eagerly in the router/history) keeps
+    // all of createBeforeLeave tree-shakeable for apps that never block leaves.
+    const slot = useRouter().beforeLeave;
+    const s = (slot.current || (slot.current = createBeforeLeave())).subscribe({
+        listener,
+        location: useLocation(),
+        navigate: useNavigate()
+    });
+    onCleanup(s);
+};

package/dist/paths.d.ts

@@ -0,0 +1,117 @@
+import type { Params, RouteDefinition, SearchParams, SetSearchParams, StandardSchemaV1, TypedPath, TypedSearchPath } from "./types.js";
+declare const FILTER_TYPE: unique symbol;
+/**
+ * A match filter that also declares the TypeScript type accepted for the
+ * param at `paths` callsites (the runtime param remains a string).
+ */
+export interface TypedMatchFilter<T> {
+    (s: string): boolean;
+    readonly [FILTER_TYPE]: T;
+}
+/** Matches integer segments; types the param as `number` in the path proxy. */
+export declare const int: TypedMatchFilter<number>;
+type Flat<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type SegmentsOf<P extends string> = P extends `${infer A}/${infer B}` ? [...SegmentsOf<A>, ...SegmentsOf<B>] : P extends "" ? [] : [P];
+type FilterArg<F> = F extends TypedMatchFilter<infer T> ? T : F extends readonly (infer S)[] ? S : string | number;
+type ParamArg<Name extends string, F> = Name extends keyof F ? FilterArg<F[Name]> : string | number;
+/** Collects a maximal run of required params (and a trailing splat) into one call's argument tuple. */
+type ParamRun<Segs extends readonly string[], F, Args extends readonly unknown[] = [], PAcc extends Params = {}> = Segs extends readonly [infer H extends string, ...infer R extends readonly string[]] ? H extends `:${string}?` ? {
+    args: Args;
+    params: PAcc;
+    rest: Segs;
+} : H extends `:${infer N}` ? ParamRun<R, F, [...Args, ParamArg<N, F>], PAcc & {
+    [K in N]: string;
+}> : H extends `*${infer N}` ? {
+    args: [...Args, string | number];
+    params: PAcc & {
+        [K in N]: string;
+    };
+    rest: R;
+} : {
+    args: Args;
+    params: PAcc;
+    rest: Segs;
+} : {
+    args: Args;
+    params: PAcc;
+    rest: Segs;
+};
+/** The search param types a route end carries: input builds URLs, output is what parsing returns. */
+export interface SearchTypes {
+    input: any;
+    output: any;
+}
+export interface DefaultSearchTypes {
+    input: SetSearchParams;
+    output: SearchParams;
+}
+/** Terminating calls available on every route end: zero-arg, or search object plus optional hash. */
+export interface PathEnd<Sch extends SearchTypes = DefaultSearchTypes, P extends Params = Params> extends TypedPath<P>, TypedSearchPath<Sch["input"], Sch["output"]> {
+    (): string;
+    (search: Sch["input"], hash?: string): string;
+}
+type SearchTypesOf<Def> = Def extends {
+    search: infer S;
+} ? S extends StandardSchemaV1<any, any> ? {
+    input: NonNullable<S["~standard"]["types"]>["input"];
+    output: NonNullable<S["~standard"]["types"]>["output"];
+} : DefaultSearchTypes : DefaultSearchTypes;
+type FiltersOf<Def> = Def extends {
+    matchFilters: infer F;
+} ? F : {};
+type ChildrenOf<Def> = Def extends {
+    children: infer C;
+} ? C : undefined;
+/**
+ * Sees through a lazy `children` thunk: the routes the import's promise
+ * resolves to (its `default` or `routes` export, matching the runtime) type
+ * exactly like inline children. Only tables genuinely built at runtime —
+ * where the thunk's return type is a plain `RouteDefinition[]` — degrade to
+ * untyped, definitionally.
+ */
+type ResolvedChildren<C> = C extends () => infer R ? Awaited<R> extends infer M ? M extends {
+    default: infer D;
+} ? D : M extends {
+    routes: infer D;
+} ? D : M : never : C;
+type ChildPaths<C, PAcc extends Params> = [C] extends [undefined] ? {} : ResolvedChildren<C> extends infer RC ? RC extends readonly unknown[] ? TuplePaths<RC, PAcc> : RouteContrib<RC, PAcc> : never;
+type TuplePaths<R extends readonly unknown[], PAcc extends Params> = R extends readonly [
+    infer H,
+    ...infer T extends readonly unknown[]
+] ? RouteContrib<H, PAcc> & TuplePaths<T, PAcc> : {};
+type PathLeaf<Sch extends SearchTypes, C, PAcc extends Params> = PathEnd<Sch, Flat<PAcc>> & ChildPaths<C, PAcc>;
+type PathNode<Segs extends readonly string[], F, Sch extends SearchTypes, C, PAcc extends Params> = Segs extends readonly [infer H extends string, ...infer R extends readonly string[]] ? H extends `:${infer N}?` ? ((arg: ParamArg<N, F>) => PathNode<R, F, Sch, C, PAcc & {
+    [K in N]?: string;
+}>) & PathNode<R, F, Sch, C, PAcc & {
+    [K in N]?: string;
+}> : H extends `:${string}` | `*${string}` ? ParamCallNode<Segs, F, Sch, C, PAcc> : {
+    [K in H]: PathNode<R, F, Sch, C, PAcc>;
+} : PathLeaf<Sch, C, PAcc>;
+type ParamCallNode<Segs extends readonly string[], F, Sch extends SearchTypes, C, PAcc extends Params> = ParamRun<Segs, F> extends {
+    args: infer A extends readonly unknown[];
+    params: infer P2 extends Params;
+    rest: infer R2 extends readonly string[];
+} ? ((...args: A) => PathNode<R2, F, Sch, C, PAcc & P2>) & (R2 extends readonly [] ? {
+    (...args: [...A, Sch["input"], string?]): string;
+} : {}) & TypedPath<Flat<PAcc & P2>> : never;
+type RouteContrib<Def, PAcc extends Params> = Def extends {
+    path: infer P;
+} ? [P] extends [undefined] ? ChildPaths<ChildrenOf<Def>, PAcc> : P extends readonly string[] ? MultiPathContrib<P, Def, PAcc> : P extends string ? string extends P ? any : PathNode<SegmentsOf<P>, FiltersOf<Def>, SearchTypesOf<Def>, ChildrenOf<Def>, PAcc> : any : ChildPaths<ChildrenOf<Def>, PAcc>;
+type MultiPathContrib<Ps extends readonly string[], Def, PAcc extends Params> = Ps extends readonly [infer H extends string, ...infer T extends readonly string[]] ? PathNode<SegmentsOf<H>, FiltersOf<Def>, SearchTypesOf<Def>, ChildrenOf<Def>, PAcc> & MultiPathContrib<T, Def, PAcc> : {};
+/**
+ * The type of a router instance's `paths` proxy for a given route tree.
+ * Requires the tree to be a literal tuple (`as const` or a `const` type
+ * param); non-literal trees fall back to an untyped proxy.
+ */
+export type RoutePaths<R extends readonly RouteDefinition[]> = number extends R["length"] ? any : PathEnd<DefaultSearchTypes, {}> & TuplePaths<R, {}>;
+/** Extracts the params record a paths node binds, as runtime (string-valued) params. */
+export type PathParamsOf<N> = N extends TypedPath<infer P> ? Flat<P> : Params;
+/**
+ * Creates the runtime path proxy. It is instance-scoped: `renderPath` comes
+ * from the router's history adapter (eg. hash routing prefixes `#`), and
+ * `base` is baked into every produced path.
+ */
+export declare function createPathsProxy(renderPath?: (path: string) => string, base?: string): any;
+export {};

package/dist/paths.js

@@ -0,0 +1,41 @@
+import { mergeSearchString, normalizePath } from "./utils.js";
+/** Matches integer segments; types the param as `number` in the path proxy. */
+export const int = ((s) => /^-?\d+$/.test(s));
+// ---------------------------------------------------------------------------
+// Runtime
+// ---------------------------------------------------------------------------
+const encodeParam = (value) => String(value).split("/").map(encodeURIComponent).join("/");
+/**
+ * Creates the runtime path proxy. It is instance-scoped: `renderPath` comes
+ * from the router's history adapter (eg. hash routing prefixes `#`), and
+ * `base` is baked into every produced path.
+ */
+export function createPathsProxy(renderPath = p => p, base = "") {
+    const toHref = (pathname, suffix = "") => renderPath(pathname || "/") + suffix;
+    function node(pathname) {
+        const build = (...args) => {
+            let path = pathname;
+            for (let i = 0; i < args.length; i++) {
+                const arg = args[i];
+                if (typeof arg === "object" && arg !== null) {
+                    // a search object terminates; an optional hash string may follow
+                    const hash = typeof args[i + 1] === "string" ? `#${args[i + 1]}` : "";
+                    return toHref(path, mergeSearchString("", arg) + hash);
+                }
+                path += `/${encodeParam(arg)}`;
+            }
+            // zero-arg calls terminate; param-only calls stay chainable
+            return args.length ? node(path) : toHref(path);
+        };
+        return new Proxy(build, {
+            get(_, prop) {
+                if (prop === "toString")
+                    return () => toHref(pathname);
+                if (typeof prop === "symbol")
+                    return prop === Symbol.toPrimitive ? () => toHref(pathname) : undefined;
+                return node(`${pathname}/${prop}`);
+            }
+        });
+    }
+    return node(normalizePath(base));
+}

package/dist/routers/components.d.ts

@@ -1,27 +1,13 @@
-import type { Component, JSX } from "solid-js";
-import type { MatchFilters, RouteDefinition, RoutePreloadFunc, RouterIntegration, RouteSectionComponent, RouteSectionProps } from "../types.js";
-export type BaseRouterProps = {
-    base?: string;
-    /**
-     * A component that wraps the content of every route.
-     */
+import type { Component } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import type { Branch, RoutePreloadFunc, RouterContext, RouteSectionProps } from "../types.js";
+export declare function Root(props: {
+    routerState: RouterContext;
     root?: Component<RouteSectionProps>;
-    rootPreload?: RoutePreloadFunc;
-    singleFlight?: boolean;
-    children?: JSX.Element | RouteDefinition | RouteDefinition[];
-    transformUrl?: (url: string) => string;
-    /** @deprecated use rootPreload */
-    rootLoad?: RoutePreloadFunc;
-};
-export declare const createRouterComponent: (router: RouterIntegration) => (props: BaseRouterProps) => JSX.Element;
-export type RouteProps<S extends string, T = unknown> = {
-    path?: S | S[];
-    children?: JSX.Element;
-    preload?: RoutePreloadFunc<T>;
-    matchFilters?: MatchFilters<S>;
-    component?: RouteSectionComponent<T>;
-    info?: Record<string, any>;
-    /** @deprecated use preload */
-    load?: RoutePreloadFunc<T>;
-};
-export declare const Route: <S extends string, T = unknown>(props: RouteProps<S, T>) => JSX.Element;
+    preload?: RoutePreloadFunc;
+    children: JSX.Element;
+}): JSX.Element;
+export declare function Routes(props: {
+    routerState: RouterContext;
+    branches: () => Branch[];
+}): JSX.Element;

package/dist/routers/components.jsx

@@ -1,67 +1,72 @@
 /*@refresh skip*/
-import { children, createMemo, createRoot, getOwner, mergeProps, on, onCleanup, Show, untrack } from "solid-js";
-import { getRequestEvent, isServer } from "solid-js/web";
-import { createBranches, createRouteContext, createRouterContext, getIntent, getRouteMatches, RouteContextObj, RouterContextObj, setInPreloadFn } from "../routing.js";
-export const createRouterComponent = (router) => (props) => {
-    const { base } = props;
-    const routeDefs = children(() => props.children);
-    const branches = createMemo(() => createBranches(routeDefs(), props.base || ""));
-    let context;
-    const routerState = createRouterContext(router, branches, () => context, {
-        base,
-        singleFlight: props.singleFlight,
-        transformUrl: props.transformUrl,
-    });
-    router.create && router.create(routerState);
-    return (<RouterContextObj.Provider value={routerState}>
-      <Root routerState={routerState} root={props.root} preload={props.rootPreload || props.rootLoad}>
-        {(context = getOwner()) && null}
-        <Routes routerState={routerState} branches={branches()}/>
-      </Root>
-    </RouterContextObj.Provider>);
-};
-function Root(props) {
+import { createMemo, createRoot, getOwner, onCleanup, runWithOwner, untrack } from "solid-js";
+import { getRequestEvent, isServer } from "@solidjs/web";
+import { createRouteContext, getIntent, getRouteMatches, resolveLazySubtree, RouteContextObj, setInPreloadFn, unresolvedLazyMatches } from "../routing.js";
+export function Root(props) {
     const location = props.routerState.location;
     const params = props.routerState.params;
     const data = createMemo(() => props.preload &&
         untrack(() => {
             setInPreloadFn(true);
-            props.preload({ params, location, intent: getIntent() || "initial" });
-            setInPreloadFn(false);
+            try {
+                return props.preload({ params, location, intent: getIntent() || "initial" });
+            }
+            finally {
+                setInPreloadFn(false);
+            }
         }));
-    return (<Show when={props.root} keyed fallback={props.children}>
-      {Root => (<Root params={params} location={location} data={data()}>
-          {props.children}
-        </Root>)}
-    </Show>);
+    const RootComp = props.root;
+    if (RootComp) {
+        return (<RootComp params={params} location={location} data={data()}>
+        {props.children}
+      </RootComp>);
+    }
+    return props.children;
 }
-function Routes(props) {
+export function Routes(props) {
     if (isServer) {
         const e = getRequestEvent();
         if (e && e.router && e.router.dataOnly) {
-            dataOnly(e, props.routerState, props.branches);
+            dataOnly(e, props.routerState, props.branches());
             return;
         }
-        e &&
-            ((e.router || (e.router = {})).matches ||
-                (e.router.matches = props.routerState.matches().map(({ route, path, params }) => ({
+        if (e && !(e.router && e.router.matches)) {
+            // A lazy getter rather than a snapshot: unresolved lazy subtrees mean
+            // the match chain can still improve while the render streams, and
+            // frameworks read this after the render settles.
+            Object.defineProperty((e.router || (e.router = {})), "matches", {
+                configurable: true,
+                enumerable: true,
+                get: () => props.routerState.matches().map(({ route, path, params }) => ({
                     path: route.originalPath,
                     pattern: route.pattern,
                     match: path,
                     params,
                     info: route.info
-                }))));
+                }))
+            });
+        }
     }
     const disposers = [];
     let root;
+    let prevMatches;
     // dispose the detached per-route roots when this component unmounts, otherwise
     // they stay subscribed to `matches` and crash on a later navigation (#451)
     onCleanup(() => disposers.forEach(dispose => dispose()));
-    const routeStates = createMemo(on(props.routerState.matches, (nextMatches, prevMatches, prev) => {
-        let equal = prevMatches && nextMatches.length === prevMatches.length;
+    // Route roots must outlive re-runs of the `routeStates` memo below, so they
+    // are created under the owner of this component rather than the memo's
+    // computation (which disposes its children every time it re-runs).
+    const owner = getOwner();
+    const routeStates = createMemo((prev) => {
+        // While a lazy subtree resolves, `matches()` is not ready and this
+        // computation parks with it — no route contexts are created against
+        // placeholder matches.
+        const nextMatches = props.routerState.matches();
+        const previousMatches = prevMatches;
+        let equal = previousMatches && nextMatches.length === previousMatches.length;
         const next = [];
         for (let i = 0, len = nextMatches.length; i < len; i++) {
-            const prevMatch = prevMatches && prevMatches[i];
+            const prevMatch = previousMatches && previousMatches[i];
             const nextMatch = nextMatches[i];
             if (prev && prevMatch && nextMatch.route.key === prevMatch.route.key) {
                 next[i] = prev[i];
@@ -71,42 +76,51 @@ function Routes(props) {
                 if (disposers[i]) {
                     disposers[i]();
                 }
-                createRoot(dispose => {
+                runWithOwner(owner, () => createRoot(dispose => {
                     disposers[i] = dispose;
-                    next[i] = createRouteContext(props.routerState, next[i - 1] || props.routerState.base, createOutlet(() => routeStates()[i + 1]), () => {
+                    const routeKey = nextMatch.route.key;
+                    // Retain the last matches in which this route participated so
+                    // that its components and preloads never observe another
+                    // route's params/path while this route is being torn down.
+                    const matchesAtLevel = createMemo((prev) => {
                         const routeMatches = props.routerState.matches();
-                        return routeMatches[i] ?? routeMatches[0];
+                        const m = routeMatches[i];
+                        return m && m.route.key === routeKey ? routeMatches : prev || nextMatches;
                     });
-                });
+                    next[i] = createRouteContext(props.routerState, next[i - 1] || props.routerState.base, createOutlet(() => routeStates()?.[i + 1]), () => matchesAtLevel()[i], matchesAtLevel);
+                }));
             }
         }
         disposers.splice(nextMatches.length).forEach(dispose => dispose());
         if (prev && equal) {
+            prevMatches = nextMatches;
             return prev;
         }
         root = next[0];
+        prevMatches = nextMatches;
         return next;
-    }));
-    return createOutlet(() => routeStates() && root)();
+    });
+    const outlet = createOutlet(() => routeStates() && root);
+    return <>{outlet()}</>;
 }
 const createOutlet = (child) => {
-    return () => (<Show when={child()} keyed>
-      {child => <RouteContextObj.Provider value={child}>{child.outlet()}</RouteContextObj.Provider>}
-    </Show>);
-};
-export const Route = (props) => {
-    const childRoutes = children(() => props.children);
-    return mergeProps(props, {
-        get children() {
-            return childRoutes();
+    return () => {
+        const c = child();
+        if (c) {
+            return <RouteContextObj value={c}>{c.outlet()}</RouteContextObj>;
         }
-    });
+        return undefined;
+    };
 };
 // for data only mode with single flight mutations
 function dataOnly(event, routerState, branches) {
     const url = new URL(event.request.url);
     const prevMatches = getRouteMatches(branches, new URL(event.router.previousUrl || event.request.url).pathname);
     const matches = getRouteMatches(branches, url.pathname);
+    // This pass is synchronous — an unresolved lazy subtree can only be
+    // kicked, not awaited (the flight collector's own runner awaits; see
+    // src/server.ts). Best effort so a subsequent pass sees the table.
+    unresolvedLazyMatches([...prevMatches, ...matches]).forEach(resolveLazySubtree);
     for (let match = 0; match < matches.length; match++) {
         if (!prevMatches[match] || matches[match].route !== prevMatches[match].route)
             event.router.dataOnly = true;

package/dist/routers/factory.d.ts

@@ -0,0 +1,121 @@
+import type { JSX } from "@solidjs/web";
+import type { RoutePaths } from "../paths.js";
+import type { DefinedRouteFilters, LazyRouteChildren, OutputMatch, Params, RouteDefinition, RouteInfo, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteSectionComponent, RouteSectionProps, StandardSchemaV1, ValidFilters } from "../types.js";
+import type { RouterHistory } from "./history.js";
+/**
+ * Identity helper that preserves literal types when the route tree is
+ * declared as a separate variable. `createRouter` infers literally from
+ * inline arrays, but an extracted `const routes = [...]` widens paths to
+ * `string` and silently degrades `paths` and the typed hooks unless it is
+ * declared `as const` — `defineRoutes` makes that impossible to forget.
+ */
+export declare function defineRoutes<const R extends readonly RouteDefinition[]>(routes: R): R;
+type RouteChildren = RouteDefinition | readonly RouteDefinition[] | LazyRouteChildren;
+type DefinedRouteComponent<T, P extends Params> = (props: RouteSectionProps<T, P> & {
+    children?: any;
+}) => JSX.Element;
+/**
+ * The type `defineRoute` hands back: `path`, `matchFilters`, `children`, and
+ * `search` stay literal — and only present when provided precisely, which is
+ * what the `paths` machinery keys on — while `component`/`preload` widen back
+ * to the plain `RouteDefinition` contract so the route drops into any route
+ * tree. Generics that stayed at their fallback (not provided, or deferred by
+ * a context-sensitive value inside) are omitted rather than widening the
+ * whole route.
+ */
+export type DefinedRoute<S = undefined, T = unknown, F = undefined, C = undefined, Sch = undefined> = ([S] extends [undefined] ? {} : {
+    path: S;
+}) & ([F] extends [undefined] ? {} : DefinedRouteFilters<S> extends F ? {} : {
+    matchFilters: F;
+}) & ([C] extends [undefined] ? {} : [RouteChildren | undefined] extends [C] ? {} : {
+    children: C;
+}) & ([Sch] extends [undefined] ? {} : {
+    search: Sch;
+}) & {
+    component?: RouteSectionComponent<T>;
+    preload?: RoutePreloadFunc<T>;
+    info?: RouteInfo;
+};
+/**
+ * Identity helper that types a single route from its own `path` pattern:
+ * inside `component` and `preload`, `props.params`/`args.params` carry the
+ * params the pattern guarantees (`:id` is `string`, `:tab?` is
+ * `string | undefined`) instead of the open `Params` record. Params
+ * inherited from parent routes remain accessible as `string | undefined`.
+ *
+ * Purely a definition-site convenience — plain object routes behave
+ * identically at runtime, and nested `children` only get typed params if
+ * they use `defineRoute` themselves.
+ */
+export declare function defineRoute<const S extends string | readonly string[], T = unknown, const F = DefinedRouteFilters<S>, const C extends RouteChildren | undefined = RouteChildren | undefined, Sch extends StandardSchemaV1<any, any> | undefined = undefined>(route: {
+    path: S;
+    matchFilters?: F & ValidFilters<F, S>;
+    preload?: (args: RoutePreloadFuncArgs<RouteParams<S>>) => T;
+    component?: DefinedRouteComponent<T, RouteParams<S>>;
+    children?: C;
+    /** Standard Schema validator for this route's search params; its input type flows into the typed path proxy. */
+    search?: Sch;
+    info?: RouteInfo;
+}): DefinedRoute<S, T, F, C, Sch>;
+export declare function defineRoute<T = unknown, const C extends RouteChildren | undefined = RouteChildren | undefined, Sch extends StandardSchemaV1<any, any> | undefined = undefined>(route: {
+    preload?: (args: RoutePreloadFuncArgs) => T;
+    component?: DefinedRouteComponent<T, Params>;
+    children?: C;
+    search?: Sch;
+    info?: RouteInfo;
+}): DefinedRoute<undefined, T, undefined, C, Sch>;
+export interface RouterConfig<R extends readonly RouteDefinition[] = RouteDefinition[]> {
+    /** The route tree. Immutable per instance — it is the source of truth for matching *and* types. */
+    routes: R;
+    base?: string;
+    /**
+     * Runs once per mount/request (and on single-flight collection passes) to
+     * warm app-wide data. Its result is passed to the render-prop child as
+     * `props.data`.
+     */
+    preload?: RoutePreloadFunc;
+    /**
+     * History adapter for client navigation; defaults to browser history. On
+     * the server only its `utils` apply — the location comes from the request
+     * event or the provider's `url` prop.
+     */
+    history?: RouterHistory;
+    singleFlight?: boolean;
+    actionBase?: string;
+    explicitLinks?: boolean;
+    /** Preload route code/data on link hover and focus. Defaults to `true`. */
+    preloadLinks?: boolean;
+    /**
+     * Explicit scroll restoration for back/forward navigation: positions are
+     * saved per history entry and restored once the navigation settles,
+     * replacing the browser heuristic that loses offsets when the destination
+     * route forces a layout while rendering. Defaults to `true` with the
+     * default browser history; a custom `history` adapter owns its session and
+     * must opt in explicitly.
+     */
+    scrollRestoration?: boolean;
+    transformUrl?: (url: string) => string;
+}
+export interface RouterProps {
+    /**
+     * Server-only: the location for this render when no request event is in
+     * scope (SSG scripts, tests, runtimes without `node:async_hooks`). A
+     * request event established by the server harness takes precedence.
+     * Ignored on the client, where the history adapter owns the location.
+     */
+    url?: string;
+    children?: (props: RouteSectionProps) => JSX.Element;
+}
+export interface RouterInstance<R extends readonly RouteDefinition[] = RouteDefinition[]> {
+    /** The instance is the provider component; the render-prop child receives the matched content as `props.children`. */
+    (props: RouterProps): JSX.Element;
+    /** Typed path proxy — builds URLs through property access and calls. */
+    readonly paths: RoutePaths<R>;
+    readonly routes: R;
+    /** The config the instance was created with — lets server integrations (flight collector, no-JS handler) consume the instance directly. */
+    readonly config: RouterConfig<R>;
+    /** Pure matching against an arbitrary URL — no rendering or request context involved. Root→leaf; `[]` when nothing matches. */
+    match(url: string): OutputMatch[];
+}
+export declare function createRouter<const R extends readonly RouteDefinition[]>(config: RouterConfig<R>): RouterInstance<R>;
+export {};