@budarin/use-route 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+    push:
+        branches: [master]
+        paths:
+            - 'src/**'
+            - 'tests/**'
+            - 'package.json'
+            - 'pnpm-lock.yaml'
+            - 'tsconfig.json'
+            - 'vitest.config.ts'
+            - '.prettierrc'
+            - '.prettierignore'
+            - '.github/workflows/**'
+
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - uses: pnpm/action-setup@v4
+              with:
+                  version: 9
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: '20'
+                  cache: 'pnpm'
+
+            - name: Установка зависимостей
+              run: pnpm install --frozen-lockfile
+
+            - name: Lint
+              run: pnpm lint
+
+            - name: Type-check
+              run: pnpm type-check
+
+            - name: Тесты
+              run: pnpm test:run
+
+            - name: Сборка
+              run: pnpm build

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Вадим Бударин
+
+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,582 @@
+# @budarin/use-route
+
+**Минимум кода. Максимум SPA-навигации.**
+
+Инфраструктурный хук для React на **Navigation API** + **URLPattern**. Без провайдеров, без контекста, без бизнес-логики.
+
+**Сферы применения:**
+
+- **Чистая архитектура** — загрузка данных в use cases и сервисах, не в роутере; хук даёт только состояние маршрута и навигацию, без loaders и встроенной загрузки данных.
+- **Динамическое дерево компонентов** — что рендерить определяется в рантайме по URL (`pathname`, `params`, `matched`), а не статичным деревом маршрутов. Подходит, когда маршруты зависят от ролей, фич-флагов, CMS или конфига с бэка.
+- **Иерархия URL без вложенных роутов** — плоская, графовая или условная структура путей; один паттерн (или PathMatcher) и проверка по `params` вместо вложенных `<Route>`.
+- **SPA по подпути** — приложение располагается не в корне домена, а по подпути (например `/app/`); глобальный `base` в конфиге и опция `base` в `navigate`/`replace` для переходов «вне» этого пути.
+- **SSR и гибридные сетапы** — на сервере задаётся `initialLocation` в конфиге один раз перед рендером запроса; единообразная настройка без отдельного API.
+- **Реальные SPA и гибридные приложения** — один хук, один конфиг, типы и тесты; применим в продакшене при опоре на современные браузеры (Navigation API + URLPattern).
+
+История формируется динамически: при каждом переходе можно выбрать `push` или `replace`.
+
+[![CI](https://github.com/budarin/use-route/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/budarin/use-route/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@budarin/use-route?color=cb0000)](https://www.npmjs.com/package/@budarin/use-route)
+[![npm](https://img.shields.io/npm/dt/@budarin/use-route)](https://www.npmjs.com/package/@budarin/use-route)
+[![bundle](https://img.shields.io/bundlephobia/minzip/@budarin/use-route)](https://bundlephobia.com/result?p=@budarin/use-route)
+[![GitHub](https://img.shields.io/github/license/budarin/use-route)](https://github.com/budarin/use-route)
+
+## ✨ Особенности
+
+- ✅ **Динамическое дерево** — маршрутизация в рантайме по pathname/params, без статичного route tree
+- ✅ **Динамическая история** — при каждом `navigate`/`replace` выбирается `push` или `replace`
+- ✅ **Navigation API** (`window.navigation.navigate()`, `traverseTo()`, `back/forward/go(n)`)
+- ✅ **URLPattern** для парсинга `:params` (только актуальные браузеры и Node.js)
+- ✅ `useSyncExternalStore` — concurrent-safe, SSR-ready
+- ✅ `canGoBack(n)`, `canGoForward(n)` — точная проверка по истории
+- ✅ **LRU кэш URL** с настраиваемым лимитом (по умолчанию 50)
+- ✅ **O(1) поиск** `historyIndex` через Map
+- ✅ **Только актуальные браузеры и Node.js** (Navigation API + URLPattern), без fallback
+- ✅ **0 провайдеров** — просто `useRoute()`
+- ✅ **~4 kB** gzipped (исходный код; с минификацией в бандле меньше)
+
+## ⚠️ Когда не использовать
+
+- **Нужна поддержка старых браузеров** — хук опирается на Navigation API и URLPattern, без fallback на History API. Если целевая аудитория использует браузеры без этих API, возьмите React Router, TanStack Router или другой роутер с полифиллами.
+- **Нужны loaders или загрузка данных в роутере** — здесь загрузка данных не входит в зону ответственности; её делают use cases и сервисы. Если вы хотите loaders/данные «из коробки» в маршруте — подойдут React Router (loaders) или TanStack Router.
+- **Нужно декларативное дерево маршрутов** — хук не предоставляет `<Route>` / `<Routes>`; что рендерить, вы решаете в коде по `pathname`/`params`. Если важна именно декларативная вложенная структура маршрутов — используйте один из перечисленных роутеров.
+- **Нужны встроенные guards, redirects, lazy-роуты** — этого в пакете нет; реализуется в приложении поверх хука.
+
+В остальных случаях (современные браузеры, чистая архитектура, динамические маршруты, без loaders в роутере) пакет подходит.
+
+## 🚀 Быстрый старт
+
+```bash
+npm i @budarin/use-route
+```
+
+```typescript
+import { useRoute, configureRouter } from '@budarin/use-route';
+
+
+function App() {
+    const {
+        pathname,
+        params,
+        searchParams,
+        navigate,
+        go,
+        canGoBack
+    } = useRoute('/users/:id'); // опционально: паттерн для парсинга params
+
+    return (
+        <div>
+            <h1>Current: {pathname}</h1>
+            <p>User ID: {params.id}</p>
+
+            <button onClick={() => navigate('/users/123')}>
+                To Profile
+            </button>
+
+            <button onClick={() => go(-1)} disabled={!canGoBack()}>
+                ← Back
+            </button>
+        </div>
+    );
+}
+```
+
+## 📖 API
+
+### `useRoute(pattern?: string | PathMatcher, options?: UseRouteOptions)` / `useRoute(options: UseRouteOptions)`
+
+**Формы вызова:**
+
+- **`useRoute()`** — без pattern и опций.
+- **`useRoute(pattern)`** — только pattern (строка или PathMatcher).
+- **`useRoute(pattern, options)`** — pattern и опции (например `base`).
+- **`useRoute({ base: '/dashboard' })`** — только опции, без pattern (удобно для раздела с локальным base; не нужно передавать `undefined`).
+
+**Параметры:**
+
+- **`pattern`** (опционально) — строка-паттерн (URLPattern) или PathMatcher для парсинга `params` и `matched`.
+- **`options`** (опционально) — **`base`**: локальный базовый путь для этого поддерева (раздел приложения под своим подпутём). Тогда `pathname` возвращается без этого префикса, а `navigate(to)` по умолчанию добавляет его к относительным путям. Приоритет над глобальным `base` из `configureRouter`. Подходит, когда у приложения несколько разделов по разным подпутям (`/dashboard`, `/admin`, `/auth`): в компонентах раздела вызывайте `useRoute({ base: '/dashboard' })` и работайте с путями относительно раздела.
+
+**Возвращает:**
+
+```typescript
+{
+    // Текущее состояние
+    location: string;
+    pathname: string;
+    searchParams: URLSearchParams; // только чтение, не мутировать
+    params: Record<string, string>;
+    historyIndex: number;
+    matched?: boolean; // true/false при переданном pattern, иначе undefined
+
+    // Навигация
+    navigate: (to: string | URL, options?) => Promise<void>; // резолвится при commit, см. Navigation API
+    back: () => void;
+    forward: () => void;
+    go: (delta: number) => void;
+    replace: (to: string | URL, options?: NavigateOptions) => Promise<void>;
+    canGoBack: (steps?: number) => boolean;
+    canGoForward: (steps?: number) => boolean;
+}
+```
+
+**Опции `navigate` и `replace`** (один интерфейс **NavigateOptions**):
+
+```typescript
+{
+    history?: 'push' | 'replace' | 'auto'; // по умолчанию из configureRouter или 'auto'
+    state?: unknown;   // опциональные данные перехода (только подсказки для UX); подробнее — раздел про state ниже
+    base?: string;     // базовый путь для этого вызова: undefined — из конфига; '' или '/' — без префикса; иначе — другой base (напр. '/auth')
+}
+```
+
+**`state`** — произвольные данные, которые вы передаёте вместе с переходом в `navigate(to, { state })` или `replace(to, { state })`. Используйте только для опциональных подсказок (скролл, откуда пришли, префилл формы): страница должна корректно работать и при заходе по прямой ссылке без state. Подробно: см. ниже «Параметр state: когда добавлять в историю».
+
+**`replace(to, options?)`** — то же, что `navigate(to, { ...options, history: 'replace' })`. Опции те же, что у **navigate** (state, base); поле **history** игнорируется (всегда замена записи).
+
+**Параметр state: когда добавлять в историю и какое состояние можно передавать**
+
+Многие разработчики ни разу не используют state при переходах — это нормально. State нужен только в узких сценариях. Ниже — когда его стоит добавлять, какое состояние можно передавать и какое нельзя, чтобы не было недопониманий.
+
+**Что такое state и откуда он берётся.** State — это произвольные данные, которые вы передаёте в `navigate(to, { state })` или `replace(to, { state })`. Они сохраняются в записи истории (Navigation API) и доступны на целевой странице через `window.navigation.currentEntry.getState()`. **Важно:** state появляется только при программном переходе (ваш вызов navigate/replace). Если пользователь попал на тот же URL извне — ввёл адрес в строке, перешёл по букмарку, по ссылке с другого сайта, обновил страницу — для этой записи истории state нет. Поэтому поведение страницы не должно от state критически зависеть.
+
+**Когда нужно добавлять state в историю.** Добавляйте state только когда вы хотите передать «подсказку» для целевой страницы, которая улучшает UX при программном переходе, но не обязательна для корректной работы:
+
+- **Подсказка для скролла** — уходя со страницы списка, сохраняете в state позицию скролла; по «Назад» можно вернуть пользователя на то же место. Если зашли по прямой ссылке — state нет, показываете список с начала.
+- **Подсказка «откуда пришли»** — переход с поиска на карточку: в state передаёте `{ from: 'search', highlight: 'keyword' }`; на карточке можно подсветить слово. При заходе по прямой ссылке подсветки нет — страница остаётся корректной.
+- **Опциональный префилл формы** — переход «Редактировать» из списка: в state передаёте черновик; на странице редактирования при наличии state подставляете его, при отсутствии — грузите данные по id из URL/сервера.
+- **Источник перехода (аналитика, UI)** — в state передаёте `{ source: 'dashboard' }`; целевая страница может отправить это в аналитику или чуть изменить UI. При заходе по ссылке без state считаете источник «прямой» или «unknown».
+
+**Какое state можно передавать.** Только то, что является **опциональным улучшением**: подсказки для скролла, флаги «откуда пришли», опциональный префилл, метаданные для аналитики. Правило: целевая страница должна корректно работать и без state (при прямом заходе по URL).
+
+**Какое state нельзя передавать.** Не используйте state для того, без чего страница работает некорректно или неполно:
+
+- **Обязательные данные страницы** — например, результаты поиска только из state. При переходе по ссылке `/search?q=foo` state нет — экран пустой. Результаты должны браться из query или сервера.
+- **То, что должно быть в URL (шаринг, букмарк)** — state не попадает в URL. Если поведение страницы должно воспроизводиться по одной ссылке — используйте pathname и query, не state.
+- **Авторизация, права, критичные данные** — не опирайтесь на state: пользователь может открыть URL напрямую. Проверки — по сессии/серверу.
+- **Основной контент страницы** — что показывать, определяется URL и данными с бэкенда. State — только для подсказок, не источник правды.
+
+**Итог.** State в истории — опциональный инструмент для «передать что-то вместе с переходом», когда это улучшение, а не требование. Если сомневаетесь — можно не использовать; в большинстве приложений достаточно pathname, query и запросов к API.
+
+**`configureRouter(config)`** — глобальная настройка один раз при старте приложения:
+
+```typescript
+configureRouter({
+    urlCacheLimit: 50, // лимит LRU-кэша URL (по умолчанию 50)
+    defaultHistory: 'replace', // history по умолчанию для всех navigate()
+    logger: myLogger, // логгер (дефолт: console)
+    base: '/app', // базовый путь: pathname без base, navigate(to) добавляет base к относительным путям
+    initialLocation: request.url, // для SSR: начальный URL при рендере на сервере (нет window)
+});
+```
+
+**`base`** (глобальный) — нужен только когда **приложение располагается не в корне домена**, а по подпути. Пример: сайт `https://example.com/` — корень; ваше приложение отдаётся по `https://example.com/app/`, то есть все его маршруты физически лежат под путём `/app`. В этом случае задайте `base: '/app'`: тогда `pathname` в хуке возвращается без префикса (как будто приложение в корне — `/dashboard` вместо `/app/dashboard`), а `navigate('/dashboard')` переходит на `/app/dashboard`. Если приложение в корне домена (`https://example.com/`), глобальный `base` задавать не нужно — префикс не используется.
+
+**`initialLocation`** — при SSR (нет `window`) хук не знает URL запроса. Задайте `initialLocation: request.url` (или полный URL страницы) один раз перед рендером запроса — тогда `pathname` и `searchParams` будут соответствовать запросу. На клиенте не используется. **По умолчанию задавать не нужно:** если на SSR `initialLocation` не задан, используется `'/'` (pathname и searchParams для корня).
+
+**Логгер:** тип `Logger` — объект с методами `trace`, `debug`, `info`, `warn`, `error` (как у `console`). Уровни: `LoggerLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error'`. Если не передан — используется `console`.
+
+**`pattern` (опционально):** строка-шаблон пути (нативный **URLPattern**) или функция **PathMatcher**. См. ниже.
+
+**Строка (URLPattern).** Поддерживается:
+
+- **Именованные параметры** — `:name` (имя как в JS: буквы, цифры, `_`). Значение сегмента попадает в `params[name]`.
+- **Опциональные группы** — `{ ... }?`: часть пути можно сделать необязательной. Один паттерн покрывает пути разной глубины; в `params` только те ключи, для которых есть сегмент в URL.
+- **Wildcard** — `*`: совпадает с «хвостом» пути; в `params` не попадает (числовые ключи из `groups` отфильтрованы).
+- **Regexp в параметре** — `:name(регулярка)` для ограничения формата сегмента (например только цифры). В `params` по-прежнему строка.
+
+```typescript
+useRoute('/users/:id');
+useRoute('/elements/:elementId/*/:subElementId'); // wildcard
+
+// Опциональные группы
+useRoute('/users/:id{/posts/:postId}?');
+
+// Ограничение формата параметра (regexp)
+useRoute('/blog/:year(\\d+)/:month(\\d+)');
+
+// Функция-матчер (иерархия, кастомный разбор)
+const matchPost = (pathname: string) => ({ matched: pathname.startsWith('/posts/'), params: {} });
+useRoute(matchPost);
+```
+
+Полный синтаксис URLPattern: [URL Pattern API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API), [WHATWG URL Pattern](https://urlpattern.spec.whatwg.org/).
+
+**PathMatcher** — функция, которую можно передать вместо строки, когда одного URLPattern недостаточно (иерархия сегментов, кастомная валидация, разбор через `split` или RegExp). Хук вызывает её с текущим `pathname` и подставляет возвращённые `matched` и `params` в состояние.
+
+- **Параметр:** `pathname: string` — текущий pathname (без origin и query).
+- **Возвращаемый тип:** `{ matched: boolean; params: RouteParams }`.
+  `matched` — совпал ли путь с вашей логикой; `params` — объект «имя параметра → значение сегмента» (тип `RouteParams` = `Record<RouteParamName, RouteParamValue>`).
+- **Где использовать:** иерархические маршруты (например, `postId` только при наличии `userId`), пути с жёстким порядком сегментов, кастомные правила, которые не выразить одним URLPattern.
+
+## 🛠 Примеры
+
+### 1. Базовая навигация (pathname, navigate)
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function BasicNavigationExample() {
+    const { pathname, navigate } = useRoute();
+
+    return (
+        <div>
+            <p>Текущий путь: {pathname}</p>
+            <button type="button" onClick={() => navigate('/posts')}>
+                К постам
+            </button>
+            <button type="button" onClick={() => navigate('/')}>
+                На главную
+            </button>
+        </div>
+    );
+}
+```
+
+### 2. Параметры пути (useRoute('/users/:id'), params)
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function ParamsExample() {
+    const { params, pathname, navigate } = useRoute('/users/:id');
+
+    return (
+        <div>
+            <p>Pathname: {pathname}</p>
+            <p>User ID из params: {params.id ?? '—'}</p>
+            <button type="button" onClick={() => navigate('/users/123')}>
+                User 123
+            </button>
+            <button type="button" onClick={() => navigate('/users/456')}>
+                User 456
+            </button>
+        </div>
+    );
+}
+```
+
+### 3. Search params (query)
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function SearchParamsExample() {
+    const { searchParams, navigate, pathname } = useRoute('/posts');
+    const pageParam = searchParams.get('page') ?? '1';
+    const currentPage = Number.parseInt(pageParam, 10) || 1;
+
+    return (
+        <div>
+            <p>Путь: {pathname}</p>
+            <p>Страница: {currentPage}</p>
+            <button
+                type="button"
+                onClick={() => navigate(`/posts?page=${currentPage - 1}`)}
+                disabled={currentPage <= 1}
+            >
+                Пред. страница
+            </button>
+            <button type="button" onClick={() => navigate(`/posts?page=${currentPage + 1}`)}>
+                След. страница
+            </button>
+        </div>
+    );
+}
+```
+
+### 4. История (back, forward, go, canGoBack, canGoForward)
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function HistoryExample() {
+    const { go, back, forward, canGoBack, canGoForward } = useRoute();
+
+    return (
+        <div>
+            <button type="button" onClick={() => back()} disabled={!canGoBack()}>
+                ← Назад
+            </button>
+            <button type="button" onClick={() => go(-2)} disabled={!canGoBack(2)}>
+                ← 2 шага
+            </button>
+            <button type="button" onClick={() => go(1)} disabled={!canGoForward()}>
+                Вперёд →
+            </button>
+            <button type="button" onClick={() => forward()} disabled={!canGoForward()}>
+                Forward
+            </button>
+        </div>
+    );
+}
+```
+
+### 5. Push и replace (и метод replace())
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function PushReplaceExample() {
+    const { navigate, replace, pathname } = useRoute();
+
+    return (
+        <div>
+            <p>Текущий путь: {pathname}</p>
+            <button type="button" onClick={() => navigate('/step-push', { history: 'push' })}>
+                Перейти (push) — в истории появится запись
+            </button>
+            <button type="button" onClick={() => navigate('/step-replace', { history: 'replace' })}>
+                Перейти (replace через navigate)
+            </button>
+            <button type="button" onClick={() => replace('/step-replace-method')}>
+                Перейти через replace() — то же, что history: 'replace'
+            </button>
+        </div>
+    );
+}
+```
+
+### 6. matched (совпадение pathname с pattern)
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+function MatchedExample() {
+    const { pathname, matched, params } = useRoute('/users/:id');
+
+    return (
+        <div>
+            <p>Pathname: {pathname}</p>
+            <p>Pattern /users/:id совпал: {matched === true ? 'да' : 'нет'}</p>
+            {matched === true ? (
+                <p>User ID: {params.id}</p>
+            ) : (
+                <p>Это не страница пользователя (path не совпал с /users/:id).</p>
+            )}
+        </div>
+    );
+}
+```
+
+### 7. Функция-матчер (PathMatcher)
+
+Удобно, когда один URLPattern или простой regex не справляется: иерархия (например, `postId` только вместе с `userId`), кастомная валидация, разный порядок сегментов. Ниже — матчер для `/users/:userId` и `/users/:userId/posts/:postId`: два параметра, причём `postId` допустим только после литерала `posts` и только при наличии `userId`.
+
+```tsx
+import { useRoute, type PathMatcher } from '@budarin/use-route';
+
+const matchUserPosts: PathMatcher = (pathname) => {
+    const segments = pathname.split('/').filter(Boolean);
+
+    if (segments[0] !== 'users' || !segments[1]) return { matched: false, params: {} };
+
+    const params: Record<string, string> = { userId: segments[1] };
+
+    if (segments[2] === 'posts' && segments[3]) {
+        params.postId = segments[3];
+    }
+
+    return { matched: true, params };
+};
+
+function UserPostsExample() {
+    const { pathname, matched, params } = useRoute(matchUserPosts);
+
+    if (!matched) return null;
+
+    return (
+        <div>
+            <p>Путь: {pathname}</p>
+            <p>User ID: {params.userId}</p>
+            {params.postId && <p>Post ID: {params.postId}</p>}
+        </div>
+    );
+}
+```
+
+### 8. Глобальный base (приложение по подпути, не в корне домена)
+
+Когда приложение располагается **не в корне домена**, а по подпути (например `https://example.com/app/` — все маршруты под `/app`), задайте в конфиге `base: '/app'`. Тогда `pathname` возвращается без префикса, а `navigate(to)` добавляет base к относительным путям. Для одноразового перехода «вне» этого пути (например на `/login`) используйте опцию `base` в `navigate` или `replace`: `navigate('/login', { base: '' })`.
+
+```tsx
+import { useRoute, configureRouter } from '@budarin/use-route';
+configureRouter({ base: '/app' });
+
+function AppUnderBase() {
+    const { pathname, navigate } = useRoute();
+
+    return (
+        <div>
+            <p>Текущий путь: {pathname}</p>
+
+            <button type="button" onClick={() => navigate('/dashboard')}>
+                В дашборд → /app/dashboard
+            </button>
+
+            <button type="button" onClick={() => navigate('/login', { base: '' })}>
+                На логин (/login)
+            </button>
+
+            <button type="button" onClick={() => navigate('/auth/profile', { base: '/auth' })}>
+                В другой раздел (/auth/profile)
+            </button>
+        </div>
+    );
+}
+```
+
+### 9. Локальный base в хуке (options.base)
+
+Когда у приложения несколько разделов по своим подпутям (`/dashboard`, `/admin`, `/auth`), в компонентах раздела можно задать **локальный** base: вызовите `useRoute({ base: '/dashboard' })` (один объект — опции без pattern). Тогда `pathname` возвращается без префикса раздела, а `navigate(to)` по умолчанию добавляет этот base — не нужно передавать `base` в каждый вызов `navigate`.
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+
+const DASHBOARD_BASE = '/dashboard';
+
+function DashboardSection() {
+    // Локальный base для раздела: pathname и navigate относительно /dashboard
+    const { pathname, navigate } = useRoute({ base: DASHBOARD_BASE });
+
+    return (
+        <div>
+            {/* При URL /dashboard/reports pathname === '/reports' */}
+            <p>Раздел Dashboard. Путь: {pathname}</p>
+            <button type="button" onClick={() => navigate('/reports')}>
+                Отчёты → /dashboard/reports
+            </button>
+            <button type="button" onClick={() => navigate('/settings')}>
+                Настройки → /dashboard/settings
+            </button>
+            {/* Переход вне раздела: свой base в вызове */}
+            <button type="button" onClick={() => navigate('/', { base: '' })}>
+                На главную
+            </button>
+        </div>
+    );
+}
+```
+
+### 10. initialLocation (SSR)
+
+При рендере на сервере нет `window`, поэтому хук не знает URL запроса. Задайте `initialLocation` в конфиге один раз перед рендером запроса (например `request.url`) — тогда `pathname` и `searchParams` будут соответствовать запросу. На клиенте `initialLocation` не используется.
+
+```tsx
+// Серверный обработчик (псевдокод: Express, Fastify, Next и т.д.)
+import { configureRouter } from '@budarin/use-route';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { App } from './App';
+
+function handleRequest(req, res) {
+    // Один раз перед рендером этого запроса
+    configureRouter({ initialLocation: req.url });
+
+    const html = renderToStaticMarkup(<App />);
+    res.send(html);
+}
+
+// В App компоненты используют useRoute() — на сервере получают pathname/searchParams из initialLocation
+function App() {
+    const { pathname, searchParams } = useRoute();
+    return (
+        <div>
+            <p>Pathname: {pathname}</p>
+            <p>Query: {searchParams.toString()}</p>
+        </div>
+    );
+}
+```
+
+### 11. Компонент Link (пример реализации)
+
+Минимальный пример компонента-ссылки поверх хука. Можно взять за основу и развивать под себя: активное состояние, префетч, аналитика, стили.
+
+```tsx
+import { useRoute } from '@budarin/use-route';
+import { useCallback, type ComponentPropsWithoutRef } from 'react';
+
+interface LinkProps extends ComponentPropsWithoutRef<'a'> {
+    to: string;
+    replace?: boolean;
+}
+
+function Link({ to, replace = false, onClick, ...props }: LinkProps) {
+    const { navigate } = useRoute();
+
+    const handleClick = useCallback(
+        (e: React.MouseEvent<HTMLAnchorElement>) => {
+            onClick?.(e);
+
+            if (!e.defaultPrevented) {
+                e.preventDefault();
+                navigate(to, { history: replace ? 'replace' : 'push' });
+            }
+        },
+        [navigate, to, replace, onClick]
+    );
+
+    return <a {...props} href={to} onClick={handleClick} />;
+}
+
+// Использование:
+// <Link to="/posts">Посты</Link>
+// <Link to="/users/123" replace>Профиль (replace)</Link>
+```
+
+## ⚙️ Установка
+
+```bash
+npm i @budarin/use-route
+
+pnpm add @budarin/use-route
+
+yarn add @budarin/use-route
+```
+
+TypeScript: типы включены.
+
+**`tsconfig.json` (рекомендуется):**
+
+```json
+{
+    "compilerOptions": {
+        "lib": ["ES2021", "DOM", "DOM.Iterable"],
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx"
+    }
+}
+```
+
+**Polyfills (опционально):**
+
+```bash
+npm i urlpattern-polyfill
+```
+
+```typescript
+// src/polyfills.ts
+import 'urlpattern-polyfill';
+```
+
+## 🌐 Браузеры и Node.js
+
+| API            | Chrome/Edge | Firefox | Safari | Node.js |
+| -------------- | ----------- | ------- | ------ | ------- |
+| Navigation API | 102+        | 109+    | 16.4+  | —       |
+| URLPattern     | 110+        | 115+    | 16.4+  | 23.8+   |
+
+Роутер рассчитан только на эти версии, fallback на History API нет.
+
+## 🎛 Под капотом
+
+- `useSyncExternalStore` на navigation события (`navigate`, `currententrychange`)
+- LRU кэш parsed URL (настраиваемый лимит)
+- Map для O(1) поиска `historyIndex`
+- URLPattern для `:params`
+- Кэш compiled patterns; `clearRouterCaches()` — очистка кэшей (тесты, смена окружения)
+- SSR-safe (checks `typeof window`)
+
+## 🤝 Лицензия
+
+MIT © budarin

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { PathMatcher, UseRouteReturn, UseRouteOptions } from './types';
+export { configureRouter, type LoggerLevel, type Logger, type NavigateOptions, type UseRouteOptions, type UseRouteReturn, type ExtractRouteParams, type ParamsForPath, type PathMatcher, type Pathname, type RouteParams, } from './types';
+/** Очищает кэши паттернов и URL. Для тестов или при смене base/origin. */
+export declare function clearRouterCaches(): void;
+/** Перегрузка: только опции (без pattern). Например useRoute({ base: '/dashboard' }). */
+export declare function useRoute(options: UseRouteOptions): UseRouteReturn;
+/** Перегрузка: pattern и опции. */
+export declare function useRoute<P extends string | PathMatcher>(pattern: P, options?: UseRouteOptions): UseRouteReturn<P>;
+/** Перегрузка: только pattern или без аргументов. */
+export declare function useRoute<P extends string | PathMatcher = string>(pattern?: P): UseRouteReturn<P>;
+//# sourceMappingURL=index.d.ts.map