@vlian/router 0.1.0 → 0.1.1

package/DESIGN.md

@@ -0,0 +1,848 @@
+# @vlian/router 设计文档
+
+本文档在 `README.md` 示例与快速上手之外，从**架构、三类路由（静态 / 动态 / 权限）、API 与类型**角度完整描述 `packages/router` 的实现契约，便于评审与二次封装。
+
+---
+
+## 文档索引
+
+
+| 你要做的事                            | 优先阅读                                                                |
+| -------------------------------- | ------------------------------------------------------------------- |
+| 判断 `@vlian/router` 是否适合当前项目      | [1. 目标与边界](#1-目标与边界)、[使用约束](#使用约束)                                  |
+| 接入静态路由、布局、重定向、元信息                | [3. 静态路由（详细）](#3-静态路由详细)、[9.1 仅静态路由](#91-仅静态路由含-redirectlayoutmeta) |
+| 接入后端菜单、权限路由或按需模块                 | [4. 动态路由（详细）](#4-动态路由详细)、[9.3 静态 + 动态 + 权限](#93-静态--动态--权限完整链路)     |
+| 统一登录态、权限码、无权限降级                  | [5. 权限路由（详细）](#5-权限路由详细)、[9.2 静态路由 + 权限](#92-静态路由--权限)              |
+| 查找公开导入路径和导出符号                    | [导出索引](#导出索引)、[6. 公开 API 一览](#6-公开-api-一览)                          |
+| 了解内部 normalize、patch、registry 契约 | [2. 模块分层与依赖关系](#2-模块分层与依赖关系)、[7. 内部导出](#7-内部导出vlianroutercore)      |
+| 按工程规范拆分路由模块                      | [接入规范](#接入规范)、[9.4 推荐目录拆分示例](#94-推荐目录拆分示例)                          |
+
+
+---
+
+## 1. 目标与边界
+
+
+| 目标             | 说明                                                                                        |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| 统一输入模型         | 业务只维护 `StaticRouteConfig` 树与可选的 `dynamic.loader`                                          |
+| 对接 Data Router | 基于 `react-router-dom` 的 `createBrowserRouter` / `createHashRouter` / `createMemoryRouter` |
+| 导航期动态注入        | 使用 `patchRoutesOnNavigation` 按需挂载动态路由，并与已注册 `id` 去重                                       |
+| 业务字段收口         | `meta`、`auth`、`redirect`、`layout` 在 normalize 与 Route Shell 中统一处理                         |
+
+
+
+| 非目标    | 说明                                                               |
+| ------ | ---------------------------------------------------------------- |
+| 替代权限中心 | `authorization` 只做前端展示/导航控制，安全边界仍在接口与后端                          |
+| 规定菜单协议 | 动态路由数据形态由业务接口决定，包只消费 `StaticRouteConfig[]` 或 `DynamicRoutePatch` |
+
+
+---
+
+## 使用约束
+
+`@vlian/router` 是对 `react-router-dom` Data Router 的业务封装。接入方应遵守下列约束，否则容易出现动态补丁失效、重复挂载、权限判断时序不稳定等问题。
+
+
+| 约束          | 要求                                                                               | 原因                                               |
+| ----------- | -------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Router 底座   | 仅面向 `react-router-dom@7` 的 Data Router；不支持 `BrowserRouter`/`HashRouter` 组件式包裹模式  | 动态注入依赖 `patchRoutesOnNavigation`                 |
+| Peer 依赖     | 消费端必须提供 `react`、`react-dom`、`react-router-dom`，包内不内置这些依赖                         | 避免多 React 实例和路由上下文冲突                             |
+| Router 生命周期 | `createAppRouter(options)` 产物应在应用启动期创建；使用 `AppRouterProvider` 时必须稳定 `options` 引用 | `options` 变化会重建整个 router，导致注册表、缓存与导航状态重置         |
+| 路由 id       | 被动态补丁挂载、菜单定位、面包屑、测试引用的路由必须手写稳定 `id`                                              | 自动 id 含同级位置，路由顺序变化会改变 id                         |
+| 动态父节点       | `dynamic.defaultParentId` 或 `DynamicRoutePatch.parentId` 指向的父路由必须已存在且 id 稳定      | React Router 的 `patch(parentId, routes)` 需要可定位父级 |
+| 动态路径        | 动态子路由挂到父路由下时，`path` 推荐使用相对片段，不要带前导 `/`                                           | 便于和父路由组成层级路径，避免和根路径语义混淆                          |
+| 动态加载        | `dynamic.loader` 必须尊重 `signal`，网络请求应传入 `{ signal }`；被取消的请求不应继续写外部状态              | 导航可中断，避免过期 patch 或竞态                             |
+| 权限判断        | `authorization.resolve` 必须是同步、快速、无副作用判断；异步权限拉取放在应用启动、loader 或 `dynamic.loader`   | Route Shell 渲染期不等待异步权限                           |
+| 安全边界        | 前端 `auth` 只做展示、导航与体验控制；接口访问控制仍必须由后端完成                                            | 前端路由不可作为安全边界                                     |
+| 自定义字段       | 业务扩展字段可放入配置对象，但不要和保留键重名；读取时优先通过 `route.__extra` 或 `handle.meta`                  | normalize 会把保留键用于内部转换                            |
+
+
+---
+
+## 接入规范
+
+### 模块组织
+
+应用侧不要把路由声明、动态加载、权限判断、store 读取、页面组件导入堆在同一个文件。推荐按职责拆分：
+
+
+| 文件                         | 职责                                                           |
+| -------------------------- | ------------------------------------------------------------ |
+| `routes/types.ts`          | 定义 `AppRouteMeta`、业务扩展字段、接口菜单类型                              |
+| `routes/static-routes.tsx` | 只声明基础静态路由树、布局、重定向和公共 meta                                    |
+| `routes/dynamic-loader.ts` | 只负责把后端菜单或本地模块映射成 `StaticRouteConfig[]`/`DynamicRoutePatch`   |
+| `routes/authorization.ts`  | 只负责同步权限判断、无权限跳转和降级视图                                         |
+| `routes/router.ts`         | 只组装 `createAppRouter` 或导出 provider 使用的 `RouterPluginOptions` |
+| `routes/index.ts`          | 可选，聚合对应用入口暴露的 router/options                                 |
+
+
+### 导入规范
+
+- 业务入口使用 `@vlian/router` 导入 `createAppRouter`、`defineRoutes` 和公开类型。
+- React 渲染入口使用 `@vlian/router/provider` 或 `@vlian/router/runtime` 导入 `AppRouterProvider`。
+- 测试、自定义适配器、调试工具才允许从 `@vlian/router/core` 导入 `normalizeRoutes`、`RouteRegistry`、`createNavigationPatcher`。
+- 只使用类型时写 `import type { ... } from "@vlian/router"`，避免引入不必要运行时代码。
+- 不从 `src/`** 或 `dist/**` 深路径导入，发布包只承诺 `exports` 中声明的入口稳定。
+
+### 命名与数据规范
+
+- 根布局推荐固定写 `id: "root"`；登录页写 `id: "login"`；动态业务页用后端稳定 code，例如 `system.user.list`。
+- 同一个 router 实例内 `id` 必须全局唯一，静态和动态路由共享同一注册表。
+- `meta` 放 UI 语义，例如 `title`、`icon`、`breadcrumb`、`hiddenInMenu`。
+- `auth` 放权限语义，例如 `required`、`permissionCode`、`redirectTo`。
+- 后端菜单原始字段不要直接散落到路由主文件；先在 `dynamic-loader.ts` 内转换为包消费的 `StaticRouteConfig`。
+- `redirect` 路由不应同时承载业务页面逻辑；需要业务判断时使用 RR `loader` 或页面组件自行处理。
+
+---
+
+## 2. 模块分层与依赖关系
+
+```text
+adapters/create-app-router.ts
+  ├── normalizeRoutes (静态 + 动态二次 normalize)
+  ├── RouteRegistry
+  ├── createNavigationPatcher (仅当 options.dynamic 存在)
+  └── createBrowserRouter | createHashRouter | createMemoryRouter
+
+core/normalize/normalize-routes.ts
+  ├── createRouteId
+  └── createRouteShellComponent (layout / auth / redirect / 纯 Outlet)
+
+core/patcher/create-navigation-patcher.ts
+  └── 调用 dynamic.loader → normalize → registry.filterUnregistered → patch
+
+runtime/AppRouterProvider.tsx
+  └── useMemo(createAppRouter) + RouterProvider
+```
+
+**导入路径约定**
+
+
+| 路径                                                 | 用途                                                                 |
+| -------------------------------------------------- | ------------------------------------------------------------------ |
+| `@vlian/router`                                    | `createAppRouter`、`defineRoutes` 及主入口类型                            |
+| `@vlian/router/runtime` 或 `@vlian/router/provider` | `AppRouterProvider`                                                |
+| `@vlian/router/core`                               | `normalizeRoutes`、`createNavigationPatcher`、`RouteRegistry`（高级/测试） |
+| `@vlian/router/types`                              | 仅类型                                                                |
+
+
+---
+
+## 导出索引
+
+### 包入口索引
+
+
+| 导入路径                     | 导出内容                                                                | 推荐场景                    |
+| ------------------------ | ------------------------------------------------------------------- | ----------------------- |
+| `@vlian/router`          | `createAppRouter`、`defineRoutes`、`AppRouterProviderProps` 类型、全部公开类型 | 应用侧默认入口                 |
+| `@vlian/router/provider` | `AppRouterProvider`、`AppRouterProviderProps`                        | React 应用入口直接渲染 provider |
+| `@vlian/router/runtime`  | 同 `provider`                                                        | 需要按运行时语义导入 provider 的场景 |
+| `@vlian/router/core`     | `normalizeRoutes`、`createNavigationPatcher`、`RouteRegistry`         | 单元测试、自定义适配器、调试          |
+| `@vlian/router/types`    | 全部类型导出                                                              | 类型集中导入或工具包复用            |
+
+
+### 主入口类型索引
+
+`@vlian/router` 主入口导出的类型按职责可分为：
+
+
+| 分类        | 类型                                                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Router 配置 | `RouterPluginOptions`、`AppRouterMode`                                                                                                         |
+| 静态路由      | `StaticRouteConfig`、`AppRouteObject`、`AppRouteHandle`、`DefaultRouteMeta`、`RouteExtraFields`                                                   |
+| 动态路由      | `DynamicRoutingOptions`、`DynamicRouteLoader`、`DynamicRouteLoaderContext`、`DynamicRouteLoadResult`、`DynamicRoutePatch`、`AppRoutePatchFunction` |
+| 权限        | `RouteAuthConfig`、`RouteAuthorizationOptions`、`RouteAuthorizationContext`、`RouteAuthorizationFallbackProps`                                   |
+| 布局        | `RouteLayout`、`RouteLayoutDescriptor`、`RouteLayoutProps`                                                                                      |
+| 重定向与懒加载   | `RouteRedirect`、`RedirectRouteConfig`、`RouteLazyLoader`                                                                                       |
+| 错误处理      | `RouterErrorHandler`、`RouterErrorHandlerContext`                                                                                              |
+
+
+---
+
+## 3. 静态路由（详细）
+
+静态路由指在 `createAppRouter({ routes })` 时一次性传入的 `StaticRouteConfig` 树，经 `normalizeRoutes(..., { source: "static" })` 转为 `AppRouteObject[]`。
+
+### 3.1 `StaticRouteConfig` 字段说明
+
+#### 与 `react-router-dom` 对齐的字段
+
+
+| 字段                                           | 类型                      | 说明                                                      |
+| -------------------------------------------- | ----------------------- | ------------------------------------------------------- |
+| `path`                                       | `string`                | 路径片段，规则同 RR                                             |
+| `index`                                      | `boolean`               | 索引路由                                                    |
+| `caseSensitive`                              | `boolean`               | 是否大小写敏感                                                 |
+| `component` / `Component`                    | 组件                      | 业务推荐写 `component`，normalize 会读 `Component ?? component` |
+| `element`                                    | `ReactNode`             | 与 component 二选一或组合（见 Route Shell）                       |
+| `lazy`                                       | `RouteLazyLoader`       | 懒加载路由模块                                                 |
+| `loader`                                     | `RouteObject["loader"]` | Data API                                                |
+| `action`                                     | `RouteObject["action"]` | 表单等                                                     |
+| `shouldRevalidate`                           | 同 RR                    |                                                         |
+| `errorElement` / `ErrorBoundary`             |                         | 错误边界                                                    |
+| `hydrateFallbackElement` / `HydrateFallback` |                         |                                                         |
+| `handle`                                     | `RouteObject["handle"]` | 会与内部合并进 `AppRouteHandle`                                |
+| `children`                                   | `StaticRouteConfig[]`   | 子路由                                                     |
+
+
+#### 包扩展字段
+
+
+| 字段         | 类型                | 说明                                                             |
+| ---------- | ----------------- | -------------------------------------------------------------- |
+| `id`       | `string`          | 可选；**显式 id 优先**。未提供时由 `createRouteId` 根据父 id、path/index、兄弟序号生成 |
+| `meta`     | `Meta`            | 写入 `handle.meta`，供面包屑、标题等使用                                    |
+| `layout`   | `RouteLayout`     | 函数或 `{ component, props }`，在 Shell 内包裹页面内容                     |
+| `auth`     | `RouteAuthConfig` | 是否参与鉴权及自定义字段（见第 5 节）                                           |
+| `redirect` | `RouteRedirect`   | 字符串或 `{ to, replace?, state? }`；字符串默认 `replace: true`          |
+
+
+#### `Extra` 扩展字段
+
+除上表「保留键」外，配置对象上**其余键**会落入 `AppRouteObject.__extra`，便于业务挂自定义标记而无需改包类型。
+
+保留键集合（不会进入 `__extra`）：`id`、`path`、`index`、`caseSensitive`、`component`、`Component`、`element`、`lazy`、`loader`、`action`、`shouldRevalidate`、`errorElement`、`ErrorBoundary`、`hydrateFallbackElement`、`HydrateFallback`、`handle`、`meta`、`layout`、`auth`、`redirect`、`children`。
+
+### 3.2 路由 id 生成规则（`createRouteId`）
+
+1. 若 `route.id` 为非空字符串（trim 后），**直接使用**。
+2. 否则：
+  - `index: true` → 段名为 `index`
+  - `path` 缺省或 `/` → 段名为 `root`
+  - 否则将 `path` 按 `/` 分段，每段规范化（小写、非字母数字转 `-`）后用 `.` 连接
+3. 最终：`无父` → `${selfId}.${position}`；`有父` → `${parentId}.${selfId}.${position}`（`position` 为同级下标）。
+
+**实践建议**：需要被 `dynamic.defaultParentId` 或 `DynamicRoutePatch.parentId` 引用的节点（如根布局）应**手写稳定 `id`**（如 `root`）。
+
+### 3.3 `handle` 合并结果（`AppRouteHandle`）
+
+normalize 后：
+
+- `handle.meta` = 配置的 `meta`
+- `handle.auth` = 配置的 `auth`
+- `handle.source` = `"static"` 或 `"dynamic"`（动态补丁进来的子树为 `"dynamic"`）
+
+原 `handle` 对象若为普通对象会展开合并。
+
+### 3.4 何时包一层 Route Shell（`needsRouteShell`）
+
+在存在 `redirect`，或 `layout`，或 **（`auth` 且提供了 `authorization`）**，或 **普通组件/元素路由** 等组合时，会用 `createRouteShellComponent` 包装。
+
+- **仅 `lazy` 路由**：在 `lazy` 解析完成后若需要 Shell，会把解析出的 `Component`/`element` 与原始 `auth`/`layout` 等一并传入 Shell。
+- **纯父级仅有 `children`** 且无 component/element/lazy 时，可能不包 Shell；有 `children` 的叶子在 Shell 内无内容时可渲染 `<Outlet />`（见 `renderRouteContent`）。
+
+### 3.5 `redirect` 行为
+
+- `redirect: "/login"` → 规范为 `{ to: "/login", replace: true }`
+- 对象形式默认 `replace: true`，可被覆盖
+- Shell 内优先渲染 `<Navigate />`，不渲染业务组件
+
+---
+
+## 4. 动态路由（详细）
+
+动态路由**不是**单独 API，而是通过 `RouterPluginOptions.dynamic` 启用：内部注册 `patchRoutesOnNavigation`（`createNavigationPatcher`）。
+
+### 4.1 触发时机与上下文
+
+每次导航时，React Router 可能调用 patch 函数，传入 `{ path, signal, matches, patch }`。本包构造：
+
+`DynamicRouteLoaderContext`
+
+
+| 字段              | 说明                                              |
+| --------------- | ----------------------------------------------- |
+| `path`          | 当前导航路径                                          |
+| `signal`        | `AbortSignal`，请求应传入以便取消                         |
+| `matches`       | 当前已匹配路由（类型为带 `AppRouteObject` 的 match）          |
+| `router`        | `DataRouter` 实例                                 |
+| `knownRouteIds` | **当前已注册**的所有路由 id 快照（含静态 + 已补丁动态），用于业务侧判断是否重复拉取 |
+
+
+### 4.2 `DynamicRoutingOptions`
+
+
+| 字段                      | 类型                              | 说明                                                                    |
+| ----------------------- | ------------------------------- | --------------------------------------------------------------------- |
+| `loader`                | `DynamicRouteLoader`            | **必填**，返回见下节                                                          |
+| `defaultParentId`       | `string` 或 `null`               | 当返回值未指定 `parentId` 时，作为 `patch(parentId, routes)` 的父节点 id             |
+| `getNavigationCacheKey` | `(context) => string` 或 `false` | 默认 `() => path`。返回的 key 用于**导航级去重**：同一 key 已处理则直接 return，不再调 `loader` |
+| `errorMode`             | `"silent"` 或 `"throw"`          | 默认 `silent`：`loader` 抛错时调用 `onError`，不向上抛；`throw` 时在 `onError` 后仍抛出   |
+
+
+### 4.3 `DynamicRouteLoader` 返回值（`DynamicRouteLoadResult`）
+
+
+| 返回值                   | 行为                                                     |
+| --------------------- | ------------------------------------------------------ |
+| `void` / `undefined`  | 不注入任何路由                                                |
+| `StaticRouteConfig[]` | 视为单个 patch：`{ parentId: defaultParentId, routes: 数组 }` |
+| `DynamicRoutePatch`   | 指定 `parentId`、`routes`，可选 `cacheKey`                   |
+| `DynamicRoutePatch[]` | 多次 patch，依次处理                                          |
+
+
+`DynamicRoutePatch`
+
+
+| 字段         | 说明                                                                               |
+| ---------- | -------------------------------------------------------------------------------- |
+| `parentId` | 挂到哪个父路由的 `children`；缺省用 `defaultParentId`                                        |
+| `routes`   | 一批静态配置（会再走 `normalizeRoutes`，`source: "dynamic"`）                                |
+| `cacheKey` | 若为非 `false`，该 patch 处理成功后会把此 key 加入**已解析集合**，后续相同 key 可跳过重复注入逻辑（与导航 cache 不同，见下） |
+
+
+### 4.4 去重与注册表（`RouteRegistry`）
+
+1. `normalizeRoutes` 后为每条路由生成稳定 `id`。
+2. `registry.filterUnregistered(routes)` **过滤掉 id 已存在的路由**，只把新 id 交给 `patch`。
+3. `registry.register` 把新 id 记入集合。
+
+因此同一动态路由**重复返回相同 id** 不会重复挂载。
+
+### 4.5 并发与 in-flight
+
+- 使用 `navigationCacheKey`（默认即 `path`）作为 key；若已有同 key 的加载任务在执行，后续导航会 **await 同一 Promise** 后返回，避免 thundering herd。
+- `navigationCacheKey === false` 时使用 `pending:${path}:${Date.now()}` 作为 in-flight key（几乎不合并）。
+
+### 4.6 错误处理（`onError`）
+
+`RouterErrorHandlerContext`：`DynamicRouteLoaderContext` 加上 `error` 与 `phase: "dynamic-route-loading"`。
+
+动态加载失败时：先 `await onError?.(context)`，再根据 `errorMode` 决定是否重新抛出。
+
+### 4.7 静态 vs 动态在 `handle.source` 上的差异
+
+- 初始 `routes` → `source: "static"`
+- `patch` 注入的配置 → `source: "dynamic"`
+
+若业务按 `handle.source` 区分埋点或调试，需知晓此约定。
+
+---
+
+## 5. 权限路由（详细）
+
+权限由两部分协作：**路由上的 `auth`** + **创建 Router 时的 `authorization`**。
+
+### 5.1 `RouteAuthConfig`
+
+
+| 形态                                                                    | 含义                                                    |
+| --------------------------------------------------------------------- | ----------------------------------------------------- |
+| `boolean`                                                             | `true`/`false` 简单开关（具体解释由 `authorization.resolve` 决定） |
+| `{ required?: boolean; redirectTo?: string; [key: string]: unknown }` | 可在对象上挂 `permissionCode` 等自定义字段，供 `resolve` 读取         |
+
+
+包**不**内置「必须登录」语义，一律通过 `authorization.resolve` 解释。
+
+### 5.2 `RouteAuthorizationOptions`
+
+
+| 字段             | 类型                                                             | 说明                                                   |
+| -------------- | -------------------------------------------------------------- | ---------------------------------------------------- |
+| `resolve`      | `(context: RouteAuthorizationContext) => boolean`              | **必填**。`context` 含 `route`（`AppRouteObject`）与 `auth` |
+| `redirectTo`   | `string`                                                       | 全局默认：无权限时跳转路径（可被路由级 `auth.redirectTo` 覆盖）            |
+| `renderDenied` | `ReactNode` 或 `ComponentType<RouteAuthorizationFallbackProps>` | 无权限且不跳转时渲染                                           |
+
+
+**判定顺序（`createRouteShellComponent`）**
+
+1. 若 `config.auth && config.authorization` 同时存在：
+  - `resolve({ route, auth }) === false` 时：
+    - 优先：若 `auth` 为对象且含 `redirectTo` 字符串 → 跳转该路径；
+    - 否则：若 `authorization.redirectTo` 为字符串 → 跳转；
+    - 否则：渲染 `renderDenied`（组件则传入 `{ route, auth }`），二者皆无则 `null`。
+2. 若**仅有** `auth` 而没有传入 `authorization`，Shell **不会**拦截（`auth` 仅写入 `handle` 供别处读取）。
+
+因此：**要做路由级权限拦截，必须同时配置 `auth` 与 `authorization`。**
+
+### 5.3 与动态路由的组合
+
+常见做法：接口返回的菜单/路由带上 `permissionCode`，动态 `normalize` 后每条路由带 `auth`，全局同一个 `authorization.resolve` 读全局 store 或 token 解析结果。
+
+异步拉取权限列表应在 `dynamic.loader` 或应用启动阶段完成；`resolve` 内建议只做同步判断。
+
+---
+
+## 6. 公开 API 一览
+
+### 6.1 `defineRoutes(routes)`
+
+
+| 参数       | 说明                                 |
+| -------- | ---------------------------------- |
+| `routes` | `StaticRouteConfig<Meta, Extra>[]` |
+
+
+**返回值**：原数组，类型收窄为 `StaticRouteConfig[]`。
+
+**作用**：仅 TypeScript 辅助，运行时为恒等函数。
+
+---
+
+### 6.2 `createAppRouter(options)`
+
+
+| 参数 `RouterPluginOptions`          | 说明                                  |
+| --------------------------------- | ----------------------------------- |
+| `routes`                          | **必填**，静态路由树                        |
+| `mode`                            | `"browser"`（默认）、`"hash"`、`"memory"` |
+| `basename`                        | 同 RR                                |
+| `future`                          | Memory/Browser/Hash 的 future 选项     |
+| `hydrationData`                   | 仅 memory/browser 等支持的 hydration     |
+| `getContext`                      | RR 7 `getContext`                   |
+| `dataStrategy`                    | RR 7 data strategy                  |
+| `initialEntries` / `initialIndex` | 仅 `memory`                          |
+| `window`                          | 自定义 `window`（测试或 iframe）            |
+| `dynamic`                         | 启用动态路由，见第 4 节                       |
+| `authorization`                   | 权限，见第 5 节                           |
+| `onError`                         | 动态加载阶段错误，见第 4.6 节                   |
+
+
+**返回值**：`DataRouter`，可直接给 `<RouterProvider router={...} />`。
+
+**实现要点**：先 `normalizeRoutes` 静态树并 `new RouteRegistry`；若存在 `dynamic`，则把 `createNavigationPatcher` 赋给 `patchRoutesOnNavigation`，并在 patcher 内持有 `getRouter()` 以拿到同一 `router` 实例。
+
+---
+
+### 6.3 `AppRouterProvider`（`@vlian/router/runtime`）
+
+
+| 属性        | 说明                                           |
+| --------- | -------------------------------------------- |
+| `options` | `RouterPluginOptions`，会传入 `createAppRouter`  |
+| 其余        | 透传 `RouterProvider` 的 props（**不含** `router`） |
+
+
+内部 `useMemo(() => createAppRouter(options), [options])`：`**options` 引用变化会重建整个 router**，生产环境建议 `useMemo` 稳定化 options 对象。
+
+---
+
+## 7. 内部导出（`@vlian/router/core`）
+
+适用于测试、调试或自有适配器。
+
+
+| 符号                                                                                  | 说明                                                                                                                   |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `normalizeRoutes(routes, options)`                                                  | `options`: `{ authorization?, parentId?, source }`；`source` 为 `"static"` 或 `"dynamic"`；动态补丁时传入父 `parentId` 以生成正确子 id |
+| `createNavigationPatcher({ dynamic, authorization, registry, getRouter, onError })` | 返回 RR 的 `PatchRoutesOnNavigationFunction`                                                                            |
+| `RouteRegistry`                                                                     | `isRegistered`、`register`、`filterUnregistered`、`snapshot`                                                            |
+
+
+---
+
+## 8. 类型别名速查
+
+
+| 类型                                | 用途                                                        |
+| --------------------------------- | --------------------------------------------------------- |
+| `AppRouteObject`                  | 带必选 `id`、可选 `children`、`handle`、`__extra` 的 `RouteObject` |
+| `AppRoutePatchFunction`           | 等价 RR 的 `PatchRoutesOnNavigationFunction`                 |
+| `RouteLayout`                     | 组件或 `{ component, props }`                                |
+| `RouteAuthorizationContext`       | `{ route, auth }`                                         |
+| `RouteAuthorizationFallbackProps` | 同 context，用于 `renderDenied` 组件 props                      |
+
+
+---
+
+## 9. 综合示例
+
+### 9.1 仅静态路由（含 redirect、layout、meta）
+
+```tsx
+import { Outlet } from "react-router-dom";
+import { defineRoutes } from "@vlian/router";
+
+function AppLayout(props: { children?: React.ReactNode; route: import("@vlian/router").AppRouteObject }) {
+  return (
+    <div>
+      <header>{String(props.route.handle?.meta?.title ?? "")}</header>
+      {props.children}
+    </div>
+  );
+}
+
+export const routes = defineRoutes([
+  {
+    id: "root",
+    path: "/",
+    component: Outlet,
+    layout: AppLayout,
+    meta: { title: "根" },
+    children: [
+      { index: true, redirect: "/home" },
+      {
+        path: "home",
+        id: "home",
+        component: () => <div>Home</div>,
+        meta: { title: "首页" },
+      },
+    ],
+  },
+]);
+```
+
+### 9.2 静态路由 + 权限
+
+```ts
+import { createAppRouter } from "@vlian/router";
+import { routes } from "./routes";
+
+export const router = createAppRouter({
+  routes,
+  authorization: {
+    resolve: ({ auth }) => {
+      if (auth === false || auth === undefined) return true;
+      if (auth === true) return Boolean(getToken());
+      if (typeof auth === "object" && auth.required === false) return true;
+      return hasPermission((auth as { code?: string }).code);
+    },
+    redirectTo: "/login",
+    renderDenied: () => <div>无权限</div>,
+  },
+});
+```
+
+路由上：
+
+```ts
+{ path: "admin", component: AdminPage, auth: { required: true, code: "admin" } }
+```
+
+### 9.3 静态 + 动态 + 权限（完整链路）
+
+```ts
+import { createAppRouter } from "@vlian/router";
+import type { DynamicRouteLoader } from "@vlian/router";
+import { routes } from "./routes";
+
+const dynamicLoader: DynamicRouteLoader = async ({ path, signal }) => {
+  if (!path.startsWith("/app")) return;
+
+  const res = await fetch("/api/menu-routes", { signal });
+  const data = await res.json();
+
+  return {
+    parentId: "root",
+    cacheKey: `menu:${data.version}`,
+    routes: data.items.map((item: { id: string; path: string; perm: string }) => ({
+      id: item.id,
+      path: item.path.replace(/^\//, ""),
+      auth: { required: true, code: item.perm },
+      lazy: async () => {
+        const mod = await import(`../pages/${item.id}.tsx`);
+        return { Component: mod.default };
+      },
+    })),
+  };
+};
+
+export const router = createAppRouter({
+  routes,
+  mode: "browser",
+  authorization: {
+    resolve: ({ auth }) => {
+      if (!auth || auth === false) return true;
+      const code = typeof auth === "object" ? auth.code : undefined;
+      return !code || usePermissionStore.getState().has(code);
+    },
+    redirectTo: "/login",
+  },
+  dynamic: {
+    defaultParentId: "root",
+    loader: dynamicLoader,
+    getNavigationCacheKey: ({ path }) => (path.startsWith("/app") ? path : false),
+    errorMode: "silent",
+  },
+  onError: ({ error, path }) => console.error(path, error),
+});
+```
+
+### 9.4 推荐目录拆分示例
+
+适用于中后台、低代码平台、权限菜单较多的应用。重点是让每个文件只承担一类职责。
+
+```text
+src/routes
+├── authorization.tsx
+├── dynamic-loader.ts
+├── index.ts
+├── router.ts
+├── static-routes.tsx
+└── types.ts
+```
+
+`routes/types.ts`
+
+```ts
+import type { RouteExtraFields } from "@vlian/router";
+
+export type AppRouteMeta = {
+  title?: string;
+  icon?: string;
+  hiddenInMenu?: boolean;
+  breadcrumb?: boolean;
+};
+
+export type AppRouteExtra = RouteExtraFields & {
+  menuCode?: string;
+  preload?: boolean;
+};
+
+export type MenuRouteItem = {
+  id: string;
+  path: string;
+  title: string;
+  component: string;
+  permissionCode?: string;
+};
+```
+
+`routes/static-routes.tsx`
+
+```tsx
+import { Outlet } from "react-router-dom";
+import { defineRoutes } from "@vlian/router";
+import type { AppRouteExtra, AppRouteMeta } from "./types";
+import { AppLayout } from "../layouts/AppLayout";
+import { LoginPage } from "../pages/login";
+
+export const staticRoutes = defineRoutes<AppRouteMeta, AppRouteExtra>([
+  {
+    id: "root",
+    path: "/",
+    component: Outlet,
+    layout: AppLayout,
+    meta: { title: "应用" },
+    children: [
+      {
+        index: true,
+        redirect: "/workspace",
+      },
+      {
+        id: "workspace",
+        path: "workspace",
+        lazy: async () => {
+          const mod = await import("../pages/workspace");
+          return { Component: mod.default };
+        },
+        meta: { title: "工作台", icon: "dashboard" },
+        auth: true,
+      },
+    ],
+  },
+  {
+    id: "login",
+    path: "/login",
+    component: LoginPage,
+    meta: { title: "登录", hiddenInMenu: true },
+  },
+]);
+```
+
+`routes/dynamic-loader.ts`
+
+```ts
+import type { DynamicRouteLoader } from "@vlian/router";
+import type { AppRouteExtra, AppRouteMeta, MenuRouteItem } from "./types";
+
+const normalizeChildPath = (path: string) => path.replace(/^\/+/, "");
+
+export const loadDynamicRoutes: DynamicRouteLoader<
+  AppRouteMeta,
+  AppRouteExtra
+> = async ({ path, signal, knownRouteIds }) => {
+  if (!path.startsWith("/system")) {
+    return;
+  }
+
+  const response = await fetch("/api/current-user/routes", { signal });
+  if (!response.ok) {
+    throw new Error(`load dynamic routes failed: ${response.status}`);
+  }
+
+  const data: { version: string; routes: MenuRouteItem[] } =
+    await response.json();
+
+  return {
+    parentId: "root",
+    cacheKey: `menu:${data.version}`,
+    routes: data.routes
+      .filter((item) => !knownRouteIds.has(item.id))
+      .map((item) => ({
+        id: item.id,
+        path: normalizeChildPath(item.path),
+        meta: {
+          title: item.title,
+          icon: "menu",
+        },
+        auth: item.permissionCode
+          ? { required: true, permissionCode: item.permissionCode }
+          : true,
+        menuCode: item.id,
+        lazy: async () => {
+          const mod = await import(`../pages/${item.component}.tsx`);
+          return { Component: mod.default, loader: mod.loader };
+        },
+      })),
+  };
+};
+```
+
+`routes/authorization.tsx`
+
+```tsx
+import type { RouteAuthorizationOptions } from "@vlian/router";
+import type { AppRouteExtra, AppRouteMeta } from "./types";
+import { authStore } from "../stores/auth-store";
+
+export const authorization: RouteAuthorizationOptions<
+  AppRouteMeta,
+  AppRouteExtra
+> = {
+  resolve: ({ auth }) => {
+    if (!auth || auth === false) {
+      return true;
+    }
+
+    if (auth === true) {
+      return authStore.getState().isLoggedIn;
+    }
+
+    if (auth.required === false) {
+      return true;
+    }
+
+    const permissionCode =
+      typeof auth.permissionCode === "string" ? auth.permissionCode : "";
+    return !permissionCode || authStore.getState().hasPermission(permissionCode);
+  },
+  redirectTo: "/login",
+  renderDenied: () => <div>无权限访问</div>,
+};
+```
+
+`routes/router.ts`
+
+```ts
+import { createAppRouter } from "@vlian/router";
+import { authorization } from "./authorization";
+import { loadDynamicRoutes } from "./dynamic-loader";
+import { staticRoutes } from "./static-routes";
+
+export const router = createAppRouter({
+  mode: "browser",
+  routes: staticRoutes,
+  authorization,
+  dynamic: {
+    defaultParentId: "root",
+    loader: loadDynamicRoutes,
+    getNavigationCacheKey: ({ path }) =>
+      path.startsWith("/system") ? "system-menu" : false,
+    errorMode: "silent",
+  },
+  onError: ({ error, path }) => {
+    console.error("dynamic route load failed", path, error);
+  },
+});
+```
+
+### 9.5 `AppRouterProvider` 稳定 options 示例
+
+如果使用 `AppRouterProvider`，不要在 JSX 中每次 render 都创建新 `options` 对象。
+
+```tsx
+import { useMemo } from "react";
+import { AppRouterProvider } from "@vlian/router/provider";
+import type { RouterPluginOptions } from "@vlian/router";
+import { authorization } from "./routes/authorization";
+import { loadDynamicRoutes } from "./routes/dynamic-loader";
+import { staticRoutes } from "./routes/static-routes";
+import type { AppRouteExtra, AppRouteMeta } from "./routes/types";
+
+export function App() {
+  const routerOptions = useMemo<
+    RouterPluginOptions<AppRouteMeta, AppRouteExtra>
+  >(
+    () => ({
+      mode: "browser",
+      routes: staticRoutes,
+      authorization,
+      dynamic: {
+        defaultParentId: "root",
+        loader: loadDynamicRoutes,
+      },
+    }),
+    [],
+  );
+
+  return <AppRouterProvider options={routerOptions} />;
+}
+```
+
+### 9.6 多父节点动态补丁示例
+
+当后端一次返回多组菜单，需要分别挂到不同布局或不同模块父节点时，`dynamic.loader` 可以返回 `DynamicRoutePatch[]`。
+
+```ts
+import type { DynamicRouteLoader } from "@vlian/router";
+
+export const loadModuleRoutes: DynamicRouteLoader = async ({ signal }) => {
+  const response = await fetch("/api/module-routes", { signal });
+  const data = await response.json();
+
+  return [
+    {
+      parentId: "root",
+      cacheKey: `workspace:${data.version}`,
+      routes: data.workspace.map((item: any) => ({
+        id: item.id,
+        path: item.path.replace(/^\/+/, ""),
+        meta: { title: item.title },
+        lazy: async () => {
+          const mod = await import(`../pages/${item.component}.tsx`);
+          return { Component: mod.default };
+        },
+      })),
+    },
+    {
+      parentId: "admin",
+      cacheKey: `admin:${data.version}`,
+      routes: data.admin.map((item: any) => ({
+        id: item.id,
+        path: item.path.replace(/^\/+/, ""),
+        auth: { required: true, permissionCode: item.permissionCode },
+        meta: { title: item.title },
+        lazy: async () => {
+          const mod = await import(`../pages/admin/${item.component}.tsx`);
+          return { Component: mod.default };
+        },
+      })),
+    },
+  ];
+};
+```
+
+---
+
+## 10. 行为小结表
+
+
+| 主题   | 要点                                                                                     |
+| ---- | -------------------------------------------------------------------------------------- |
+| 静态路由 | `StaticRouteConfig` → `normalizeRoutes` → `id` / `handle` / 可选 Shell                   |
+| 动态路由 | `dynamic.loader` → patch 结果 → 仅注册新 `id` → `handle.source === "dynamic"`                |
+| 权限路由 | 同时配置 `auth` + `authorization`；拒绝时 `auth.redirectTo` > 全局 `redirectTo` > `renderDenied` |
+| 缓存   | 导航级：`getNavigationCacheKey`；patch 级：`DynamicRoutePatch.cacheKey`                       |
+
+
+---
+
+## 11. 与 README 的关系
+
+- **README**：安装、快速开始、长示例、预加载与发布说明。
+- **DESIGN.md**（本文）：三类路由语义、全部选项与内部方法契约，便于架构评审与封装扩展。
+

package/dist/core/normalize/normalize-routes.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"normalizeRoutes",{enumerable:true,get:function(){return normalizeRoutes}});const _routeshell=require("../guards/route-shell");const _routeid=require("./route-id");const RESERVED_ROUTE_KEYS=new Set(["id","path","index","caseSensitive","component","Component","element","lazy","loader","action","shouldRevalidate","errorElement","ErrorBoundary","hydrateFallbackElement","HydrateFallback","handle","meta","layout","auth","redirect","children"]);const isRecord=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const mergeHandle=(handle,meta,auth,source)=>{const baseHandle=isRecord(handle)?handle:{};return{...baseHandle,meta,auth,source}};const pickExtraFields=route=>{const extraEntries=Object.entries(route).filter(([key])=>!RESERVED_ROUTE_KEYS.has(key));return Object.fromEntries(extraEntries)};const normalizeRedirect=redirect=>{if(!redirect){return undefined}if(typeof redirect==="string"){return{to:redirect,replace:true}}return{replace:true,...redirect}};const needsRouteShell=(route,normalizedRedirect,authorization)=>Boolean(normalizedRedirect||route.layout||route.auth&&authorization||route.component||route.Component&&(route.layout||route.auth)||route.element!==undefined&&(route.layout||route.auth));const wrapLazyRoute=(lazy,routeRef,route,normalizedRedirect,authorization)=>{return async()=>{const resolved=await lazy();const component=resolved.Component??route.Component??route.component;const element=resolved.element??route.element;if(!needsRouteShell({...route,Component:component,element},normalizedRedirect,authorization)){return resolved}return{...resolved,Component:(0,_routeshell.createRouteShellComponent)({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element}),element:undefined}}};const normalizeRoute=(route,index,parentId,options)=>{const routeId=(0,_routeid.createRouteId)(route,parentId,index);const normalizedRedirect=normalizeRedirect(route.redirect);const handle=mergeHandle(route.handle,route.meta,route.auth,options.source);const normalizedRoute={id:routeId,path:route.path,index:route.index,caseSensitive:route.caseSensitive,loader:route.loader,action:route.action,shouldRevalidate:route.shouldRevalidate,errorElement:route.errorElement,ErrorBoundary:route.ErrorBoundary,hydrateFallbackElement:route.hydrateFallbackElement,HydrateFallback:route.HydrateFallback,handle,__extra:pickExtraFields(route)};if(route.children?.length){normalizedRoute.children=route.children.map((child,childIndex)=>normalizeRoute(child,childIndex,routeId,options))}if(route.lazy){normalizedRoute.lazy=wrapLazyRoute(route.lazy,normalizedRoute,route,normalizedRedirect,options.authorization);return normalizedRoute}const component=route.Component??route.component;const element=route.element;if(needsRouteShell(route,normalizedRedirect,options.authorization)){normalizedRoute.Component=(0,_routeshell.createRouteShellComponent)({route:normalizedRoute,redirect:normalizedRedirect,auth:route.auth,authorization:options.authorization,layout:route.layout,component,element});return normalizedRoute}if(component){normalizedRoute.Component=component}if(element!==undefined){normalizedRoute.element=element}return normalizedRoute};const normalizeRoutes=(routes,options)=>routes.map((route,index)=>normalizeRoute(route,index,options.parentId??null,options));
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"normalizeRoutes",{enumerable:true,get:function(){return normalizeRoutes}});const _routeshell=require("../guards/route-shell");const _routeid=require("./route-id");const RESERVED_ROUTE_KEYS=new Set(["id","path","index","caseSensitive","component","Component","element","lazy","middleware","loader","action","shouldRevalidate","errorElement","ErrorBoundary","hydrateFallbackElement","HydrateFallback","handle","meta","layout","auth","redirect","children"]);const isRecord=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const mergeHandle=(handle,meta,auth,source)=>{const baseHandle=isRecord(handle)?handle:{};return{...baseHandle,meta,auth,source}};const pickExtraFields=route=>{const extraEntries=Object.entries(route).filter(([key])=>!RESERVED_ROUTE_KEYS.has(key));return Object.fromEntries(extraEntries)};const normalizeRedirect=redirect=>{if(!redirect){return undefined}if(typeof redirect==="string"){return{to:redirect,replace:true}}return{replace:true,...redirect}};const needsRouteShell=(route,normalizedRedirect,authorization)=>Boolean(normalizedRedirect||route.layout||route.auth&&authorization||route.component||route.Component&&(route.layout||route.auth)||route.element!==undefined&&(route.layout||route.auth));const wrapLazyRoute=(lazy,routeRef,route,normalizedRedirect,authorization)=>{if(typeof lazy!=="function"){if(!needsRouteShell(route,normalizedRedirect,authorization)){return lazy}const{Component:loadComponent,element:loadElement,...restLazy}=lazy;return{...restLazy,Component:async()=>{const component=loadComponent?await loadComponent():route.Component??route.component;const element=loadElement?await loadElement():route.element;return(0,_routeshell.createRouteShellComponent)({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element})}}}return async()=>{const resolved=await lazy();const component=resolved.Component??route.Component??route.component;const element=resolved.element??route.element;if(!needsRouteShell({...route,Component:component,element},normalizedRedirect,authorization)){return resolved}return{...resolved,Component:(0,_routeshell.createRouteShellComponent)({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element}),element:undefined}}};const normalizeRoute=(route,index,parentId,options)=>{const routeId=(0,_routeid.createRouteId)(route,parentId,index);const normalizedRedirect=normalizeRedirect(route.redirect);const handle=mergeHandle(route.handle,route.meta,route.auth,options.source);const normalizedRoute={id:routeId,path:route.path,index:route.index,caseSensitive:route.caseSensitive,middleware:route.middleware,loader:route.loader,action:route.action,shouldRevalidate:route.shouldRevalidate,errorElement:route.errorElement,ErrorBoundary:route.ErrorBoundary,hydrateFallbackElement:route.hydrateFallbackElement,HydrateFallback:route.HydrateFallback,handle,__extra:pickExtraFields(route)};if(route.children?.length){normalizedRoute.children=route.children.map((child,childIndex)=>normalizeRoute(child,childIndex,routeId,options))}if(route.lazy){normalizedRoute.lazy=wrapLazyRoute(route.lazy,normalizedRoute,route,normalizedRedirect,options.authorization);return normalizedRoute}const component=route.Component??route.component;const element=route.element;if(needsRouteShell(route,normalizedRedirect,options.authorization)){normalizedRoute.Component=(0,_routeshell.createRouteShellComponent)({route:normalizedRoute,redirect:normalizedRedirect,auth:route.auth,authorization:options.authorization,layout:route.layout,component,element});return normalizedRoute}if(component){normalizedRoute.Component=component}if(element!==undefined){normalizedRoute.element=element}return normalizedRoute};const normalizeRoutes=(routes,options)=>routes.map((route,index)=>normalizeRoute(route,index,options.parentId??null,options));

package/dist/core/normalize/normalize-routes.js

@@ -1 +1 @@
-import{createRouteShellComponent}from"../guards/route-shell";import{createRouteId}from"./route-id";const RESERVED_ROUTE_KEYS=new Set(["id","path","index","caseSensitive","component","Component","element","lazy","loader","action","shouldRevalidate","errorElement","ErrorBoundary","hydrateFallbackElement","HydrateFallback","handle","meta","layout","auth","redirect","children"]);const isRecord=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const mergeHandle=(handle,meta,auth,source)=>{const baseHandle=isRecord(handle)?handle:{};return{...baseHandle,meta,auth,source}};const pickExtraFields=route=>{const extraEntries=Object.entries(route).filter(([key])=>!RESERVED_ROUTE_KEYS.has(key));return Object.fromEntries(extraEntries)};const normalizeRedirect=redirect=>{if(!redirect){return undefined}if(typeof redirect==="string"){return{to:redirect,replace:true}}return{replace:true,...redirect}};const needsRouteShell=(route,normalizedRedirect,authorization)=>Boolean(normalizedRedirect||route.layout||route.auth&&authorization||route.component||route.Component&&(route.layout||route.auth)||route.element!==undefined&&(route.layout||route.auth));const wrapLazyRoute=(lazy,routeRef,route,normalizedRedirect,authorization)=>{return async()=>{const resolved=await lazy();const component=resolved.Component??route.Component??route.component;const element=resolved.element??route.element;if(!needsRouteShell({...route,Component:component,element},normalizedRedirect,authorization)){return resolved}return{...resolved,Component:createRouteShellComponent({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element}),element:undefined}}};const normalizeRoute=(route,index,parentId,options)=>{const routeId=createRouteId(route,parentId,index);const normalizedRedirect=normalizeRedirect(route.redirect);const handle=mergeHandle(route.handle,route.meta,route.auth,options.source);const normalizedRoute={id:routeId,path:route.path,index:route.index,caseSensitive:route.caseSensitive,loader:route.loader,action:route.action,shouldRevalidate:route.shouldRevalidate,errorElement:route.errorElement,ErrorBoundary:route.ErrorBoundary,hydrateFallbackElement:route.hydrateFallbackElement,HydrateFallback:route.HydrateFallback,handle,__extra:pickExtraFields(route)};if(route.children?.length){normalizedRoute.children=route.children.map((child,childIndex)=>normalizeRoute(child,childIndex,routeId,options))}if(route.lazy){normalizedRoute.lazy=wrapLazyRoute(route.lazy,normalizedRoute,route,normalizedRedirect,options.authorization);return normalizedRoute}const component=route.Component??route.component;const element=route.element;if(needsRouteShell(route,normalizedRedirect,options.authorization)){normalizedRoute.Component=createRouteShellComponent({route:normalizedRoute,redirect:normalizedRedirect,auth:route.auth,authorization:options.authorization,layout:route.layout,component,element});return normalizedRoute}if(component){normalizedRoute.Component=component}if(element!==undefined){normalizedRoute.element=element}return normalizedRoute};export const normalizeRoutes=(routes,options)=>routes.map((route,index)=>normalizeRoute(route,index,options.parentId??null,options));
+import{createRouteShellComponent}from"../guards/route-shell";import{createRouteId}from"./route-id";const RESERVED_ROUTE_KEYS=new Set(["id","path","index","caseSensitive","component","Component","element","lazy","middleware","loader","action","shouldRevalidate","errorElement","ErrorBoundary","hydrateFallbackElement","HydrateFallback","handle","meta","layout","auth","redirect","children"]);const isRecord=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const mergeHandle=(handle,meta,auth,source)=>{const baseHandle=isRecord(handle)?handle:{};return{...baseHandle,meta,auth,source}};const pickExtraFields=route=>{const extraEntries=Object.entries(route).filter(([key])=>!RESERVED_ROUTE_KEYS.has(key));return Object.fromEntries(extraEntries)};const normalizeRedirect=redirect=>{if(!redirect){return undefined}if(typeof redirect==="string"){return{to:redirect,replace:true}}return{replace:true,...redirect}};const needsRouteShell=(route,normalizedRedirect,authorization)=>Boolean(normalizedRedirect||route.layout||route.auth&&authorization||route.component||route.Component&&(route.layout||route.auth)||route.element!==undefined&&(route.layout||route.auth));const wrapLazyRoute=(lazy,routeRef,route,normalizedRedirect,authorization)=>{if(typeof lazy!=="function"){if(!needsRouteShell(route,normalizedRedirect,authorization)){return lazy}const{Component:loadComponent,element:loadElement,...restLazy}=lazy;return{...restLazy,Component:async()=>{const component=loadComponent?await loadComponent():route.Component??route.component;const element=loadElement?await loadElement():route.element;return createRouteShellComponent({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element})}}}return async()=>{const resolved=await lazy();const component=resolved.Component??route.Component??route.component;const element=resolved.element??route.element;if(!needsRouteShell({...route,Component:component,element},normalizedRedirect,authorization)){return resolved}return{...resolved,Component:createRouteShellComponent({route:routeRef,redirect:normalizedRedirect,auth:route.auth,authorization,layout:route.layout,component,element}),element:undefined}}};const normalizeRoute=(route,index,parentId,options)=>{const routeId=createRouteId(route,parentId,index);const normalizedRedirect=normalizeRedirect(route.redirect);const handle=mergeHandle(route.handle,route.meta,route.auth,options.source);const normalizedRoute={id:routeId,path:route.path,index:route.index,caseSensitive:route.caseSensitive,middleware:route.middleware,loader:route.loader,action:route.action,shouldRevalidate:route.shouldRevalidate,errorElement:route.errorElement,ErrorBoundary:route.ErrorBoundary,hydrateFallbackElement:route.hydrateFallbackElement,HydrateFallback:route.HydrateFallback,handle,__extra:pickExtraFields(route)};if(route.children?.length){normalizedRoute.children=route.children.map((child,childIndex)=>normalizeRoute(child,childIndex,routeId,options))}if(route.lazy){normalizedRoute.lazy=wrapLazyRoute(route.lazy,normalizedRoute,route,normalizedRedirect,options.authorization);return normalizedRoute}const component=route.Component??route.component;const element=route.element;if(needsRouteShell(route,normalizedRedirect,options.authorization)){normalizedRoute.Component=createRouteShellComponent({route:normalizedRoute,redirect:normalizedRedirect,auth:route.auth,authorization:options.authorization,layout:route.layout,component,element});return normalizedRoute}if(component){normalizedRoute.Component=component}if(element!==undefined){normalizedRoute.element=element}return normalizedRoute};export const normalizeRoutes=(routes,options)=>routes.map((route,index)=>normalizeRoute(route,index,options.parentId??null,options));

package/dist/types/route.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from "react";
-import type { DataRouter, LazyRouteFunction, MemoryRouterOpts, PatchRoutesOnNavigationFunction, RouteMatch, RouteObject } from "react-router-dom";
+import type { DataRouter, MemoryRouterOpts, PatchRoutesOnNavigationFunction, RouteMatch, RouteObject } from "react-router-dom";
 export type MaybePromise<T> = T | Promise<T>;
 export type AppRouterMode = "browser" | "hash" | "memory";
 export type DefaultRouteMeta = Record<string, unknown>;
@@ -36,7 +36,7 @@ export interface RouteLayoutDescriptor<Meta = DefaultRouteMeta, Extra extends Ro
 }
 export type RouteLayout<Meta = DefaultRouteMeta, Extra extends RouteExtraFields = RouteExtraFields> = ComponentType<RouteLayoutProps<Meta, Extra>> | RouteLayoutDescriptor<Meta, Extra>;
 export type RouteComponent = Exclude<RouteObject["Component"], undefined>;
-export type RouteLazyLoader = LazyRouteFunction<RouteObject>;
+export type RouteLazyLoader = Exclude<RouteObject["lazy"], undefined>;
 interface StaticRouteConfigBase<Meta = DefaultRouteMeta, Extra extends RouteExtraFields = RouteExtraFields> {
     id?: string;
     path?: string;
@@ -46,6 +46,7 @@ interface StaticRouteConfigBase<Meta = DefaultRouteMeta, Extra extends RouteExtr
     Component?: RouteComponent;
     element?: ReactNode;
     lazy?: RouteLazyLoader;
+    middleware?: RouteObject["middleware"];
     loader?: RouteObject["loader"];
     action?: RouteObject["action"];
     shouldRevalidate?: RouteObject["shouldRevalidate"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlian/router",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Business-friendly router wrapper built on react-router-dom",
   "license": "Apache-2.0",
   "author": "Secra Framework Contributors",
@@ -58,7 +58,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "DESIGN.md"
   ],
   "scripts": {
     "build": "npm run clean && npm run build:types && npm run build:esm && npm run build:cjs",
@@ -67,7 +68,8 @@
     "build:cjs": "swc src -d dist-temp --strip-leading-paths --config-file .swcrc.cjs && node scripts/rename-cjs.js && rm -rf dist-temp",
     "clean": "rm -rf dist dist-temp",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm version patch --no-git-tag-version",
+    "publish:dry-run": "npm run prepublishOnly && npm publish --dry-run --access public"
   },
   "peerDependencies": {
     "react": "^19.0.0",