@pactor-app/app 1.46.0 → 1.48.0

package/README.md

@@ -124,6 +124,8 @@ import { SitemapApp } from '@pactor-app/app';
 
 内置能力（无需自行拼装）：多源拉取合并（冲突后源覆盖前源）、`menus × pages` 继承（`path` / `title` 缺省自引用页面）、MenuRegistry 路由解析（含 `:param`）、访问守卫（缺省匿名守卫：非 `public` 且无 user → `navigate(auth.loginPath)`，`guard` prop 可替换为角色鉴权等策略）、DSL 布局渲染（`PageOutlet` 页面出口、`SitemapMenu` 选中态与 `activeMenu` 高亮）、页面内联 / 懒加载（`id@version` 缓存，`pageEndpoint` 可配）、`session.context` 服务桥（DSL 经 `${data.session.*}` 读 user / app / menus）、缺省动作（`app.reload` 整页重载、`service.call` 服务调用，宿主 `actions` 同名覆盖）、布局常驻（同布局名切换导航仅内容区重建）。布局名解析链：`menu.layout` → 顶层 `layout` → `layouts` 首键。
 
+布局可声明 `state` / `lifecycle`（布局运行时常驻，state 跨页面保持）；`LayoutDsl.parent` 引用另一布局形成**嵌套链**——如 `agent.parent = 'admin'` 时渲染为 `admin`（其 `PageOutlet` 渲染 `agent` 布局，`agent` 的 `PageOutlet` 渲染页面）。每级布局是独立运行时（独立 state / lifecycle / 弹层宿主），导航时链共享前缀的外层布局保持挂载（一级外壳不重建），仅分叉层重建；`parent` 悬空或成环时链截断兜底。隐藏页（不进菜单的路由页）用菜单条目的 `activeMenu` 指向一级菜单 id，访问时外层导航菜单保持对应选中态。
+
 | Props | 说明 |
 | --- | --- |
 | `sources`（必填） | sitemap 接口 URL 列表（相对路径以 `baseUrl` 补全） |
@@ -139,7 +141,7 @@ import { SitemapApp } from '@pactor-app/app';
 | `sessionService` | 会话桥服务名（缺省 `session.context`） |
 | `loading` / `renderError` / `renderNotFound` | 状态视图定制 |
 
-配套导出（高级用法）：`fetchSitemap`、`createSitemapLoader`、`mergeSitemapMenus`、`toSitemapNavItems`、`resolveSitemapRoute`、`defaultSitemapGuard`、`defaultSitemapActions`、`createHttpHooks`、`withHttpHooks`、`createSitemapSessionServices` 与类型 `SitemapResource` / `SitemapMenuItem` / `SitemapPageEntry` / `LayoutDsl` / `SitemapRouteMatch` / `SitemapRouteResolution` / `SitemapGuard` / `SitemapSessionContext`。完整示例工程见 `starters/next-app-starter`（宿主路由模式）与 `starters/spa-starter`（纯前端内置路由模式）。
+配套导出（高级用法）：`fetchSitemap`、`createSitemapLoader`、`mergeSitemapMenus`、`toSitemapNavItems`、`resolveSitemapRoute`、`resolveLayoutChain`、`defaultSitemapGuard`、`defaultSitemapActions`、`createHttpHooks`、`withHttpHooks`、`createSitemapSessionServices` 与类型 `SitemapResource` / `SitemapMenuItem` / `SitemapPageEntry` / `LayoutDsl` / `SitemapRouteMatch` / `SitemapRouteResolution` / `SitemapGuard` / `SitemapSessionContext`。完整示例工程见 `starters/next-app-starter`（宿主路由模式）与 `starters/spa-starter`（纯前端内置路由模式）。
 
 ## 文档
 

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   defaultSitemapGuard: () => defaultSitemapGuard,
   fetchSitemap: () => fetchSitemap,
   mergeSitemapMenus: () => mergeSitemapMenus,
+  resolveLayoutChain: () => resolveLayoutChain,
   resolveSitemapRoute: () => resolveSitemapRoute,
   toSitemapNavItems: () => toSitemapNavItems,
   withHttpHooks: () => withHttpHooks,
@@ -1291,11 +1292,26 @@ function resolveSitemapRoute(sitemap, registry, pathname) {
     route: {
       pageId: menu.pageId,
       layoutName,
+      layoutChain: resolveLayoutChain(sitemap, layoutName),
       highlightKey: highlightItem?.path ?? highlightId,
       params: match.params
     }
   };
 }
+function resolveLayoutChain(sitemap, layoutName) {
+  const chain = [layoutName];
+  const seen = new Set(chain);
+  let current = layoutName;
+  for (; ; ) {
+    const parent = sitemap.layouts[current]?.parent;
+    if (parent === void 0 || seen.has(parent) || sitemap.layouts[parent] === void 0) {
+      return chain;
+    }
+    chain.unshift(parent);
+    seen.add(parent);
+    current = parent;
+  }
+}
 var defaultSitemapGuard = ({
   sitemap,
   pathname,
@@ -1414,24 +1430,24 @@ function SitemapAppInner(props) {
   if (resolution.route === null) {
     return props.renderNotFound !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(import_jsx_runtime6.Fragment, { children: props.renderNotFound(pathname) }) : /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(Centered, { children: t("pactor.sitemap.notFound", { path: pathname }) });
   }
-  const { pageId, layoutName, highlightKey, params } = resolution.route;
+  const { pageId, layoutChain, highlightKey, params } = resolution.route;
   return (
-    // key 只随布局名变化：切换导航（同布局）时布局常驻，
-    // 仅 PageOutlet 内的页面随路由重建
+    // key 只随最外层布局名变化：布局链共享前缀时外层布局常驻，
+    // 仅分叉的内层布局与 PageOutlet 内页面随路由重建
     /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(NavHighlightContext.Provider, { value: highlightKey, children: /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
       SitemapLayout,
       {
         sitemap,
         registry,
         pageId,
-        layoutName,
+        layoutChain,
         pathname,
         query,
         navigate,
         routeParams: params,
         props
       },
-      layoutName
+      layoutChain[0]
     ) })
   );
 }
@@ -1439,14 +1455,13 @@ function SitemapLayout({
   sitemap,
   registry,
   pageId,
-  layoutName,
+  layoutChain,
   pathname,
   query,
   navigate: hostNavigate,
   routeParams,
   props
 }) {
-  const { t } = (0, import_runtime6.useI18n)();
   const sessionService = props.sessionService ?? "session.context";
   const session = (0, import_react8.useMemo)(
     () => ({
@@ -1494,23 +1509,6 @@ function SitemapLayout({
     () => ({ ...defaultSitemapActions, ...props.actions }),
     [props.actions]
   );
-  const layoutDsl = sitemap.layouts[layoutName];
-  const layoutPage = (0, import_react8.useMemo)(() => {
-    if (layoutDsl === void 0) {
-      return null;
-    }
-    return {
-      dsl: layoutDsl.dsl,
-      page: { id: `layout:${layoutName}`, title: layoutName },
-      dataSources: {
-        session: { type: "service", service: sessionService, autoLoad: true }
-      },
-      body: layoutDsl.body
-    };
-  }, [layoutDsl, layoutName, sessionService]);
-  if (layoutDsl === void 0 || layoutPage === null) {
-    return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(Centered, { children: t("pactor.sitemap.layoutMissing", { name: layoutName }) });
-  }
   const messagesSignature = JSON.stringify(props.messages ?? {});
   const pageFactory = (0, import_react8.useMemo)(
     () => createPactorPage({
@@ -1541,6 +1539,9 @@ function SitemapLayout({
   );
   const layoutFactory = (0, import_react8.useMemo)(
     () => createPactorPage({
+      // loader 注入使布局运行时的 OverlayHost 支持 page 类型弹层
+      //（布局内按钮经 overlay.open 打开懒加载表单页，如创建实例）
+      loader,
       services,
       actions,
       navigate,
@@ -1552,6 +1553,7 @@ function SitemapLayout({
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
+      loader,
       services,
       actions,
       navigate,
@@ -1563,11 +1565,15 @@ function SitemapLayout({
     ]
   );
   const Page = pageFactory;
-  const LayoutPage = layoutFactory;
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
-    OutletContext.Provider,
+    LayoutLevel,
     {
-      value: (
+      sitemap,
+      chain: layoutChain,
+      index: 0,
+      sessionService,
+      layoutFactory,
+      outlet: (
         // 页面实例：key 随 pageId + pathname 变化（route 参数变化需重建，
         // PactorPage 的 route prop 不参与运行时重建）——布局保持挂载
         /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
@@ -1578,8 +1584,57 @@ function SitemapLayout({
           },
           `${pageId}@${pathname}`
         )
+      )
+    }
+  );
+}
+function LayoutLevel({
+  sitemap,
+  chain,
+  index,
+  sessionService,
+  layoutFactory,
+  outlet
+}) {
+  const { t } = (0, import_runtime6.useI18n)();
+  const layoutName = chain[index];
+  const layoutDsl = sitemap.layouts[layoutName];
+  const layoutPage = (0, import_react8.useMemo)(() => {
+    if (layoutDsl === void 0) {
+      return null;
+    }
+    return {
+      dsl: layoutDsl.dsl,
+      page: { id: `layout:${layoutName}`, title: layoutName },
+      // 布局级 state / lifecycle 透传（布局运行时常驻，state 跨页面保持）
+      state: layoutDsl.state,
+      lifecycle: layoutDsl.lifecycle,
+      dataSources: {
+        session: { type: "service", service: sessionService, autoLoad: true }
+      },
+      body: layoutDsl.body
+    };
+  }, [layoutDsl, layoutName, sessionService]);
+  if (layoutDsl === void 0 || layoutPage === null) {
+    return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(Centered, { children: t("pactor.sitemap.layoutMissing", { name: layoutName }) });
+  }
+  const LayoutPage = layoutFactory;
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+    OutletContext.Provider,
+    {
+      value: index === chain.length - 1 ? outlet : /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+        LayoutLevel,
+        {
+          sitemap,
+          chain,
+          index: index + 1,
+          sessionService,
+          layoutFactory,
+          outlet
+        },
+        chain[index + 1]
       ),
-      children: /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(LayoutPage, { pageDsl: layoutPage })
+      children: /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(LayoutPage, { pageDsl: layoutPage }, layoutName)
     }
   );
 }
@@ -1619,6 +1674,7 @@ function Centered({ children }) {
   defaultSitemapGuard,
   fetchSitemap,
   mergeSitemapMenus,
+  resolveLayoutChain,
   resolveSitemapRoute,
   toSitemapNavItems,
   withHttpHooks,

package/dist/index.d.cts

@@ -432,9 +432,20 @@ declare const defaultSitemapActions: Record<string, ActionHandler>;
  * 服务端按会话裁剪内容（匿名 / 角色），对象本身不为角色建模。
  */
 /** 布局定义：DSL 描述外壳结构，PageOutlet 组件为页面内容出口。
- * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明 */
+ * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明。
+ * state / lifecycle 可选：布局运行时在相同布局名导航间常驻（key 不变
+ * 不重建），其中的 state 跨页面保持（如侧栏选中 / 折叠态），onInit
+ * 随布局运行时创建执行一次。
+ * parent 可选：引用另一布局作为外层外壳，形成布局嵌套链（如
+ * agent.parent = admin → 渲染 admin(PageOutlet=agent(PageOutlet=页面))）。
+ * 每级布局是独立运行时；跨页面导航时共享前缀的外层布局保持挂载，
+ * 其 state 不受内层布局 / 页面切换影响 */
 interface LayoutDsl {
     dsl: string;
+    /** 外层布局名，引用 layouts 的键；缺省无外层（自身为最外层） */
+    parent?: string;
+    state?: PageDsl['state'];
+    lifecycle?: PageDsl['lifecycle'];
     body: DslNode;
 }
 /** 页面定义：id 主键；pageDsl 缺省 → loadPage(id) 懒加载 */
@@ -472,7 +483,10 @@ interface SitemapResource extends BootstrapResource {
 /** 可渲染路由匹配结果（resolveSitemapRoute 产物） */
 interface SitemapRouteMatch {
     pageId: string;
+    /** 页面直接布局名（布局链的最内层） */
     layoutName: string;
+    /** 布局嵌套链（最外层在前）：沿 LayoutDsl.parent 上溯，含自身 */
+    layoutChain: string[];
     /** 菜单高亮 key：activeMenu 指向的菜单项 path（缺省自身 path） */
     highlightKey: string;
     params: Record<string, string>;
@@ -528,6 +542,11 @@ interface SitemapRouteResolution {
  * key 与 toSitemapNavItems 一致（path ?? id）。
  */
 declare function resolveSitemapRoute(sitemap: SitemapResource, registry: MenuRegistry, pathname: string): SitemapRouteResolution;
+/**
+ * 布局嵌套链（最外层在前）：自布局名沿 LayoutDsl.parent 上溯至无外层。
+ * parent 悬空（未定义的布局名）或成环时截断，保证有限终止。
+ */
+declare function resolveLayoutChain(sitemap: SitemapResource, layoutName: string): string[];
 /** 守卫判定：放行或重定向 */
 type SitemapGuardDecision = {
     allow: true;
@@ -574,7 +593,9 @@ declare const defaultSitemapGuard: SitemapGuard;
  * 页面内联 / 懒加载（id@version 缓存）、session.context 服务桥
  * （${data.session.*}）、缺省动作（app.reload / service.call）。
  *
- * 布局常驻：切换导航（同布局名）时仅 PageOutlet 内页面随路由重建。
+ * 布局常驻与嵌套：LayoutDsl.parent 引用外层布局形成嵌套链（最外层在
+ * 前），每级布局为独立运行时；切换导航时链共享前缀的外层布局保持
+ * 挂载（state 跨页面保持），仅分叉层与 PageOutlet 内页面随路由重建。
  */
 interface SitemapAppProps {
     /** sitemap 接口 URL 列表（多源合并，冲突后源覆盖前源）；相对路径以 baseUrl 补全 */
@@ -686,4 +707,4 @@ interface SitemapSessionContext {
 /** 注册会话桥服务（缺省名 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 LocaleStorage, 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, createLocalStorageLocaleStorage, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };
+export { Application, type ApplicationProps, type AuthTokenProvider, type CreateHttpHooksOptions, DslPageLoader, type DslPageLoaderProps, type FetchSitemapOptions, type LayoutDsl, type LocaleStorage, 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, createLocalStorageLocaleStorage, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveLayoutChain, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };

package/dist/index.d.ts

@@ -432,9 +432,20 @@ declare const defaultSitemapActions: Record<string, ActionHandler>;
  * 服务端按会话裁剪内容（匿名 / 角色），对象本身不为角色建模。
  */
 /** 布局定义：DSL 描述外壳结构，PageOutlet 组件为页面内容出口。
- * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明 */
+ * 不套 PageDsl 的 page 包装——id 即 layouts 的键，无重复声明。
+ * state / lifecycle 可选：布局运行时在相同布局名导航间常驻（key 不变
+ * 不重建），其中的 state 跨页面保持（如侧栏选中 / 折叠态），onInit
+ * 随布局运行时创建执行一次。
+ * parent 可选：引用另一布局作为外层外壳，形成布局嵌套链（如
+ * agent.parent = admin → 渲染 admin(PageOutlet=agent(PageOutlet=页面))）。
+ * 每级布局是独立运行时；跨页面导航时共享前缀的外层布局保持挂载，
+ * 其 state 不受内层布局 / 页面切换影响 */
 interface LayoutDsl {
     dsl: string;
+    /** 外层布局名，引用 layouts 的键；缺省无外层（自身为最外层） */
+    parent?: string;
+    state?: PageDsl['state'];
+    lifecycle?: PageDsl['lifecycle'];
     body: DslNode;
 }
 /** 页面定义：id 主键；pageDsl 缺省 → loadPage(id) 懒加载 */
@@ -472,7 +483,10 @@ interface SitemapResource extends BootstrapResource {
 /** 可渲染路由匹配结果（resolveSitemapRoute 产物） */
 interface SitemapRouteMatch {
     pageId: string;
+    /** 页面直接布局名（布局链的最内层） */
     layoutName: string;
+    /** 布局嵌套链（最外层在前）：沿 LayoutDsl.parent 上溯，含自身 */
+    layoutChain: string[];
     /** 菜单高亮 key：activeMenu 指向的菜单项 path（缺省自身 path） */
     highlightKey: string;
     params: Record<string, string>;
@@ -528,6 +542,11 @@ interface SitemapRouteResolution {
  * key 与 toSitemapNavItems 一致（path ?? id）。
  */
 declare function resolveSitemapRoute(sitemap: SitemapResource, registry: MenuRegistry, pathname: string): SitemapRouteResolution;
+/**
+ * 布局嵌套链（最外层在前）：自布局名沿 LayoutDsl.parent 上溯至无外层。
+ * parent 悬空（未定义的布局名）或成环时截断，保证有限终止。
+ */
+declare function resolveLayoutChain(sitemap: SitemapResource, layoutName: string): string[];
 /** 守卫判定：放行或重定向 */
 type SitemapGuardDecision = {
     allow: true;
@@ -574,7 +593,9 @@ declare const defaultSitemapGuard: SitemapGuard;
  * 页面内联 / 懒加载（id@version 缓存）、session.context 服务桥
  * （${data.session.*}）、缺省动作（app.reload / service.call）。
  *
- * 布局常驻：切换导航（同布局名）时仅 PageOutlet 内页面随路由重建。
+ * 布局常驻与嵌套：LayoutDsl.parent 引用外层布局形成嵌套链（最外层在
+ * 前），每级布局为独立运行时；切换导航时链共享前缀的外层布局保持
+ * 挂载（state 跨页面保持），仅分叉层与 PageOutlet 内页面随路由重建。
  */
 interface SitemapAppProps {
     /** sitemap 接口 URL 列表（多源合并，冲突后源覆盖前源）；相对路径以 baseUrl 补全 */
@@ -686,4 +707,4 @@ interface SitemapSessionContext {
 /** 注册会话桥服务（缺省名 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 LocaleStorage, 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, createLocalStorageLocaleStorage, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };
+export { Application, type ApplicationProps, type AuthTokenProvider, type CreateHttpHooksOptions, DslPageLoader, type DslPageLoaderProps, type FetchSitemapOptions, type LayoutDsl, type LocaleStorage, 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, createLocalStorageLocaleStorage, createPactorApplication, createPactorPage, createRuntimeHttpAdapter, createSitemapLoader, createSitemapSessionServices, defaultSitemapActions, defaultSitemapGuard, fetchSitemap, mergeSitemapMenus, resolveLayoutChain, resolveSitemapRoute, toSitemapNavItems, withHttpHooks, wrapHttpAdapter };

package/dist/index.js

@@ -1293,11 +1293,26 @@ function resolveSitemapRoute(sitemap, registry, pathname) {
     route: {
       pageId: menu.pageId,
       layoutName,
+      layoutChain: resolveLayoutChain(sitemap, layoutName),
       highlightKey: highlightItem?.path ?? highlightId,
       params: match.params
     }
   };
 }
+function resolveLayoutChain(sitemap, layoutName) {
+  const chain = [layoutName];
+  const seen = new Set(chain);
+  let current = layoutName;
+  for (; ; ) {
+    const parent = sitemap.layouts[current]?.parent;
+    if (parent === void 0 || seen.has(parent) || sitemap.layouts[parent] === void 0) {
+      return chain;
+    }
+    chain.unshift(parent);
+    seen.add(parent);
+    current = parent;
+  }
+}
 var defaultSitemapGuard = ({
   sitemap,
   pathname,
@@ -1416,24 +1431,24 @@ function SitemapAppInner(props) {
   if (resolution.route === null) {
     return props.renderNotFound !== void 0 ? /* @__PURE__ */ jsx6(Fragment, { children: props.renderNotFound(pathname) }) : /* @__PURE__ */ jsx6(Centered, { children: t("pactor.sitemap.notFound", { path: pathname }) });
   }
-  const { pageId, layoutName, highlightKey, params } = resolution.route;
+  const { pageId, layoutChain, highlightKey, params } = resolution.route;
   return (
-    // key 只随布局名变化：切换导航（同布局）时布局常驻，
-    // 仅 PageOutlet 内的页面随路由重建
+    // key 只随最外层布局名变化：布局链共享前缀时外层布局常驻，
+    // 仅分叉的内层布局与 PageOutlet 内页面随路由重建
     /* @__PURE__ */ jsx6(NavHighlightContext.Provider, { value: highlightKey, children: /* @__PURE__ */ jsx6(
       SitemapLayout,
       {
         sitemap,
         registry,
         pageId,
-        layoutName,
+        layoutChain,
         pathname,
         query,
         navigate,
         routeParams: params,
         props
       },
-      layoutName
+      layoutChain[0]
     ) })
   );
 }
@@ -1441,14 +1456,13 @@ function SitemapLayout({
   sitemap,
   registry,
   pageId,
-  layoutName,
+  layoutChain,
   pathname,
   query,
   navigate: hostNavigate,
   routeParams,
   props
 }) {
-  const { t } = useI18n2();
   const sessionService = props.sessionService ?? "session.context";
   const session = useMemo2(
     () => ({
@@ -1496,23 +1510,6 @@ function SitemapLayout({
     () => ({ ...defaultSitemapActions, ...props.actions }),
     [props.actions]
   );
-  const layoutDsl = sitemap.layouts[layoutName];
-  const layoutPage = useMemo2(() => {
-    if (layoutDsl === void 0) {
-      return null;
-    }
-    return {
-      dsl: layoutDsl.dsl,
-      page: { id: `layout:${layoutName}`, title: layoutName },
-      dataSources: {
-        session: { type: "service", service: sessionService, autoLoad: true }
-      },
-      body: layoutDsl.body
-    };
-  }, [layoutDsl, layoutName, sessionService]);
-  if (layoutDsl === void 0 || layoutPage === null) {
-    return /* @__PURE__ */ jsx6(Centered, { children: t("pactor.sitemap.layoutMissing", { name: layoutName }) });
-  }
   const messagesSignature = JSON.stringify(props.messages ?? {});
   const pageFactory = useMemo2(
     () => createPactorPage({
@@ -1543,6 +1540,9 @@ function SitemapLayout({
   );
   const layoutFactory = useMemo2(
     () => createPactorPage({
+      // loader 注入使布局运行时的 OverlayHost 支持 page 类型弹层
+      //（布局内按钮经 overlay.open 打开懒加载表单页，如创建实例）
+      loader,
       services,
       actions,
       navigate,
@@ -1554,6 +1554,7 @@ function SitemapLayout({
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
+      loader,
       services,
       actions,
       navigate,
@@ -1565,11 +1566,15 @@ function SitemapLayout({
     ]
   );
   const Page = pageFactory;
-  const LayoutPage = layoutFactory;
   return /* @__PURE__ */ jsx6(
-    OutletContext.Provider,
+    LayoutLevel,
     {
-      value: (
+      sitemap,
+      chain: layoutChain,
+      index: 0,
+      sessionService,
+      layoutFactory,
+      outlet: (
         // 页面实例：key 随 pageId + pathname 变化（route 参数变化需重建，
         // PactorPage 的 route prop 不参与运行时重建）——布局保持挂载
         /* @__PURE__ */ jsx6(
@@ -1580,8 +1585,57 @@ function SitemapLayout({
           },
           `${pageId}@${pathname}`
         )
+      )
+    }
+  );
+}
+function LayoutLevel({
+  sitemap,
+  chain,
+  index,
+  sessionService,
+  layoutFactory,
+  outlet
+}) {
+  const { t } = useI18n2();
+  const layoutName = chain[index];
+  const layoutDsl = sitemap.layouts[layoutName];
+  const layoutPage = useMemo2(() => {
+    if (layoutDsl === void 0) {
+      return null;
+    }
+    return {
+      dsl: layoutDsl.dsl,
+      page: { id: `layout:${layoutName}`, title: layoutName },
+      // 布局级 state / lifecycle 透传（布局运行时常驻，state 跨页面保持）
+      state: layoutDsl.state,
+      lifecycle: layoutDsl.lifecycle,
+      dataSources: {
+        session: { type: "service", service: sessionService, autoLoad: true }
+      },
+      body: layoutDsl.body
+    };
+  }, [layoutDsl, layoutName, sessionService]);
+  if (layoutDsl === void 0 || layoutPage === null) {
+    return /* @__PURE__ */ jsx6(Centered, { children: t("pactor.sitemap.layoutMissing", { name: layoutName }) });
+  }
+  const LayoutPage = layoutFactory;
+  return /* @__PURE__ */ jsx6(
+    OutletContext.Provider,
+    {
+      value: index === chain.length - 1 ? outlet : /* @__PURE__ */ jsx6(
+        LayoutLevel,
+        {
+          sitemap,
+          chain,
+          index: index + 1,
+          sessionService,
+          layoutFactory,
+          outlet
+        },
+        chain[index + 1]
       ),
-      children: /* @__PURE__ */ jsx6(LayoutPage, { pageDsl: layoutPage })
+      children: /* @__PURE__ */ jsx6(LayoutPage, { pageDsl: layoutPage }, layoutName)
     }
   );
 }
@@ -1620,6 +1674,7 @@ export {
   defaultSitemapGuard,
   fetchSitemap,
   mergeSitemapMenus,
+  resolveLayoutChain,
   resolveSitemapRoute,
   toSitemapNavItems,
   withHttpHooks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/app",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Pactor application: one-stop composition layer (createPactorApplication) wiring loader, bootstrap, registries, router, layout, interaction and page runtimes",
   "keywords": [
     "pactor",
@@ -46,14 +46,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@pactor-app/core": "1.46.0",
-    "@pactor-app/expression": "1.46.0",
-    "@pactor-app/schema": "1.46.0",
-    "@pactor-app/permission": "1.46.0",
-    "@pactor-app/runtime": "1.46.0",
-    "@pactor-app/ui": "1.46.0",
-    "@pactor-app/router": "1.46.0",
-    "@pactor-app/resource": "1.46.0"
+    "@pactor-app/core": "1.48.0",
+    "@pactor-app/permission": "1.48.0",
+    "@pactor-app/expression": "1.48.0",
+    "@pactor-app/router": "1.48.0",
+    "@pactor-app/runtime": "1.48.0",
+    "@pactor-app/resource": "1.48.0",
+    "@pactor-app/ui": "1.48.0",
+    "@pactor-app/schema": "1.48.0"
   },
   "peerDependencies": {
     "react": ">=18",