@pactor-app/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pactor Contributors
+
+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,94 @@
+# @pactor-app/router
+
+[Pactor](https://github.com/426-330/pactor) 的路由模块：菜单模型与 MenuRegistry、极简路径匹配（PathMatcher）、导航桥接（NavigationBridge / MemoryNavigation）、@pactor-app/runtime RouterAdapter 桥接，以及 React Router 动态路由绑定（`<DynamicDslRoute>`）。
+
+菜单声明 `path` + `pageId`（不绑定 React 组件），Dynamic Router 把 URL 解析为 pageId 与路由上下文；页面资源加载（pageId → loadPage）由应用组合层串联，不在本包。
+
+## 安装
+
+```bash
+npm install @pactor-app/router
+# 或
+pnpm add @pactor-app/router
+```
+
+核心入口（`@pactor-app/router`）零 React 依赖，可纯 Node 使用与测试；React 绑定在独立子入口 `@pactor-app/router/react`，仅该子入口需要 peer 依赖 `react >=18` 与 `react-router-dom >=6`（开发基准为 react-router-dom v7，仅用 v6/v7 共有的稳定 API）。
+
+## 示例
+
+```ts
+import {
+  MenuRegistry,
+  MemoryNavigation,
+  createRouterAdapter,
+  resolveRoute,
+} from '@pactor-app/router';
+
+const registry = new MenuRegistry([
+  {
+    id: 'customer',
+    type: 'group',
+    title: '客户管理',
+    children: [
+      { id: 'customer-list', type: 'page', title: '客户列表', path: '/customers', pageId: 'customer-list' },
+      {
+        id: 'customer-edit', type: 'page', title: '编辑客户',
+        path: '/customers/:id/edit', pageId: 'customer-edit',
+        hidden: true, activeMenu: 'customer-list',
+      },
+    ],
+  },
+]);
+
+// 1. URL → RouteContext（隐藏详情页参与匹配，activeMenu 指向列表页）
+const route = resolveRoute(registry, { pathname: '/customers/123/edit', search: '?tab=risk' });
+// → { path, params: { id: '123' }, query: { tab: 'risk' }, pageId: 'customer-edit',
+//     menuId: 'customer-edit', activeMenu: 'customer-list' }
+
+// 2. 桥接 @pactor-app/runtime：DSL navigate 动作驱动导航
+const navigation = new MemoryNavigation();
+const runtime = createPageRuntime(pageDsl, {
+  router: createRouterAdapter(navigation), // navigate(to) → bridge.push(to)
+  route: { params: route.params, query: route.query }, // ${route.params.id} 可求值
+});
+```
+
+React 绑定（`@pactor-app/router/react`）：
+
+```tsx
+import { DynamicDslRoute, useReactRouterBridge } from '@pactor-app/router/react';
+import { Route, Routes } from 'react-router-dom';
+
+<Routes>
+  <Route
+    path="*"
+    element={
+      <DynamicDslRoute
+        registry={registry}
+        render={({ pageId, route }) => <DslPage pageId={pageId} route={route} />}
+        fallback={<NotFound />}
+        forbidden={<Forbidden />}
+        permissionChecker={permissionStore}
+      />
+    }
+  />
+</Routes>
+```
+
+## 功能一览
+
+- **MenuItem**：对齐设计文档第 30 节字段（id/type/title/icon/order/path/pageId/permission/hidden/disabled/external/target/keepAlive/badge/activeMenu/defaultOpen/breadcrumb/tab/children），`permission` 用 @pactor-app/core 的 `PermissionConfig`。
+- **MenuRegistry**：由菜单树构建可见菜单树（`tree()`，过滤 hidden）+ 扁平可路由条目列表（`list()`，非 group 且有 path，按 order 排序、未指定者保持声明顺序在后）；`findById`（含 group 与隐藏项）、`findByPath`（按 list() 顺序模式匹配，隐藏页参与，未命中 null）。
+- **PathMatcher**：`match(pattern, pathname)` 仅支持静态段与 `:param` 段，整路径精确匹配（段数一致），不支持 `*` 与可选段；`parseQuery(search)` 解析查询串；`resolveRoute(registry, location)` 产出 `RouteContext`（path/params/query/pageId/menuId/activeMenu，activeMenu 取菜单项 activeMenu ?? 自身 id）。
+- **NavigationBridge / MemoryNavigation**：`getLocation` / `push` / `replace` / `subscribe`（返回退订函数）；MemoryNavigation 为纯 Node 内存历史栈实现，另支持 `back()`。
+- **`createRouterAdapter(bridge)`**：结构化兼容 @pactor-app/runtime `RouterAdapter`，`navigate(to)` → `bridge.push(to)`。
+- **`<DynamicDslRoute>`**（子入口 `@pactor-app/router/react`）：useLocation 驱动重新解析——未命中渲染 `fallback`（404）、配置 `permissionChecker`（@pactor-app/permission `checkPagePermission` 守卫）且无权限渲染 `forbidden`（403），否则 `render({ pageId, route })`。
+- **`useReactRouterBridge()`**：把 useNavigate / useLocation 包装为 NavigationBridge（React Router 自身驱动重渲染，subscribe 为 no-op）。
+
+## 文档
+
+完整文档见 <https://github.com/426-330/pactor/tree/main/docs>（`pnpm docs:dev` 本地启动文档站）。
+
+## License
+
+[MIT](../../LICENSE)

package/dist/chunk-JY7Z55CR.js

@@ -0,0 +1,53 @@
+// src/path-matcher.ts
+function toSegments(path) {
+  return path.split("/").filter((segment) => segment.length > 0);
+}
+function match(pattern, pathname) {
+  const patternSegments = toSegments(pattern);
+  const pathSegments = toSegments(pathname);
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i += 1) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    if (patternSegment.startsWith(":")) {
+      params[patternSegment.slice(1)] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return { params };
+}
+function parseQuery(search) {
+  const query = {};
+  if (search === "" || search === "?") {
+    return query;
+  }
+  for (const [key, value] of new URLSearchParams(search)) {
+    query[key] = value;
+  }
+  return query;
+}
+function resolveRoute(registry, location) {
+  const hit = registry.findByPath(location.pathname);
+  if (hit === null) {
+    return null;
+  }
+  const { menu, params } = hit;
+  return {
+    path: location.pathname,
+    params,
+    query: parseQuery(location.search ?? ""),
+    pageId: menu.pageId,
+    menuId: menu.id,
+    activeMenu: menu.activeMenu ?? menu.id
+  };
+}
+
+export {
+  match,
+  parseQuery,
+  resolveRoute
+};

package/dist/index.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryNavigation: () => MemoryNavigation,
+  MenuRegistry: () => MenuRegistry,
+  createRouterAdapter: () => createRouterAdapter,
+  match: () => match,
+  parseQuery: () => parseQuery,
+  resolveRoute: () => resolveRoute
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/path-matcher.ts
+function toSegments(path) {
+  return path.split("/").filter((segment) => segment.length > 0);
+}
+function match(pattern, pathname) {
+  const patternSegments = toSegments(pattern);
+  const pathSegments = toSegments(pathname);
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i += 1) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    if (patternSegment.startsWith(":")) {
+      params[patternSegment.slice(1)] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return { params };
+}
+function parseQuery(search) {
+  const query = {};
+  if (search === "" || search === "?") {
+    return query;
+  }
+  for (const [key, value] of new URLSearchParams(search)) {
+    query[key] = value;
+  }
+  return query;
+}
+function resolveRoute(registry, location) {
+  const hit = registry.findByPath(location.pathname);
+  if (hit === null) {
+    return null;
+  }
+  const { menu, params } = hit;
+  return {
+    path: location.pathname,
+    params,
+    query: parseQuery(location.search ?? ""),
+    pageId: menu.pageId,
+    menuId: menu.id,
+    activeMenu: menu.activeMenu ?? menu.id
+  };
+}
+
+// src/menu.ts
+function filterHidden(items) {
+  const result = [];
+  for (const item of items) {
+    if (item.hidden) {
+      continue;
+    }
+    if (item.children !== void 0) {
+      result.push({ ...item, children: filterHidden(item.children) });
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+}
+function sortByOrder(items) {
+  return [...items].sort(
+    (a, b) => (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY)
+  );
+}
+var MenuRegistry = class {
+  constructor(menus) {
+    this.byId = /* @__PURE__ */ new Map();
+    this.visibleTree = filterHidden(menus);
+    const flat = [];
+    const walk = (items) => {
+      for (const item of items) {
+        this.byId.set(item.id, item);
+        if (item.type !== "group" && item.path !== void 0) {
+          flat.push(item);
+        }
+        if (item.children !== void 0) {
+          walk(item.children);
+        }
+      }
+    };
+    walk(menus);
+    this.entries = sortByOrder(flat);
+  }
+  /** 可见菜单树（过滤 hidden，供 layout 渲染） */
+  tree() {
+    return this.visibleTree;
+  }
+  /** 扁平可路由条目列表，按 order 排序（未指定者保持声明顺序在后） */
+  list() {
+    return this.entries;
+  }
+  /** 按 id 查找（含 group 与隐藏项），未找到返回 undefined */
+  findById(id) {
+    return this.byId.get(id);
+  }
+  /** 按 list() 顺序逐个模式匹配；隐藏页参与匹配；未命中返回 null */
+  findByPath(pathname) {
+    for (const menu of this.entries) {
+      const result = match(menu.path, pathname);
+      if (result !== null) {
+        return { menu, params: result.params };
+      }
+    }
+    return null;
+  }
+};
+
+// src/navigation.ts
+function splitTo(to) {
+  const queryIndex = to.indexOf("?");
+  if (queryIndex === -1) {
+    return { pathname: to, search: "" };
+  }
+  return { pathname: to.slice(0, queryIndex), search: to.slice(queryIndex) };
+}
+var MemoryNavigation = class {
+  constructor(initial = "/") {
+    this.index = 0;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.history = [splitTo(initial)];
+  }
+  getLocation() {
+    return this.history[this.index];
+  }
+  push(to) {
+    this.history = this.history.slice(0, this.index + 1);
+    this.history.push(splitTo(to));
+    this.index += 1;
+    this.notify();
+  }
+  replace(to) {
+    this.history[this.index] = splitTo(to);
+    this.notify();
+  }
+  /** 回退一步；已在栈底时不动作并返回 false */
+  back() {
+    if (this.index === 0) {
+      return false;
+    }
+    this.index -= 1;
+    this.notify();
+    return true;
+  }
+  /** 当前历史栈长度（调试与测试观察用） */
+  get size() {
+    return this.history.length;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    const location = this.getLocation();
+    for (const listener of [...this.listeners]) {
+      listener(location);
+    }
+  }
+};
+function createRouterAdapter(bridge) {
+  return {
+    navigate(to) {
+      bridge.push(to);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryNavigation,
+  MenuRegistry,
+  createRouterAdapter,
+  match,
+  parseQuery,
+  resolveRoute
+});

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+import { PermissionConfig } from '@pactor-app/core';
+
+/**
+ * 菜单项模型（设计文档第 30 节，决策 D1）。
+ *
+ * 菜单声明 `path` + `pageId`，不绑定 React 组件；Dynamic Router 把
+ * URL 解析为 pageId 与路由上下文。`keepAlive` / `tab` / `breadcrumb`
+ * 等 UI 语义字段由 @pactor-app/ui 的 layout 层消费，本包只保留字段与 activeMenu 解析。
+ */
+interface MenuItem {
+    id: string;
+    type: 'group' | 'page' | 'link';
+    title: string;
+    icon?: string;
+    order?: number;
+    path?: string;
+    pageId?: string;
+    /** 访问权限（@pactor-app/core PermissionConfig，守卫由 @pactor-app/permission 提供） */
+    permission?: PermissionConfig;
+    /** 隐藏页：不出现在可见菜单树，但参与路径匹配（详情页场景） */
+    hidden?: boolean;
+    disabled?: boolean;
+    external?: boolean;
+    target?: string;
+    keepAlive?: boolean;
+    badge?: string | number;
+    /** 高亮菜单 id：命中该项时高亮另一个菜单项（缺省为自身 id） */
+    activeMenu?: string;
+    defaultOpen?: boolean;
+    breadcrumb?: boolean;
+    tab?: boolean;
+    children?: MenuItem[];
+}
+/** findByPath 命中结果（`menu` 字段预留供 layout 推导面包屑等） */
+interface MenuPathMatch {
+    menu: MenuItem;
+    params: Record<string, string>;
+}
+/**
+ * MenuRegistry（决策 D2）：由菜单树构建，产出可见菜单树（过滤 hidden）
+ * + 扁平可路由条目列表（type 非 group 且有 path），并维护 id 索引。
+ *
+ * - `findByPath` 按 list() 顺序逐个做路径模式匹配，隐藏页参与匹配；
+ * - `findById` 覆盖全树（含 group 与隐藏项）。
+ */
+declare class MenuRegistry {
+    private readonly visibleTree;
+    private readonly entries;
+    private readonly byId;
+    constructor(menus: readonly MenuItem[]);
+    /** 可见菜单树（过滤 hidden，供 layout 渲染） */
+    tree(): MenuItem[];
+    /** 扁平可路由条目列表，按 order 排序（未指定者保持声明顺序在后） */
+    list(): MenuItem[];
+    /** 按 id 查找（含 group 与隐藏项），未找到返回 undefined */
+    findById(id: string): MenuItem | undefined;
+    /** 按 list() 顺序逐个模式匹配；隐藏页参与匹配；未命中返回 null */
+    findByPath(pathname: string): MenuPathMatch | null;
+}
+
+/** match 命中结果 */
+interface PathMatchResult {
+    params: Record<string, string>;
+}
+/**
+ * 路径模式匹配（决策 D3）：仅支持静态段与 `:param` 段
+ * （如 `/customers/:id/edit`），整路径精确匹配（段数一致）。
+ * V1 不支持 `*` 通配与可选段。
+ */
+declare function match(pattern: string, pathname: string): PathMatchResult | null;
+/**
+ * 解析查询串：`?tab=risk&page=2` → `{ tab: 'risk', page: '2' }`；
+ * 空字符串与裸 `?` 返回空对象。
+ */
+declare function parseQuery(search: string): Record<string, string>;
+/** 路由上下文（设计文档第 32 节，决策 D3） */
+interface RouteContext {
+    /** 当前 pathname */
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    pageId?: string;
+    menuId?: string;
+    /** 高亮菜单 id：菜单项 activeMenu ?? 自身 id */
+    activeMenu?: string;
+}
+/** resolveRoute 的入参位置（search 可省略，视为无查询串） */
+interface RouteLocation {
+    pathname: string;
+    search?: string;
+}
+/**
+ * 把当前位置解析为 RouteContext：findByPath 命中 →
+ * `{ path, params, query, pageId, menuId, activeMenu }`；未命中返回 null。
+ */
+declare function resolveRoute(registry: MenuRegistry, location: RouteLocation): RouteContext | null;
+
+/** 导航位置（pathname + search，search 含前导 `?` 或为空串） */
+interface NavigationLocation {
+    pathname: string;
+    search: string;
+}
+/** location 变化监听器 */
+type NavigationListener = (location: NavigationLocation) => void;
+/**
+ * 导航桥接抽象（决策 D4）：核心逻辑与具体路由库
+ * （React Router / hash / memory）解耦。
+ */
+interface NavigationBridge {
+    getLocation(): NavigationLocation;
+    push(to: string): void;
+    replace(to: string): void;
+    /** 订阅 location 变化，返回退订函数 */
+    subscribe(listener: NavigationListener): () => void;
+}
+/**
+ * MemoryNavigation（决策 D4）：零依赖内存导航，维护历史栈。
+ * push 追加历史（截断 forward 分支）、replace 替换当前、back 回退；
+ * 任何变化通知订阅者。可纯 Node 使用与测试。
+ */
+declare class MemoryNavigation implements NavigationBridge {
+    private history;
+    private index;
+    private readonly listeners;
+    constructor(initial?: string);
+    getLocation(): NavigationLocation;
+    push(to: string): void;
+    replace(to: string): void;
+    /** 回退一步；已在栈底时不动作并返回 false */
+    back(): boolean;
+    /** 当前历史栈长度（调试与测试观察用） */
+    get size(): number;
+    subscribe(listener: NavigationListener): () => void;
+    private notify;
+}
+/**
+ * runtime RouterAdapter 的结构化形状（与 @pactor-app/runtime 的 RouterAdapter
+ * 结构化兼容，避免对 @pactor-app/runtime 的运行时依赖；编译期断言见测试）。
+ */
+interface RouterAdapterLike {
+    navigate(to: string): void;
+}
+/**
+ * 桥接 @pactor-app/runtime 的 RouterAdapter（决策 D4）：DSL navigate 动作
+ * 经 runtime `route.navigate(to)` → `adapter.navigate(to)` → `bridge.push(to)`。
+ */
+declare function createRouterAdapter(bridge: NavigationBridge): RouterAdapterLike;
+
+export { MemoryNavigation, type MenuItem, type MenuPathMatch, MenuRegistry, type NavigationBridge, type NavigationListener, type NavigationLocation, type PathMatchResult, type RouteContext, type RouteLocation, type RouterAdapterLike, createRouterAdapter, match, parseQuery, resolveRoute };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { PermissionConfig } from '@pactor-app/core';
+
+/**
+ * 菜单项模型（设计文档第 30 节，决策 D1）。
+ *
+ * 菜单声明 `path` + `pageId`，不绑定 React 组件；Dynamic Router 把
+ * URL 解析为 pageId 与路由上下文。`keepAlive` / `tab` / `breadcrumb`
+ * 等 UI 语义字段由 @pactor-app/ui 的 layout 层消费，本包只保留字段与 activeMenu 解析。
+ */
+interface MenuItem {
+    id: string;
+    type: 'group' | 'page' | 'link';
+    title: string;
+    icon?: string;
+    order?: number;
+    path?: string;
+    pageId?: string;
+    /** 访问权限（@pactor-app/core PermissionConfig，守卫由 @pactor-app/permission 提供） */
+    permission?: PermissionConfig;
+    /** 隐藏页：不出现在可见菜单树，但参与路径匹配（详情页场景） */
+    hidden?: boolean;
+    disabled?: boolean;
+    external?: boolean;
+    target?: string;
+    keepAlive?: boolean;
+    badge?: string | number;
+    /** 高亮菜单 id：命中该项时高亮另一个菜单项（缺省为自身 id） */
+    activeMenu?: string;
+    defaultOpen?: boolean;
+    breadcrumb?: boolean;
+    tab?: boolean;
+    children?: MenuItem[];
+}
+/** findByPath 命中结果（`menu` 字段预留供 layout 推导面包屑等） */
+interface MenuPathMatch {
+    menu: MenuItem;
+    params: Record<string, string>;
+}
+/**
+ * MenuRegistry（决策 D2）：由菜单树构建，产出可见菜单树（过滤 hidden）
+ * + 扁平可路由条目列表（type 非 group 且有 path），并维护 id 索引。
+ *
+ * - `findByPath` 按 list() 顺序逐个做路径模式匹配，隐藏页参与匹配；
+ * - `findById` 覆盖全树（含 group 与隐藏项）。
+ */
+declare class MenuRegistry {
+    private readonly visibleTree;
+    private readonly entries;
+    private readonly byId;
+    constructor(menus: readonly MenuItem[]);
+    /** 可见菜单树（过滤 hidden，供 layout 渲染） */
+    tree(): MenuItem[];
+    /** 扁平可路由条目列表，按 order 排序（未指定者保持声明顺序在后） */
+    list(): MenuItem[];
+    /** 按 id 查找（含 group 与隐藏项），未找到返回 undefined */
+    findById(id: string): MenuItem | undefined;
+    /** 按 list() 顺序逐个模式匹配；隐藏页参与匹配；未命中返回 null */
+    findByPath(pathname: string): MenuPathMatch | null;
+}
+
+/** match 命中结果 */
+interface PathMatchResult {
+    params: Record<string, string>;
+}
+/**
+ * 路径模式匹配（决策 D3）：仅支持静态段与 `:param` 段
+ * （如 `/customers/:id/edit`），整路径精确匹配（段数一致）。
+ * V1 不支持 `*` 通配与可选段。
+ */
+declare function match(pattern: string, pathname: string): PathMatchResult | null;
+/**
+ * 解析查询串：`?tab=risk&page=2` → `{ tab: 'risk', page: '2' }`；
+ * 空字符串与裸 `?` 返回空对象。
+ */
+declare function parseQuery(search: string): Record<string, string>;
+/** 路由上下文（设计文档第 32 节，决策 D3） */
+interface RouteContext {
+    /** 当前 pathname */
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    pageId?: string;
+    menuId?: string;
+    /** 高亮菜单 id：菜单项 activeMenu ?? 自身 id */
+    activeMenu?: string;
+}
+/** resolveRoute 的入参位置（search 可省略，视为无查询串） */
+interface RouteLocation {
+    pathname: string;
+    search?: string;
+}
+/**
+ * 把当前位置解析为 RouteContext：findByPath 命中 →
+ * `{ path, params, query, pageId, menuId, activeMenu }`；未命中返回 null。
+ */
+declare function resolveRoute(registry: MenuRegistry, location: RouteLocation): RouteContext | null;
+
+/** 导航位置（pathname + search，search 含前导 `?` 或为空串） */
+interface NavigationLocation {
+    pathname: string;
+    search: string;
+}
+/** location 变化监听器 */
+type NavigationListener = (location: NavigationLocation) => void;
+/**
+ * 导航桥接抽象（决策 D4）：核心逻辑与具体路由库
+ * （React Router / hash / memory）解耦。
+ */
+interface NavigationBridge {
+    getLocation(): NavigationLocation;
+    push(to: string): void;
+    replace(to: string): void;
+    /** 订阅 location 变化，返回退订函数 */
+    subscribe(listener: NavigationListener): () => void;
+}
+/**
+ * MemoryNavigation（决策 D4）：零依赖内存导航，维护历史栈。
+ * push 追加历史（截断 forward 分支）、replace 替换当前、back 回退；
+ * 任何变化通知订阅者。可纯 Node 使用与测试。
+ */
+declare class MemoryNavigation implements NavigationBridge {
+    private history;
+    private index;
+    private readonly listeners;
+    constructor(initial?: string);
+    getLocation(): NavigationLocation;
+    push(to: string): void;
+    replace(to: string): void;
+    /** 回退一步；已在栈底时不动作并返回 false */
+    back(): boolean;
+    /** 当前历史栈长度（调试与测试观察用） */
+    get size(): number;
+    subscribe(listener: NavigationListener): () => void;
+    private notify;
+}
+/**
+ * runtime RouterAdapter 的结构化形状（与 @pactor-app/runtime 的 RouterAdapter
+ * 结构化兼容，避免对 @pactor-app/runtime 的运行时依赖；编译期断言见测试）。
+ */
+interface RouterAdapterLike {
+    navigate(to: string): void;
+}
+/**
+ * 桥接 @pactor-app/runtime 的 RouterAdapter（决策 D4）：DSL navigate 动作
+ * 经 runtime `route.navigate(to)` → `adapter.navigate(to)` → `bridge.push(to)`。
+ */
+declare function createRouterAdapter(bridge: NavigationBridge): RouterAdapterLike;
+
+export { MemoryNavigation, type MenuItem, type MenuPathMatch, MenuRegistry, type NavigationBridge, type NavigationListener, type NavigationLocation, type PathMatchResult, type RouteContext, type RouteLocation, type RouterAdapterLike, createRouterAdapter, match, parseQuery, resolveRoute };

package/dist/index.js

@@ -0,0 +1,137 @@
+import {
+  match,
+  parseQuery,
+  resolveRoute
+} from "./chunk-JY7Z55CR.js";
+
+// src/menu.ts
+function filterHidden(items) {
+  const result = [];
+  for (const item of items) {
+    if (item.hidden) {
+      continue;
+    }
+    if (item.children !== void 0) {
+      result.push({ ...item, children: filterHidden(item.children) });
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+}
+function sortByOrder(items) {
+  return [...items].sort(
+    (a, b) => (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY)
+  );
+}
+var MenuRegistry = class {
+  constructor(menus) {
+    this.byId = /* @__PURE__ */ new Map();
+    this.visibleTree = filterHidden(menus);
+    const flat = [];
+    const walk = (items) => {
+      for (const item of items) {
+        this.byId.set(item.id, item);
+        if (item.type !== "group" && item.path !== void 0) {
+          flat.push(item);
+        }
+        if (item.children !== void 0) {
+          walk(item.children);
+        }
+      }
+    };
+    walk(menus);
+    this.entries = sortByOrder(flat);
+  }
+  /** 可见菜单树（过滤 hidden，供 layout 渲染） */
+  tree() {
+    return this.visibleTree;
+  }
+  /** 扁平可路由条目列表，按 order 排序（未指定者保持声明顺序在后） */
+  list() {
+    return this.entries;
+  }
+  /** 按 id 查找（含 group 与隐藏项），未找到返回 undefined */
+  findById(id) {
+    return this.byId.get(id);
+  }
+  /** 按 list() 顺序逐个模式匹配；隐藏页参与匹配；未命中返回 null */
+  findByPath(pathname) {
+    for (const menu of this.entries) {
+      const result = match(menu.path, pathname);
+      if (result !== null) {
+        return { menu, params: result.params };
+      }
+    }
+    return null;
+  }
+};
+
+// src/navigation.ts
+function splitTo(to) {
+  const queryIndex = to.indexOf("?");
+  if (queryIndex === -1) {
+    return { pathname: to, search: "" };
+  }
+  return { pathname: to.slice(0, queryIndex), search: to.slice(queryIndex) };
+}
+var MemoryNavigation = class {
+  constructor(initial = "/") {
+    this.index = 0;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.history = [splitTo(initial)];
+  }
+  getLocation() {
+    return this.history[this.index];
+  }
+  push(to) {
+    this.history = this.history.slice(0, this.index + 1);
+    this.history.push(splitTo(to));
+    this.index += 1;
+    this.notify();
+  }
+  replace(to) {
+    this.history[this.index] = splitTo(to);
+    this.notify();
+  }
+  /** 回退一步；已在栈底时不动作并返回 false */
+  back() {
+    if (this.index === 0) {
+      return false;
+    }
+    this.index -= 1;
+    this.notify();
+    return true;
+  }
+  /** 当前历史栈长度（调试与测试观察用） */
+  get size() {
+    return this.history.length;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    const location = this.getLocation();
+    for (const listener of [...this.listeners]) {
+      listener(location);
+    }
+  }
+};
+function createRouterAdapter(bridge) {
+  return {
+    navigate(to) {
+      bridge.push(to);
+    }
+  };
+}
+export {
+  MemoryNavigation,
+  MenuRegistry,
+  createRouterAdapter,
+  match,
+  parseQuery,
+  resolveRoute
+};

package/dist/react.cjs

@@ -0,0 +1,104 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  DynamicDslRoute: () => DynamicDslRoute,
+  useReactRouterBridge: () => useReactRouterBridge
+});
+module.exports = __toCommonJS(react_exports);
+var import_permission = require("@pactor-app/permission");
+var import_react = require("react");
+var import_react_router_dom = require("react-router-dom");
+
+// src/path-matcher.ts
+function parseQuery(search) {
+  const query = {};
+  if (search === "" || search === "?") {
+    return query;
+  }
+  for (const [key, value] of new URLSearchParams(search)) {
+    query[key] = value;
+  }
+  return query;
+}
+function resolveRoute(registry, location) {
+  const hit = registry.findByPath(location.pathname);
+  if (hit === null) {
+    return null;
+  }
+  const { menu, params } = hit;
+  return {
+    path: location.pathname,
+    params,
+    query: parseQuery(location.search ?? ""),
+    pageId: menu.pageId,
+    menuId: menu.id,
+    activeMenu: menu.activeMenu ?? menu.id
+  };
+}
+
+// src/react.ts
+function DynamicDslRoute(props) {
+  const {
+    registry,
+    render,
+    fallback = null,
+    forbidden = null,
+    permissionChecker
+  } = props;
+  const location = (0, import_react_router_dom.useLocation)();
+  const hit = registry.findByPath(location.pathname);
+  const route = resolveRoute(registry, {
+    pathname: location.pathname,
+    search: location.search
+  });
+  if (hit === null || route === null || hit.menu.pageId === void 0) {
+    return fallback;
+  }
+  if (permissionChecker !== void 0 && !(0, import_permission.checkPagePermission)(hit.menu, permissionChecker)) {
+    return forbidden;
+  }
+  return render({ pageId: hit.menu.pageId, route });
+}
+function useReactRouterBridge() {
+  const navigate = (0, import_react_router_dom.useNavigate)();
+  const location = (0, import_react_router_dom.useLocation)();
+  const locationRef = (0, import_react.useRef)(location);
+  locationRef.current = location;
+  return (0, import_react.useMemo)(
+    () => ({
+      getLocation: () => ({
+        pathname: locationRef.current.pathname,
+        search: locationRef.current.search
+      }),
+      push: (to) => navigate(to),
+      replace: (to) => navigate(to, { replace: true }),
+      subscribe: () => () => {
+      }
+    }),
+    [navigate]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DynamicDslRoute,
+  useReactRouterBridge
+});

package/dist/react.d.cts

@@ -0,0 +1,41 @@
+import { PermissionChecker } from '@pactor-app/permission';
+import { ReactNode } from 'react';
+import { MenuRegistry, RouteContext, NavigationBridge } from './index.cjs';
+import '@pactor-app/core';
+
+/** 命中页面时 render 的入参 */
+interface RenderPageArgs {
+    pageId: string;
+    route: RouteContext;
+}
+/** DynamicDslRoute 的 props（决策 D5） */
+interface DynamicDslRouteProps {
+    registry: MenuRegistry;
+    /** 命中且有权限时渲染页面 */
+    render(page: RenderPageArgs): ReactNode;
+    /** 路径未命中（404）渲染内容，缺省为 null */
+    fallback?: ReactNode;
+    /** 无权限（403）渲染内容，缺省为 null */
+    forbidden?: ReactNode;
+    /** 权限判定（@pactor-app/permission PermissionChecker，直接传 PermissionStore 即可） */
+    permissionChecker?: PermissionChecker;
+}
+/**
+ * DynamicDslRoute（设计文档第 31 节，决策 D5），用法：
+ * `<Route path="*" element={<DynamicDslRoute registry={...} render={...} />} />`。
+ *
+ * useLocation 变化 → 重新解析：未命中（或命中项无 pageId）渲染 fallback；
+ * 配置了 permissionChecker 且页面无权限时渲染 forbidden（不调用 render）；
+ * 否则 `render({ pageId, route })`。
+ */
+declare function DynamicDslRoute(props: DynamicDslRouteProps): ReactNode;
+/**
+ * 把 React Router 的 useNavigate / useLocation 包装为 NavigationBridge
+ * （决策 D5）。仅用稳定 API，兼容 react-router-dom v6/v7。
+ *
+ * 注意：React Router 自身驱动组件重渲染，无裸事件源，故 subscribe
+ * 返回 no-op 退订函数；getLocation 始终返回当前渲染的 location。
+ */
+declare function useReactRouterBridge(): NavigationBridge;
+
+export { DynamicDslRoute, type DynamicDslRouteProps, type RenderPageArgs, useReactRouterBridge };

package/dist/react.d.ts

@@ -0,0 +1,41 @@
+import { PermissionChecker } from '@pactor-app/permission';
+import { ReactNode } from 'react';
+import { MenuRegistry, RouteContext, NavigationBridge } from './index.js';
+import '@pactor-app/core';
+
+/** 命中页面时 render 的入参 */
+interface RenderPageArgs {
+    pageId: string;
+    route: RouteContext;
+}
+/** DynamicDslRoute 的 props（决策 D5） */
+interface DynamicDslRouteProps {
+    registry: MenuRegistry;
+    /** 命中且有权限时渲染页面 */
+    render(page: RenderPageArgs): ReactNode;
+    /** 路径未命中（404）渲染内容，缺省为 null */
+    fallback?: ReactNode;
+    /** 无权限（403）渲染内容，缺省为 null */
+    forbidden?: ReactNode;
+    /** 权限判定（@pactor-app/permission PermissionChecker，直接传 PermissionStore 即可） */
+    permissionChecker?: PermissionChecker;
+}
+/**
+ * DynamicDslRoute（设计文档第 31 节，决策 D5），用法：
+ * `<Route path="*" element={<DynamicDslRoute registry={...} render={...} />} />`。
+ *
+ * useLocation 变化 → 重新解析：未命中（或命中项无 pageId）渲染 fallback；
+ * 配置了 permissionChecker 且页面无权限时渲染 forbidden（不调用 render）；
+ * 否则 `render({ pageId, route })`。
+ */
+declare function DynamicDslRoute(props: DynamicDslRouteProps): ReactNode;
+/**
+ * 把 React Router 的 useNavigate / useLocation 包装为 NavigationBridge
+ * （决策 D5）。仅用稳定 API，兼容 react-router-dom v6/v7。
+ *
+ * 注意：React Router 自身驱动组件重渲染，无裸事件源，故 subscribe
+ * 返回 no-op 退订函数；getLocation 始终返回当前渲染的 location。
+ */
+declare function useReactRouterBridge(): NavigationBridge;
+
+export { DynamicDslRoute, type DynamicDslRouteProps, type RenderPageArgs, useReactRouterBridge };

package/dist/react.js

@@ -0,0 +1,55 @@
+import {
+  resolveRoute
+} from "./chunk-JY7Z55CR.js";
+
+// src/react.ts
+import {
+  checkPagePermission
+} from "@pactor-app/permission";
+import { useMemo, useRef } from "react";
+import { useLocation, useNavigate } from "react-router-dom";
+function DynamicDslRoute(props) {
+  const {
+    registry,
+    render,
+    fallback = null,
+    forbidden = null,
+    permissionChecker
+  } = props;
+  const location = useLocation();
+  const hit = registry.findByPath(location.pathname);
+  const route = resolveRoute(registry, {
+    pathname: location.pathname,
+    search: location.search
+  });
+  if (hit === null || route === null || hit.menu.pageId === void 0) {
+    return fallback;
+  }
+  if (permissionChecker !== void 0 && !checkPagePermission(hit.menu, permissionChecker)) {
+    return forbidden;
+  }
+  return render({ pageId: hit.menu.pageId, route });
+}
+function useReactRouterBridge() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const locationRef = useRef(location);
+  locationRef.current = location;
+  return useMemo(
+    () => ({
+      getLocation: () => ({
+        pathname: locationRef.current.pathname,
+        search: locationRef.current.search
+      }),
+      push: (to) => navigate(to),
+      replace: (to) => navigate(to, { replace: true }),
+      subscribe: () => () => {
+      }
+    }),
+    [navigate]
+  );
+}
+export {
+  DynamicDslRoute,
+  useReactRouterBridge
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@pactor-app/router",
+  "version": "0.1.0",
+  "description": "Pactor router: menu registry, path matcher, navigation bridge and React Router dynamic route bindings",
+  "keywords": [
+    "pactor",
+    "dsl",
+    "server-driven-ui",
+    "router",
+    "menu"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/426-330/pactor.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://github.com/426-330/pactor/tree/main/packages/router",
+  "bugs": "https://github.com/426-330/pactor/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pactor-app/core": "0.1.0",
+    "@pactor-app/permission": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-router-dom": ">=6"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router-dom": "^7.18.2",
+    "@pactor-app/runtime": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}