modernjs-typed-routes 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giancarlos Isasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# modernjs-typed-routes
+
+[![npm version](https://img.shields.io/npm/v/modernjs-typed-routes)](https://www.npmjs.com/package/modernjs-typed-routes)
+[![CI](https://github.com/giancarlosisasi/modernjs-typed-routes/actions/workflows/ci.yml/badge.svg)](https://github.com/giancarlosisasi/modernjs-typed-routes/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Type-safe routes for [Modern.js](https://modernjs.dev): a zero-config CLI plugin that generates
+TypeScript types from your file-based `routes/` folders, plus typed `Link`, `Navigate` and
+`useNavigate` wrappers — so path typos and missing route params become **compile errors** instead
+of runtime 404s.
+
+> **Status: pre-release.** Not yet published to npm — v0.1.0 is on its way.
+
+![Demo: route autocomplete, typo'd path error, required params](./docs/public/demo.gif)
+
+```tsx
+import { Link, useNavigate } from 'modernjs-typed-routes';
+
+<Link to="/about" />                                // ✅ autocompleted route union
+<Link to="/blog/[id]" params={{ id: post.id }} />   // ✅ params required & typed
+<Link to="/blgo/[id]" params={{ id: post.id }} />   // ❌ error: Did you mean '"/blog/[id]"'?
+
+const { navigateTo } = useNavigate();
+navigateTo('/blog/[id]');                           // ❌ error: `params` is required here
+```
+
+## Quickstart
+
+**1. Install** (one package: build-time plugin + runtime wrappers):
+
+```bash
+pnpm add modernjs-typed-routes
+```
+
+**2. Register the plugin:**
+
+```ts
+// modern.config.ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { routeTypesPlugin } from 'modernjs-typed-routes/plugin';
+
+export default defineConfig({
+  plugins: [appTools(), routeTypesPlugin()],
+});
+```
+
+**3. Run `modern dev`** (or `npx modern typegen` to generate without starting anything). A single
+declaration file appears at `src/routes.gen.d.ts` and regenerates automatically whenever your
+routes change.
+
+**4. Import navigation from the package** instead of `@modern-js/runtime/router` — it re-exports
+the full router surface with `Link`, `Navigate` and `useNavigate` swapped for typed versions:
+
+```tsx
+import { Link } from 'modernjs-typed-routes';
+
+<Link to="/blog/[id]" params={{ id: 42 }}>Read post 42</Link>
+```
+
+That's the whole setup. See the docs for the full API: `buildPath`, `useTypedParams`,
+`createUrl`, search params, hashes, multi-entry apps and more.
+
+## Why this plugin
+
+- **Derived from Modern.js's own route parser** — not a re-implementation of its conventions, so
+  the types can't drift from what the framework serves. Covers dynamic `[id]`, optional `[id$]`,
+  splat `$`, pathless `__auth` layouts, flat `a.b.c` segments, `modern.routes.ts` config routes
+  and multi-entry apps.
+- **Types only, zero bundle cost** — the generated file is a `.d.ts`; declaration merging does the
+  rest. The wrappers are tiny static components.
+- **Params are objects, required per route** — `<Link to="/blog/[id]" params={{ id }}>`
+  autocompletes the path *and* the param names.
+- **CI friendly** — `npx modern typegen && tsc --noEmit` catches broken links in pull requests.
+
+## Comparison
+
+| | modernjs-typed-routes | Next.js `typedRoutes` | React Router `typegen` | TanStack Router |
+|---|---|---|---|---|
+| Framework | Modern.js | Next.js | RR framework mode | TanStack |
+| Typed path union | ✅ | ✅ | ✅ (`href()`) | ✅ |
+| Params required per route | ✅ objects | template strings only | ✅ (`href()`) | ✅ |
+| Typed navigation components | ✅ ships wrappers | `next/link` built-in | partial | ✅ built-in |
+| Search params | basic (validated planned) | ❌ | ❌ | ✅ validated |
+| Bundle cost | none (types only) | none | none | runtime router |
+
+## Requirements
+
+| | Supported |
+|---|---|
+| Modern.js | v3 — `@modern-js/app-tools` / `@modern-js/runtime` `^3.6.0` |
+| Node.js | ≥ 20 |
+| TypeScript | ≥ 5.3 |
+| React | ≥ 18 |
+
+Routing must use conventional `routes/` entries. Modern.js v2, the legacy `pages/` convention and
+self-controlled (`App.tsx`) entries are out of scope — there's no conventional route tree to type.
+
+## Documentation
+
+Full docs live in [`docs/`](./docs) (Rspress site — hosted version coming with the first release):
+guides for [getting started](./docs/guide/getting-started.md),
+[navigation](./docs/guide/navigation.md),
+[route conventions](./docs/guide/route-conventions.md) and
+[troubleshooting](./docs/guide/troubleshooting.md), plus the
+[plugin options](./docs/api/plugin-options.md) and [runtime API](./docs/api/runtime.md) reference.
+
+Related: [web-infra-dev/modern.js#6218](https://github.com/web-infra-dev/modern.js/issues/6218) —
+the upstream feature request this plugin answers.
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Development at a glance:
+
+```bash
+pnpm install
+pnpm build        # build the library (rslib)
+pnpm test         # unit + type-level + docs-snippet + playground checks
+pnpm test:e2e     # E2E against the real Modern.js CLI (examples/playground)
+pnpm check        # biome
+pnpm docs:dev     # rspress docs site
+```
+
+## License
+
+[MIT](./LICENSE) © Giancarlos Isasi

package/dist/index.cjs

@@ -0,0 +1,298 @@
+"use strict";
+var __webpack_modules__ = {
+    "./src/runtime/basename.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var _modern_js_runtime_router__rspack_import_0 = __webpack_require__("@modern-js/runtime/router");
+        const splitAtQueryOrHash = (url)=>{
+            const at = url.search(/[?#]/);
+            return -1 === at ? [
+                url,
+                ''
+            ] : [
+                url.slice(0, at),
+                url.slice(at)
+            ];
+        };
+        const normalizeBasename = (basename)=>{
+            const trimmed = basename.replace(/\/+$/, '');
+            return '' === trimmed ? '/' : trimmed;
+        };
+        function isWithinBasename(url, basename) {
+            const base = normalizeBasename(basename);
+            if ('/' === base) return true;
+            const [path] = splitAtQueryOrHash(url);
+            return path === base || path.startsWith(`${base}/`);
+        }
+        function toRouterPath(url, basename) {
+            const base = normalizeBasename(basename);
+            if ('/' === base || !isWithinBasename(url, base)) return url;
+            const [path, suffix] = splitAtQueryOrHash(url);
+            return (path.slice(base.length) || '/') + suffix;
+        }
+        function toRealUrl(url, basename) {
+            const base = normalizeBasename(basename);
+            if ('/' === base || isWithinBasename(url, base)) return url;
+            const [path, suffix] = splitAtQueryOrHash(url);
+            return ('/' === path ? base : `${base}${path}`) + suffix;
+        }
+        function useBasename() {
+            return normalizeBasename((0, _modern_js_runtime_router__rspack_import_0.useHref)('/'));
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            Kh: ()=>useBasename,
+            Tz: ()=>toRealUrl,
+            aT: ()=>toRouterPath
+        });
+    },
+    "./src/runtime/build-path.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        const OPTIONAL_TOKEN = /^\[(.+)\$\]$/;
+        const REQUIRED_TOKEN = /^\[(.+)\]$/;
+        const isAbsent = (value)=>null == value || '' === value;
+        function substituteSegment(segment, params, path) {
+            if ('$' === segment) {
+                const splat = params['*'];
+                if (isAbsent(splat)) return null;
+                const pieces = String(splat).split('/').filter(Boolean);
+                return 0 === pieces.length ? null : pieces.map(encodeURIComponent).join('/');
+            }
+            const optional = OPTIONAL_TOKEN.exec(segment);
+            if (optional) {
+                const value = params[optional[1]];
+                if (isAbsent(value)) return null;
+                return encodeURIComponent(String(value));
+            }
+            const required = REQUIRED_TOKEN.exec(segment);
+            if (required) {
+                const name = required[1];
+                const value = params[name];
+                if (isAbsent(value)) throw new Error(`[modernjs-typed-routes] Missing required param "${name}" for path "${path}".`);
+                return encodeURIComponent(String(value));
+            }
+            return segment;
+        }
+        function serializeSearchParams(searchParams) {
+            const query = new URLSearchParams();
+            for (const [key, value] of Object.entries(searchParams))if (null != value) query.append(key, String(value));
+            return query.toString();
+        }
+        function buildPath(path, ...args) {
+            const { params = {}, searchParams, hash } = args[0] ?? {};
+            const wantsTrailingSlash = path.length > 1 && path.endsWith('/');
+            const base = wantsTrailingSlash ? path.slice(0, -1) : path;
+            const built = base.split('/').filter((segment)=>'' !== segment).map((segment)=>substituteSegment(segment, params, path)).filter((segment)=>null !== segment).join('/');
+            let url = `/${built}`;
+            if (wantsTrailingSlash && '/' !== url) url += '/';
+            if (searchParams) {
+                const query = serializeSearchParams(searchParams);
+                if ('' !== query) url += `?${query}`;
+            }
+            if (void 0 !== hash && '' !== hash && '#' !== hash) url += hash.startsWith('#') ? hash : `#${hash}`;
+            return url;
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            U: ()=>buildPath
+        });
+    },
+    "./src/runtime/link.tsx" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var react_jsx_runtime__rspack_import_0 = __webpack_require__("react/jsx-runtime");
+        var _modern_js_runtime_router__rspack_import_1 = __webpack_require__("@modern-js/runtime/router");
+        var react__rspack_import_2 = __webpack_require__("react");
+        var _basename__rspack_import_3 = __webpack_require__("./src/runtime/basename.ts");
+        var _build_path__rspack_import_4 = __webpack_require__("./src/runtime/build-path.ts");
+        function LinkImpl(props, ref) {
+            const { to, params, searchParams, hash, ...rest } = props;
+            const basename = (0, _basename__rspack_import_3.Kh)();
+            const url = (0, _build_path__rspack_import_4.U)(to, {
+                params,
+                searchParams,
+                hash
+            });
+            return /*#__PURE__*/ (0, react_jsx_runtime__rspack_import_0.jsx)(_modern_js_runtime_router__rspack_import_1.Link, {
+                ...rest,
+                ref: ref,
+                to: (0, _basename__rspack_import_3.aT)(url, basename)
+            });
+        }
+        LinkImpl.displayName = 'TypedLink';
+        const Link = /*#__PURE__*/ (0, react__rspack_import_2.forwardRef)(LinkImpl);
+        __webpack_require__.d(__webpack_exports__, {}, {
+            N: Link
+        });
+    },
+    "./src/runtime/navigate.tsx" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var react_jsx_runtime__rspack_import_0 = __webpack_require__("react/jsx-runtime");
+        var _modern_js_runtime_router__rspack_import_1 = __webpack_require__("@modern-js/runtime/router");
+        var _basename__rspack_import_2 = __webpack_require__("./src/runtime/basename.ts");
+        var _build_path__rspack_import_3 = __webpack_require__("./src/runtime/build-path.ts");
+        function Navigate(props) {
+            const { to, params, searchParams, hash, ...rest } = props;
+            const basename = (0, _basename__rspack_import_2.Kh)();
+            const url = (0, _build_path__rspack_import_3.U)(to, {
+                params,
+                searchParams,
+                hash
+            });
+            return /*#__PURE__*/ (0, react_jsx_runtime__rspack_import_0.jsx)(_modern_js_runtime_router__rspack_import_1.Navigate, {
+                ...rest,
+                to: (0, _basename__rspack_import_2.aT)(url, basename)
+            });
+        }
+        Navigate.displayName = 'TypedNavigate';
+        __webpack_require__.d(__webpack_exports__, {
+            C: ()=>Navigate
+        });
+    },
+    "./src/runtime/reexports.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        __webpack_require__.r(__webpack_exports__);
+        var _modern_js_runtime_router__rspack_import_0 = __webpack_require__("@modern-js/runtime/router");
+        var __rspack_reexport = {};
+        for(const __rspack_import_key in _modern_js_runtime_router__rspack_import_0)if ([
+            "useTypedParams",
+            "buildPath",
+            "default",
+            "Navigate",
+            "useNavigate",
+            "Link"
+        ].indexOf(__rspack_import_key) < 0) __rspack_reexport[__rspack_import_key] = ()=>_modern_js_runtime_router__rspack_import_0[__rspack_import_key];
+        __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+        var _build_path__rspack_import_1 = __webpack_require__("./src/runtime/build-path.ts");
+        var _link__rspack_import_2 = __webpack_require__("./src/runtime/link.tsx");
+        var _navigate__rspack_import_3 = __webpack_require__("./src/runtime/navigate.tsx");
+        var _use_navigate__rspack_import_4 = __webpack_require__("./src/runtime/use-navigate.ts");
+        var _use_typed_params__rspack_import_5 = __webpack_require__("./src/runtime/use-typed-params.ts");
+        __webpack_require__.d(__webpack_exports__, {
+            Link: ()=>_link__rspack_import_2.N,
+            Navigate: ()=>_navigate__rspack_import_3.C,
+            buildPath: ()=>_build_path__rspack_import_1.U,
+            useNavigate: ()=>_use_navigate__rspack_import_4.Z,
+            useTypedParams: ()=>_use_typed_params__rspack_import_5.C
+        });
+    },
+    "./src/runtime/use-navigate.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var _modern_js_runtime_router__rspack_import_0 = __webpack_require__("@modern-js/runtime/router");
+        var react__rspack_import_1 = __webpack_require__("react");
+        var _basename__rspack_import_2 = __webpack_require__("./src/runtime/basename.ts");
+        var _build_path__rspack_import_3 = __webpack_require__("./src/runtime/build-path.ts");
+        function useNavigate() {
+            const originalNavigate = (0, _modern_js_runtime_router__rspack_import_0.useNavigate)();
+            const basename = (0, _basename__rspack_import_2.Kh)();
+            const navigateTo = (0, react__rspack_import_1.useCallback)((to, ...args)=>{
+                const { replace, state, ...build } = args[0] ?? {};
+                const url = (0, _build_path__rspack_import_3.U)(to, build);
+                originalNavigate((0, _basename__rspack_import_2.aT)(url, basename), {
+                    replace,
+                    state
+                });
+            }, [
+                originalNavigate,
+                basename
+            ]);
+            const createUrl = (0, react__rspack_import_1.useCallback)((to, ...args)=>(0, _basename__rspack_import_2.Tz)((0, _build_path__rspack_import_3.U)(to, ...args), basename), [
+                basename
+            ]);
+            const goBack = (0, react__rspack_import_1.useCallback)(()=>{
+                originalNavigate(-1);
+            }, [
+                originalNavigate
+            ]);
+            return (0, react__rspack_import_1.useMemo)(()=>({
+                    navigateTo,
+                    createUrl,
+                    goBack,
+                    originalNavigate
+                }), [
+                navigateTo,
+                createUrl,
+                goBack,
+                originalNavigate
+            ]);
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            Z: ()=>useNavigate
+        });
+    },
+    "./src/runtime/use-typed-params.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        var _modern_js_runtime_router__rspack_import_0 = __webpack_require__("@modern-js/runtime/router");
+        function useTypedParams(_path) {
+            return (0, _modern_js_runtime_router__rspack_import_0.useParams)();
+        }
+        __webpack_require__.d(__webpack_exports__, {
+            C: ()=>useTypedParams
+        });
+    },
+    "@modern-js/runtime/router" (module) {
+        module.exports = require("@modern-js/runtime/router");
+    },
+    react (module) {
+        module.exports = require("react");
+    },
+    "react/jsx-runtime" (module) {
+        module.exports = require("react/jsx-runtime");
+    }
+};
+var __webpack_module_cache__ = {};
+function __webpack_require__(moduleId) {
+    var cachedModule = __webpack_module_cache__[moduleId];
+    if (void 0 !== cachedModule) return cachedModule.exports;
+    var module = __webpack_module_cache__[moduleId] = {
+        exports: {}
+    };
+    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+    return module.exports;
+}
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+(()=>{
+    __webpack_require__.r(__webpack_exports__);
+    var _runtime_reexports__rspack_import_0 = __webpack_require__("./src/runtime/reexports.ts");
+    var __rspack_reexport = {};
+    for(const __rspack_import_key in _runtime_reexports__rspack_import_0)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_runtime_reexports__rspack_import_0[__rspack_import_key];
+    __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+})();
+exports.Link = __webpack_exports__.Link;
+exports.Navigate = __webpack_exports__.Navigate;
+exports.buildPath = __webpack_exports__.buildPath;
+exports.useNavigate = __webpack_exports__.useNavigate;
+exports.useTypedParams = __webpack_exports__.useTypedParams;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "Link",
+    "Navigate",
+    "buildPath",
+    "useNavigate",
+    "useTypedParams"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.cts

@@ -0,0 +1,176 @@
+import { ComponentProps } from 'react';
+import { Link as Link_2 } from '@modern-js/runtime/router';
+import { Navigate as Navigate_2 } from '@modern-js/runtime/router';
+import { NavigateFunction } from '@modern-js/runtime/router';
+import { ReactElement } from 'react';
+import { Ref } from 'react';
+
+declare type AllEntryRouteKeys = {
+    [E in RegisterEntryName]: keyof RoutesOf<E> & string;
+}[RegisterEntryName];
+
+export declare type BaseBuildOptions = {
+    searchParams?: SearchParamsInit;
+    hash?: string;
+};
+
+/** Same conditional tuple for `buildPath` / `createUrl`. */
+export declare type BuildArgs<P extends RoutePath> = Record<string, never> extends RouteParams<P> ? [options?: BuildOptions<P>] : [options: BuildOptions<P>];
+
+/** Options for `buildPath` / `createUrl` — `params` conditionally required (D8). */
+export declare type BuildOptions<P extends RoutePath> = BaseBuildOptions & WithParams<P>;
+
+/**
+ * `buildPath('/blog/[id]', { params: { id: 42 }, searchParams: { ref: 'rss' }, hash: 'top' })`
+ * → `'/blog/42?ref=rss#top'`
+ */
+export declare function buildPath<P extends RoutePath>(path: P, ...args: BuildArgs<P>): string;
+
+declare type EntriesMap = Register extends {
+    entries: infer E extends EntriesShape;
+} ? E : never;
+
+declare type EntriesShape = Record<string, {
+    basename: string;
+    routes: RoutesShape;
+}>;
+
+/** Write-side params scoped to one entry. */
+export declare type EntryRouteParams<E extends RegisterEntryName, P extends EntryRoutePath<E>> = P extends keyof RoutesOf<E> ? ParamsLookup<RoutesOf<E>[P]> : never;
+
+/** Route-path literals belonging to ONE entry of a multi-entry app. */
+export declare type EntryRoutePath<E extends RegisterEntryName> = keyof RoutesOf<E> & string;
+
+/** Fallback write-side params when nothing is generated yet. */
+declare type FallbackParams = Record<string, string | number>;
+
+declare type HasEntries = [EntriesMap] extends [never] ? false : true;
+
+declare type HasSingle = [SingleRoutes] extends [never] ? false : true;
+
+export declare const Link: <P extends RoutePath>(props: LinkProps<P> & {
+    ref?: Ref<HTMLAnchorElement>;
+}) => ReactElement;
+
+export declare type LinkProps<P extends RoutePath> = Omit<RouterLinkProps, 'to'> & {
+    to: P;
+} & BaseBuildOptions & WithParams<P>;
+
+export declare function Navigate<P extends RoutePath>(props: NavigateProps<P>): ReactElement;
+
+export declare namespace Navigate {
+    var displayName: string;
+}
+
+/**
+ * Argument tuple making the whole options object required exactly when the
+ * route has required params: `navigateTo('/blog/[id]')` must not compile.
+ */
+export declare type NavigateArgs<P extends RoutePath> = Record<string, never> extends RouteParams<P> ? [options?: NavigateToOptions<P>] : [options: NavigateToOptions<P>];
+
+export declare type NavigateProps<P extends RoutePath> = Omit<RouterNavigateProps, 'to'> & {
+    to: P;
+} & BaseBuildOptions & WithParams<P>;
+
+/** Options for `navigateTo` / `<Navigate>`. */
+export declare type NavigateToOptions<P extends RoutePath> = BuildOptions<P> & {
+    replace?: boolean;
+    state?: unknown;
+};
+
+/** `infer`-based lookup — TS cannot index `['params']` on a generic entry lookup directly. */
+declare type ParamsLookup<R> = R extends {
+    params: infer P extends ParamsShape;
+} ? P : never;
+
+declare type ParamsShape = Record<string, unknown>;
+
+/**
+ * Runtime entry (`modernjs-typed-routes`): the full router surface with the
+ * typed wrappers shadowing `Link`/`Navigate`/`useNavigate` (docs contract).
+ *
+ * `Register` MUST be an interface (never a `type`): the generated
+ * `routes.gen.d.ts` fills it via declaration merging (D5), which only
+ * works on interfaces. It must also stay DECLARED here — module
+ * augmentation does not merge through re-exports.
+ */
+export declare interface Register {
+}
+
+/**
+ * Entry names of a multi-entry Register (`never` for single-entry/empty).
+ * The `HasEntries` guard is required: with `EntriesMap = never`,
+ * `keyof never & string` collapses to `string`, not `never`.
+ */
+export declare type RegisterEntryName = HasEntries extends true ? keyof EntriesMap & string : never;
+
+/** Write-side params for route `P` (values `string | number`, splat `string`). */
+export declare type RouteParams<P extends RoutePath> = HasSingle extends true ? P extends keyof SingleRoutes ? SingleRoutes[P]['params'] : never : HasEntries extends true ? {
+    [E in RegisterEntryName]: P extends keyof RoutesOf<E> ? ParamsLookup<RoutesOf<E>[P]> : never;
+}[RegisterEntryName] : FallbackParams;
+
+/** Union of all route-path literals; `string` before the first generation. */
+export declare type RoutePath = HasSingle extends true ? keyof SingleRoutes & string : HasEntries extends true ? AllEntryRouteKeys : string;
+
+/** Alias of {@link RoutePath} for app-level props (`RoutePathname | (string & {})`). */
+export declare type RoutePathname = RoutePath;
+
+/**
+ * Read-side params for `useTypedParams` — values are always `string`
+ * (that's what the URL contains); optionality is preserved.
+ */
+export declare type RouteReadParams<P extends RoutePath> = {
+    [K in keyof RouteParams<P>]: string;
+};
+
+declare type RouterLinkProps = ComponentProps<typeof Link_2>;
+
+declare type RouterNavigateProps = ComponentProps<typeof Navigate_2>;
+
+declare type RoutesOf<E extends RegisterEntryName> = EntriesMap[E]['routes'];
+
+declare type RoutesShape = Record<string, {
+    params: ParamsShape;
+}>;
+
+export declare type SearchParamsInit = Record<string, string | number | boolean>;
+
+declare type SingleRoutes = Register extends {
+    routes: infer R extends RoutesShape;
+} ? R : never;
+
+declare type StaticKeysOf<R extends RoutesShape> = {
+    [K in keyof R]: Record<string, never> extends R[K]['params'] ? K : never;
+}[keyof R] & string;
+
+/** Only the routes callable without a `params` argument (optional-only included). */
+export declare type StaticRoutePath = HasSingle extends true ? StaticKeysOf<SingleRoutes> : HasEntries extends true ? {
+    [E in RegisterEntryName]: StaticKeysOf<RoutesOf<E>>;
+}[RegisterEntryName] : string;
+
+export declare function useNavigate(): {
+    navigateTo: <P extends RoutePath>(to: P, options?: NavigateToOptions<P> | undefined) => void;
+    createUrl: <P extends RoutePath>(to: P, options?: BuildOptions<P> | undefined) => string;
+    goBack: () => void;
+    originalNavigate: NavigateFunction;
+};
+
+export declare function useTypedParams<P extends RoutePath>(_path: P): RouteReadParams<P>;
+
+/**
+ * `params` prop/option: required iff the route has required params (D8).
+ * Keyless params (`{}`) are tightened to `Record<string, never>` so passing
+ * params to a static route is a type error (TS never excess-checks against
+ * `{}`); the empty-Register fallback keeps `keyof = string` and stays
+ * permissive.
+ */
+export declare type WithParams<P extends RoutePath> = Record<string, never> extends RouteParams<P> ? {
+    params?: [keyof RouteParams<P>] extends [never] ? Record<string, never> : RouteParams<P>;
+} : {
+    params: RouteParams<P>;
+};
+
+
+export * from "@modern-js/runtime/router";
+
+export { }