@pactor-app/app 1.18.0 → 1.20.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { Registry, I18nMessages, PageDsl, DslSourceRef } from '@pactor-app/core';
+import { Registry, I18nMessages, PageDsl, DslSourceRef, DslNode } from '@pactor-app/core';
 import { InteractionProviderProps, OverlayHostProps, OverlayManager, UiBridge } from '@pactor-app/ui/interaction';
 import { LayoutRegistry, AdminLayoutConfig } from '@pactor-app/ui/layout';
 import { PermissionStore } from '@pactor-app/permission';
 import { BootstrapResource, DslResourceLoader } from '@pactor-app/resource';
-import { NavigationBridge, NavigationLocation, NavigationListener, MenuRegistry, RouteContext } from '@pactor-app/router';
+import { NavigationBridge, NavigationLocation, NavigationListener, MenuRegistry, RouteContext, MenuItem } from '@pactor-app/router';
 import { HttpRequestConfig, ActionHandler, ServiceHandler, HttpAdapter, PageRuntime, PermissionAdapter } from '@pactor-app/runtime';
 import * as react from 'react';
 import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
@@ -366,4 +366,263 @@ declare function createPactorPage(options?: PactorPageOptions): ComponentType<Pa
  */
 declare function PactorPage(props: PactorPageProps & PactorPageOptions): react.JSX.Element;
 
-export { Application, type ApplicationProps, type AuthTokenProvider, DslPageLoader, type DslPageLoaderProps, type PactorAppSession, type PactorApplication, type PactorApplicationHandle, type PactorApplicationOptions, type PactorHttpHooks, PactorPage, type PactorPageOptions, type PactorPageProps, type PactorRouterOptions, PageErrorBoundary, ReactRouterBinding, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, wrapHttpAdapter };
+/**
+ * SitemapApp 缺省动作（宿主 actions 同名覆盖）：
+ * 常见动作开箱即用，无需每个项目重复扩展。
+ *
+ * - app.reload：整页重载 / 跳转。登录 / 登出后 sitemap 端点需按新会话
+ *   重新裁剪内容（SPA 导航不触发重取），params.to 缺省跳 '/'
+ * - service.call：调用已注册服务（params.service 服务名，params.params
+ *   入参，表达式求值后传入）。request 动作仅覆盖 HTTP 出口，
+ *   服务层调用经此桥接
+ */
+declare const defaultSitemapActions: Record<string, ActionHandler>;
+
+/**
+ * Sitemap 对象结构（design/dynamic-page.md，方案 B）：
+ * 扁平 pages + 独立 menus + DSL 布局 layouts。
+ * 服务端按会话裁剪内容（匿名 / 角色），对象本身不为角色建模。
+ */
+/** 布局定义：DSL 描述外壳结构，PageOutlet 组件为页面内容出口。
+ * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明 */
+interface LayoutDsl {
+    dsl: string;
+    body: DslNode;
+}
+/** 页面定义：id 主键；pageDsl 缺省 → loadPage(id) 懒加载 */
+interface SitemapPageEntry {
+    id: string;
+    /** 页面 url，支持 /reports/:id 参数 */
+    path: string;
+    title: string;
+    /** 单页版本，参与缓存键 id@version */
+    version?: number;
+    /** 内联页面 DSL；缺省 = 懒加载 */
+    pageDsl?: PageDsl;
+}
+/** 菜单/路由条目：MenuItem + layout 引用 + public 标记。
+ * type: 'page' 且带 pageId 时，path / title 缺省从引用页面继承，
+ * 仅在导航与页面分叉时显式覆写；group / link 只出现在 menus 中 */
+interface SitemapMenuItem extends MenuItem {
+    /** 引用 layouts 的键；缺省用顶层 layout */
+    layout?: string;
+    /** 免登录可访问（登录/注册/落地页） */
+    public?: boolean;
+    children?: SitemapMenuItem[];
+}
+interface SitemapResource extends BootstrapResource {
+    /** 应用级缺省布局名，引用 layouts 的键 */
+    layout?: string;
+    /** 匿名访问控制：未登录访问非 public 页时重定向到 loginPath */
+    auth?: {
+        loginPath?: string;
+    };
+    layouts: Record<string, LayoutDsl>;
+    pages: SitemapPageEntry[];
+    menus: SitemapMenuItem[];
+}
+/** 可渲染路由匹配结果（resolveSitemapRoute 产物） */
+interface SitemapRouteMatch {
+    pageId: string;
+    layoutName: string;
+    /** 菜单高亮 key：activeMenu 指向的菜单项 path（缺省自身 path） */
+    highlightKey: string;
+    params: Record<string, string>;
+}
+
+interface FetchSitemapOptions {
+    /** fetch 实现（缺省全局 fetch；SSR / 测试可注入） */
+    fetcher?: typeof fetch;
+    /** 接口基准地址：sources 为相对路径时以此为基准补全 */
+    baseUrl?: string;
+    /** HTTP 钩子：与页面运行时同一套 request / response 加工 */
+    httpHooks?: PactorHttpHooks;
+}
+/**
+ * 拉取并合并多个 sitemap 源（design/dynamic-page.md）：
+ * pages / menus / layouts 按键合并（id / path 冲突后源覆盖前源并告警），
+ * app / user / permissions / auth 取第一个源。
+ */
+declare function fetchSitemap(sources: string[], options?: FetchSitemapOptions): Promise<SitemapResource>;
+
+interface SitemapLoaderOptions {
+    /** 懒加载页面端点（pages[].pageDsl 缺省时按 id 获取），缺省 /api/pages/{id} */
+    pageEndpoint?: (pageId: string) => string;
+    /** fetch 实现（缺省全局 fetch） */
+    fetcher?: typeof fetch;
+    /** 会话服务名（注入每个页面的 dataSource），缺省 'session.context' */
+    sessionService?: string;
+    /** 接口基准地址：pageEndpoint 返回相对路径时以此为基准补全 */
+    baseUrl?: string;
+    /** HTTP 钩子：与页面运行时同一套 request / response 加工 */
+    httpHooks?: PactorHttpHooks;
+}
+/**
+ * SitemapDslLoader（design/dynamic-page.md 落地影响 #1）：
+ * 内联 pageDsl 直接命中；缺省项经页面端点懒加载。
+ * 缓存键 id@version——同一版本只取一次。
+ * 每个页面注入 session dataSource（${data.session.*}），页面自行声明
+ * 同名 dataSource 时以页面为准。
+ */
+declare function createSitemapLoader(sitemap: SitemapResource, options?: SitemapLoaderOptions): DslResourceLoader;
+
+/** 路由解析结果：菜单命中情况 + 可渲染路由（404 判定） */
+interface SitemapRouteResolution {
+    /** 命中的菜单项（未命中为 null） */
+    menu: SitemapMenuItem | null;
+    /** 可渲染路由；菜单未命中或无 pageId（group / link）时为 null → 404 */
+    route: SitemapRouteMatch | null;
+}
+/**
+ * 路由解析（纯函数）：菜单命中、布局名、activeMenu 高亮 key 一次算清。
+ * 布局名解析链：menu.layout → 顶层 layout → layouts 首键。
+ * 高亮 key：activeMenu 指向其他菜单 id 时高亮该项（隐藏页场景），
+ * key 与 toSitemapNavItems 一致（path ?? id）。
+ */
+declare function resolveSitemapRoute(sitemap: SitemapResource, registry: MenuRegistry, pathname: string): SitemapRouteResolution;
+/** 守卫判定：放行或重定向 */
+type SitemapGuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    redirectTo: string;
+};
+interface SitemapGuardContext {
+    sitemap: SitemapResource;
+    pathname: string;
+    /** 命中的菜单项（未命中为 null） */
+    menu: SitemapMenuItem | null;
+}
+/** 访问守卫：每次路由变化时求值；返回重定向时组件执行 navigate */
+type SitemapGuard = (context: SitemapGuardContext) => SitemapGuardDecision;
+/**
+ * 缺省守卫（匿名访问控制）：未登录访问非 public 页（含未命中路径）→
+ * 重定向 auth.loginPath（缺省 /login）。
+ */
+declare const defaultSitemapGuard: SitemapGuard;
+
+/**
+ * SitemapApp（design/dynamic-page.md）：sitemap 驱动的动态页面应用组件。
+ * 简单配置即可实现动态页面。两种路由模式：
+ * - 纯前端 SPA：不传路由 props，内置浏览器路由（History API + popstate）；
+ * - 宿主路由（Next App Router / react-router / 任意宿主）：注入 pathname / navigate。
+ *
+ * ```tsx
+ * <SitemapApp
+ *   sources={['/api/sitemap']}
+ *   baseUrl="https://api.example.com"
+ *   pathname={usePathname()}
+ *   navigate={(to) => router.push(to)}
+ *   services={{ 'auth.login': login }}
+ * />
+ * ```
+ *
+ * baseUrl 可选：sources / pageEndpoint 只写相对路径时以此为基准补全。
+ *
+ * 内置：多源拉取合并、menus×pages 继承、MenuRegistry 路由解析、访问守卫
+ * （缺省匿名守卫：非 public 且无 user → navigate 到 auth.loginPath，
+ * 可经 guard prop 替换）、DSL 布局渲染
+ * （PageOutlet 页面出口 + SitemapMenu 选中态 / activeMenu 高亮）、
+ * 页面内联 / 懒加载（id@version 缓存）、session.context 服务桥
+ * （${data.session.*}）、缺省动作（app.reload / service.call）。
+ *
+ * 布局常驻：切换导航（同布局名）时仅 PageOutlet 内页面随路由重建。
+ */
+interface SitemapAppProps {
+    /** sitemap 接口 URL 列表（多源合并，冲突后源覆盖前源）；相对路径以 baseUrl 补全 */
+    sources: string[];
+    /** 接口基准地址：sources / pageEndpoint 中的相对路径以此为基准补全 */
+    baseUrl?: string;
+    /** 当前路径（宿主路由注入，如 Next usePathname）；缺省用内置浏览器路由 */
+    pathname?: string;
+    /** 站内导航实现（如 Next router.push）；http(s) 外链自动新标签打开；
+     * 缺省用内置浏览器路由（History API） */
+    navigate?: (to: string) => void;
+    /** 当前 query（DSL ${route.query.x} 可读）；缺省自 location.search 解析 */
+    query?: Record<string, string>;
+    /** 懒加载页面端点，缺省 /api/pages/{id} */
+    pageEndpoint?: SitemapLoaderOptions['pageEndpoint'];
+    /** 业务服务（auth.login 等）；session.context 由组件自动注册 */
+    services?: Record<string, ServiceHandler>;
+    /** 业务动作；框架内置 app.reload / service.call 默认值，同名覆盖 */
+    actions?: Record<string, ActionHandler>;
+    /** 业务组件（同名覆盖内建；PageOutlet / SitemapMenu 为布局保留名） */
+    components?: Record<string, unknown>;
+    /** HTTP 钩子：所有 HTTP 出口（sitemap 源 / 页面端点 / 页面运行时）的统一加工（跨域改写 / 拆包） */
+    httpAdapter?: PactorHttpHooks;
+    /** fetch 实现（缺省全局 fetch；SSR / 测试可注入） */
+    fetcher?: FetchSitemapOptions['fetcher'];
+    /** 访问守卫（缺省 defaultSitemapGuard：匿名访问非 public 页 → 重定向 auth.loginPath） */
+    guard?: SitemapGuard;
+    /** 会话服务名（缺省 session.context） */
+    sessionService?: string;
+    /** 加载中视图 */
+    loading?: ReactNode;
+    /** sitemap 加载失败视图 */
+    renderError?: (error: Error) => ReactNode;
+    /** 路由未命中视图 */
+    renderNotFound?: (path: string) => ReactNode;
+}
+declare function SitemapApp(props: SitemapAppProps): react.JSX.Element | null;
+
+/** createHttpHooks 配置 */
+interface CreateHttpHooksOptions {
+    /** 项目内代理前缀：传入后跨域绝对地址改写到此前缀（由宿主服务端
+     * 转发）；缺省不改写——服务端已开通 CORS，浏览器直连 */
+    proxyPrefix?: string;
+    /** 公共头注入（Authorization / 租户头等），对象或函数（每次请求求值） */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** 响应拆包：缺省按 { code, data, message } 包裹协议处理（拆出 data，
+     * 非 0 抛错）；后端不包裹时传 false 关闭 */
+    envelope?: boolean;
+}
+/**
+ * 默认 HTTP 钩子（常用协议开箱即用）：
+ * - request：缺省不改写地址（假定服务端已开通 CORS，浏览器直连）；
+ *   传 proxyPrefix 时跨域绝对地址（origin ≠ 页面源）改写到项目内
+ *   代理前缀（path + query 保留），由宿主服务端代理转发
+ *   （Vite server.proxy / Next rewrites / nginx）；可注入公共头
+ * - response：{ code, data, message } 包裹结构拆包为 data，非 0 抛错
+ *   （DSL 动作按失败处理）；非包裹结构原样透传
+ *
+ * 后端协议不同（包裹结构 / 错误码约定）时自行实现 PactorHttpHooks。
+ */
+declare function createHttpHooks(options?: CreateHttpHooksOptions): PactorHttpHooks;
+/**
+ * 把 PactorHttpHooks 包装到 fetcher 上：sitemap 源 / 页面端点等框架自发
+ * 请求与页面运行时走同一套 HTTP 加工（跨域改写 / 鉴权头 / 响应拆包）。
+ * response 钩子仅作用于 2xx（错误响应原样返回，由调用方判定 HTTP 错误）。
+ */
+declare function withHttpHooks(fetcher: typeof fetch, hooks?: PactorHttpHooks): typeof fetch;
+
+/**
+ * menus × pages 合并：type: 'page' 且带 pageId 的条目缺省从引用页面
+ * 继承 path / title（仅分叉时覆写）；group / link 原样透传。
+ * 产物可直接 new MenuRegistry(...) 做路由匹配。
+ */
+declare function mergeSitemapMenus(sitemap: SitemapResource): SitemapMenuItem[];
+/** ui Menu 组件 items 形态（可见菜单树 → 导航数据；key = 路径） */
+interface SitemapNavItem {
+    key: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    children?: SitemapNavItem[];
+}
+declare function toSitemapNavItems(menuTree: MenuItem[]): SitemapNavItem[];
+
+/**
+ * 会话上下文（session.context 服务返回值）：布局 / 页面 DSL 经
+ * service dataSource 消费（${data.session.*}）。
+ * 框架原生 user / menus 作用域属设计目标（design/dynamic-page.md
+ * 落地影响 #3），当前经服务桥实现。
+ */
+interface SitemapSessionContext {
+    user?: Record<string, unknown>;
+    app: Record<string, unknown>;
+    menus: SitemapNavItem[];
+}
+/** 注册会话桥服务（缺省名 session.context，与 loader 注入的 dataSource 对应） */
+declare function createSitemapSessionServices(session: SitemapSessionContext, serviceName?: string): Record<string, ServiceHandler>;
+
+export { Application, type ApplicationProps, type AuthTokenProvider, type CreateHttpHooksOptions, DslPageLoader, type DslPageLoaderProps, type FetchSitemapOptions, type LayoutDsl, type PactorAppSession, type PactorApplication, type PactorApplicationHandle, type PactorApplicationOptions, type PactorHttpHooks, PactorPage, type PactorPageOptions, type PactorPageProps, type PactorRouterOptions, PageErrorBoundary, ReactRouterBinding, SitemapApp, type SitemapAppProps, type SitemapGuard, type SitemapGuardContext, type SitemapGuardDecision, type SitemapLoaderOptions, type SitemapMenuItem, type SitemapNavItem, type SitemapPageEntry, type SitemapResource, type SitemapRouteMatch, type SitemapRouteResolution, type SitemapSessionContext, createHttpHooks, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { Registry, I18nMessages, PageDsl, DslSourceRef } from '@pactor-app/core';
+import { Registry, I18nMessages, PageDsl, DslSourceRef, DslNode } from '@pactor-app/core';
 import { InteractionProviderProps, OverlayHostProps, OverlayManager, UiBridge } from '@pactor-app/ui/interaction';
 import { LayoutRegistry, AdminLayoutConfig } from '@pactor-app/ui/layout';
 import { PermissionStore } from '@pactor-app/permission';
 import { BootstrapResource, DslResourceLoader } from '@pactor-app/resource';
-import { NavigationBridge, NavigationLocation, NavigationListener, MenuRegistry, RouteContext } from '@pactor-app/router';
+import { NavigationBridge, NavigationLocation, NavigationListener, MenuRegistry, RouteContext, MenuItem } from '@pactor-app/router';
 import { HttpRequestConfig, ActionHandler, ServiceHandler, HttpAdapter, PageRuntime, PermissionAdapter } from '@pactor-app/runtime';
 import * as react from 'react';
 import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
@@ -366,4 +366,263 @@ declare function createPactorPage(options?: PactorPageOptions): ComponentType<Pa
  */
 declare function PactorPage(props: PactorPageProps & PactorPageOptions): react.JSX.Element;
 
-export { Application, type ApplicationProps, type AuthTokenProvider, DslPageLoader, type DslPageLoaderProps, type PactorAppSession, type PactorApplication, type PactorApplicationHandle, type PactorApplicationOptions, type PactorHttpHooks, PactorPage, type PactorPageOptions, type PactorPageProps, type PactorRouterOptions, PageErrorBoundary, ReactRouterBinding, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, wrapHttpAdapter };
+/**
+ * SitemapApp 缺省动作（宿主 actions 同名覆盖）：
+ * 常见动作开箱即用，无需每个项目重复扩展。
+ *
+ * - app.reload：整页重载 / 跳转。登录 / 登出后 sitemap 端点需按新会话
+ *   重新裁剪内容（SPA 导航不触发重取），params.to 缺省跳 '/'
+ * - service.call：调用已注册服务（params.service 服务名，params.params
+ *   入参，表达式求值后传入）。request 动作仅覆盖 HTTP 出口，
+ *   服务层调用经此桥接
+ */
+declare const defaultSitemapActions: Record<string, ActionHandler>;
+
+/**
+ * Sitemap 对象结构（design/dynamic-page.md，方案 B）：
+ * 扁平 pages + 独立 menus + DSL 布局 layouts。
+ * 服务端按会话裁剪内容（匿名 / 角色），对象本身不为角色建模。
+ */
+/** 布局定义：DSL 描述外壳结构，PageOutlet 组件为页面内容出口。
+ * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明 */
+interface LayoutDsl {
+    dsl: string;
+    body: DslNode;
+}
+/** 页面定义：id 主键；pageDsl 缺省 → loadPage(id) 懒加载 */
+interface SitemapPageEntry {
+    id: string;
+    /** 页面 url，支持 /reports/:id 参数 */
+    path: string;
+    title: string;
+    /** 单页版本，参与缓存键 id@version */
+    version?: number;
+    /** 内联页面 DSL；缺省 = 懒加载 */
+    pageDsl?: PageDsl;
+}
+/** 菜单/路由条目：MenuItem + layout 引用 + public 标记。
+ * type: 'page' 且带 pageId 时，path / title 缺省从引用页面继承，
+ * 仅在导航与页面分叉时显式覆写；group / link 只出现在 menus 中 */
+interface SitemapMenuItem extends MenuItem {
+    /** 引用 layouts 的键；缺省用顶层 layout */
+    layout?: string;
+    /** 免登录可访问（登录/注册/落地页） */
+    public?: boolean;
+    children?: SitemapMenuItem[];
+}
+interface SitemapResource extends BootstrapResource {
+    /** 应用级缺省布局名，引用 layouts 的键 */
+    layout?: string;
+    /** 匿名访问控制：未登录访问非 public 页时重定向到 loginPath */
+    auth?: {
+        loginPath?: string;
+    };
+    layouts: Record<string, LayoutDsl>;
+    pages: SitemapPageEntry[];
+    menus: SitemapMenuItem[];
+}
+/** 可渲染路由匹配结果（resolveSitemapRoute 产物） */
+interface SitemapRouteMatch {
+    pageId: string;
+    layoutName: string;
+    /** 菜单高亮 key：activeMenu 指向的菜单项 path（缺省自身 path） */
+    highlightKey: string;
+    params: Record<string, string>;
+}
+
+interface FetchSitemapOptions {
+    /** fetch 实现（缺省全局 fetch；SSR / 测试可注入） */
+    fetcher?: typeof fetch;
+    /** 接口基准地址：sources 为相对路径时以此为基准补全 */
+    baseUrl?: string;
+    /** HTTP 钩子：与页面运行时同一套 request / response 加工 */
+    httpHooks?: PactorHttpHooks;
+}
+/**
+ * 拉取并合并多个 sitemap 源（design/dynamic-page.md）：
+ * pages / menus / layouts 按键合并（id / path 冲突后源覆盖前源并告警），
+ * app / user / permissions / auth 取第一个源。
+ */
+declare function fetchSitemap(sources: string[], options?: FetchSitemapOptions): Promise<SitemapResource>;
+
+interface SitemapLoaderOptions {
+    /** 懒加载页面端点（pages[].pageDsl 缺省时按 id 获取），缺省 /api/pages/{id} */
+    pageEndpoint?: (pageId: string) => string;
+    /** fetch 实现（缺省全局 fetch） */
+    fetcher?: typeof fetch;
+    /** 会话服务名（注入每个页面的 dataSource），缺省 'session.context' */
+    sessionService?: string;
+    /** 接口基准地址：pageEndpoint 返回相对路径时以此为基准补全 */
+    baseUrl?: string;
+    /** HTTP 钩子：与页面运行时同一套 request / response 加工 */
+    httpHooks?: PactorHttpHooks;
+}
+/**
+ * SitemapDslLoader（design/dynamic-page.md 落地影响 #1）：
+ * 内联 pageDsl 直接命中；缺省项经页面端点懒加载。
+ * 缓存键 id@version——同一版本只取一次。
+ * 每个页面注入 session dataSource（${data.session.*}），页面自行声明
+ * 同名 dataSource 时以页面为准。
+ */
+declare function createSitemapLoader(sitemap: SitemapResource, options?: SitemapLoaderOptions): DslResourceLoader;
+
+/** 路由解析结果：菜单命中情况 + 可渲染路由（404 判定） */
+interface SitemapRouteResolution {
+    /** 命中的菜单项（未命中为 null） */
+    menu: SitemapMenuItem | null;
+    /** 可渲染路由；菜单未命中或无 pageId（group / link）时为 null → 404 */
+    route: SitemapRouteMatch | null;
+}
+/**
+ * 路由解析（纯函数）：菜单命中、布局名、activeMenu 高亮 key 一次算清。
+ * 布局名解析链：menu.layout → 顶层 layout → layouts 首键。
+ * 高亮 key：activeMenu 指向其他菜单 id 时高亮该项（隐藏页场景），
+ * key 与 toSitemapNavItems 一致（path ?? id）。
+ */
+declare function resolveSitemapRoute(sitemap: SitemapResource, registry: MenuRegistry, pathname: string): SitemapRouteResolution;
+/** 守卫判定：放行或重定向 */
+type SitemapGuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    redirectTo: string;
+};
+interface SitemapGuardContext {
+    sitemap: SitemapResource;
+    pathname: string;
+    /** 命中的菜单项（未命中为 null） */
+    menu: SitemapMenuItem | null;
+}
+/** 访问守卫：每次路由变化时求值；返回重定向时组件执行 navigate */
+type SitemapGuard = (context: SitemapGuardContext) => SitemapGuardDecision;
+/**
+ * 缺省守卫（匿名访问控制）：未登录访问非 public 页（含未命中路径）→
+ * 重定向 auth.loginPath（缺省 /login）。
+ */
+declare const defaultSitemapGuard: SitemapGuard;
+
+/**
+ * SitemapApp（design/dynamic-page.md）：sitemap 驱动的动态页面应用组件。
+ * 简单配置即可实现动态页面。两种路由模式：
+ * - 纯前端 SPA：不传路由 props，内置浏览器路由（History API + popstate）；
+ * - 宿主路由（Next App Router / react-router / 任意宿主）：注入 pathname / navigate。
+ *
+ * ```tsx
+ * <SitemapApp
+ *   sources={['/api/sitemap']}
+ *   baseUrl="https://api.example.com"
+ *   pathname={usePathname()}
+ *   navigate={(to) => router.push(to)}
+ *   services={{ 'auth.login': login }}
+ * />
+ * ```
+ *
+ * baseUrl 可选：sources / pageEndpoint 只写相对路径时以此为基准补全。
+ *
+ * 内置：多源拉取合并、menus×pages 继承、MenuRegistry 路由解析、访问守卫
+ * （缺省匿名守卫：非 public 且无 user → navigate 到 auth.loginPath，
+ * 可经 guard prop 替换）、DSL 布局渲染
+ * （PageOutlet 页面出口 + SitemapMenu 选中态 / activeMenu 高亮）、
+ * 页面内联 / 懒加载（id@version 缓存）、session.context 服务桥
+ * （${data.session.*}）、缺省动作（app.reload / service.call）。
+ *
+ * 布局常驻：切换导航（同布局名）时仅 PageOutlet 内页面随路由重建。
+ */
+interface SitemapAppProps {
+    /** sitemap 接口 URL 列表（多源合并，冲突后源覆盖前源）；相对路径以 baseUrl 补全 */
+    sources: string[];
+    /** 接口基准地址：sources / pageEndpoint 中的相对路径以此为基准补全 */
+    baseUrl?: string;
+    /** 当前路径（宿主路由注入，如 Next usePathname）；缺省用内置浏览器路由 */
+    pathname?: string;
+    /** 站内导航实现（如 Next router.push）；http(s) 外链自动新标签打开；
+     * 缺省用内置浏览器路由（History API） */
+    navigate?: (to: string) => void;
+    /** 当前 query（DSL ${route.query.x} 可读）；缺省自 location.search 解析 */
+    query?: Record<string, string>;
+    /** 懒加载页面端点，缺省 /api/pages/{id} */
+    pageEndpoint?: SitemapLoaderOptions['pageEndpoint'];
+    /** 业务服务（auth.login 等）；session.context 由组件自动注册 */
+    services?: Record<string, ServiceHandler>;
+    /** 业务动作；框架内置 app.reload / service.call 默认值，同名覆盖 */
+    actions?: Record<string, ActionHandler>;
+    /** 业务组件（同名覆盖内建；PageOutlet / SitemapMenu 为布局保留名） */
+    components?: Record<string, unknown>;
+    /** HTTP 钩子：所有 HTTP 出口（sitemap 源 / 页面端点 / 页面运行时）的统一加工（跨域改写 / 拆包） */
+    httpAdapter?: PactorHttpHooks;
+    /** fetch 实现（缺省全局 fetch；SSR / 测试可注入） */
+    fetcher?: FetchSitemapOptions['fetcher'];
+    /** 访问守卫（缺省 defaultSitemapGuard：匿名访问非 public 页 → 重定向 auth.loginPath） */
+    guard?: SitemapGuard;
+    /** 会话服务名（缺省 session.context） */
+    sessionService?: string;
+    /** 加载中视图 */
+    loading?: ReactNode;
+    /** sitemap 加载失败视图 */
+    renderError?: (error: Error) => ReactNode;
+    /** 路由未命中视图 */
+    renderNotFound?: (path: string) => ReactNode;
+}
+declare function SitemapApp(props: SitemapAppProps): react.JSX.Element | null;
+
+/** createHttpHooks 配置 */
+interface CreateHttpHooksOptions {
+    /** 项目内代理前缀：传入后跨域绝对地址改写到此前缀（由宿主服务端
+     * 转发）；缺省不改写——服务端已开通 CORS，浏览器直连 */
+    proxyPrefix?: string;
+    /** 公共头注入（Authorization / 租户头等），对象或函数（每次请求求值） */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** 响应拆包：缺省按 { code, data, message } 包裹协议处理（拆出 data，
+     * 非 0 抛错）；后端不包裹时传 false 关闭 */
+    envelope?: boolean;
+}
+/**
+ * 默认 HTTP 钩子（常用协议开箱即用）：
+ * - request：缺省不改写地址（假定服务端已开通 CORS，浏览器直连）；
+ *   传 proxyPrefix 时跨域绝对地址（origin ≠ 页面源）改写到项目内
+ *   代理前缀（path + query 保留），由宿主服务端代理转发
+ *   （Vite server.proxy / Next rewrites / nginx）；可注入公共头
+ * - response：{ code, data, message } 包裹结构拆包为 data，非 0 抛错
+ *   （DSL 动作按失败处理）；非包裹结构原样透传
+ *
+ * 后端协议不同（包裹结构 / 错误码约定）时自行实现 PactorHttpHooks。
+ */
+declare function createHttpHooks(options?: CreateHttpHooksOptions): PactorHttpHooks;
+/**
+ * 把 PactorHttpHooks 包装到 fetcher 上：sitemap 源 / 页面端点等框架自发
+ * 请求与页面运行时走同一套 HTTP 加工（跨域改写 / 鉴权头 / 响应拆包）。
+ * response 钩子仅作用于 2xx（错误响应原样返回，由调用方判定 HTTP 错误）。
+ */
+declare function withHttpHooks(fetcher: typeof fetch, hooks?: PactorHttpHooks): typeof fetch;
+
+/**
+ * menus × pages 合并：type: 'page' 且带 pageId 的条目缺省从引用页面
+ * 继承 path / title（仅分叉时覆写）；group / link 原样透传。
+ * 产物可直接 new MenuRegistry(...) 做路由匹配。
+ */
+declare function mergeSitemapMenus(sitemap: SitemapResource): SitemapMenuItem[];
+/** ui Menu 组件 items 形态（可见菜单树 → 导航数据；key = 路径） */
+interface SitemapNavItem {
+    key: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    children?: SitemapNavItem[];
+}
+declare function toSitemapNavItems(menuTree: MenuItem[]): SitemapNavItem[];
+
+/**
+ * 会话上下文（session.context 服务返回值）：布局 / 页面 DSL 经
+ * service dataSource 消费（${data.session.*}）。
+ * 框架原生 user / menus 作用域属设计目标（design/dynamic-page.md
+ * 落地影响 #3），当前经服务桥实现。
+ */
+interface SitemapSessionContext {
+    user?: Record<string, unknown>;
+    app: Record<string, unknown>;
+    menus: SitemapNavItem[];
+}
+/** 注册会话桥服务（缺省名 session.context，与 loader 注入的 dataSource 对应） */
+declare function createSitemapSessionServices(session: SitemapSessionContext, serviceName?: string): Record<string, ServiceHandler>;
+
+export { Application, type ApplicationProps, type AuthTokenProvider, type CreateHttpHooksOptions, DslPageLoader, type DslPageLoaderProps, type FetchSitemapOptions, type LayoutDsl, type PactorAppSession, type PactorApplication, type PactorApplicationHandle, type PactorApplicationOptions, type PactorHttpHooks, PactorPage, type PactorPageOptions, type PactorPageProps, type PactorRouterOptions, PageErrorBoundary, ReactRouterBinding, SitemapApp, type SitemapAppProps, type SitemapGuard, type SitemapGuardContext, type SitemapGuardDecision, type SitemapLoaderOptions, type SitemapMenuItem, type SitemapNavItem, type SitemapPageEntry, type SitemapResource, type SitemapRouteMatch, type SitemapRouteResolution, type SitemapSessionContext, createHttpHooks, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };