add keep alive

.changeset/components-and-keepalive.md

@@ -0,0 +1,15 @@
+---
+"@biugle/react-components": patch
+"@biugle/react-form": patch
+"@biugle/react-table": patch
+"@biugle/biu-preset": patch
+"@biugle/biu-runtime": minor
+"@biugle/biu-cli": minor
+"@biugle/biu-bridge": minor
+---
+
+组件部分样式边界优化。
+
+Add opt-in route-level keep-alive caching for local pages and remote APP iframes. The Bridge exposes optional host activation state so embedded apps can pause background work; the default remains off.
+
+增加 keepAlive 支持。

AGENTS.md

@@ -73,7 +73,7 @@ apps/<project>/
 ## 最终交付归档
 
 - 首版发布前的回归结果、评分、已完成项、TODO、GitHub Secrets 和生产接入边界统一记录在 `docs/final-delivery-review.md` 及 `docs/en/final-delivery-review.md`。
-- HTML、Vue、React 独立 APP 必须共用 `@biugle/biu-preset` 的 `LayoutFrame`；收起状态统一为 60px 图标栏和底部单一控制按钮，顶部恢复按钮只用于“隐藏菜单栏”，禁止 Adapter 或 Demo 自行复制收起逻辑。
+- HTML、Vue、React 独立 APP 必须共用 `@biugle/biu-preset` 的 `LayoutFrame`；收起状态统一为 60px 图标栏，收起/展开按钮始终固定在侧栏顶部，展开态位于侧栏与内容区交界处，收起态居中在图标栏内并只显示图标；底部始终保留菜单配置入口。菜单完全隐藏时，顶部按钮仍在 `aside` 外，避免 `aria-hidden/inert` 阻断恢复；禁止 Adapter 或 Demo 自行复制收起逻辑。
 - 交付门禁统一执行 `pnpm verify`：公共包/Demo 类型检查、18 个公开包打包目标与污染检查、公共包回归单测、ESLint、Prettier、Knip、生产依赖审计、100 个 CLI 创建输入、7 种 Portal/APP preset 与环境构建、全量 Demo 构建和 `git diff --check`；正式 npm/Vercel 发布仍需配置仓库 Secrets 后由 GitHub Actions 执行。
 - 首次提交前必须检查 staged diff，确保无 Token、Cookie、密码、内部域名或本地用户数据；不要提交 `dist/`、`.biu/`、`node_modules/`、缓存和 `.husky/_/`。
 - 组件、基座、公共包、Demo、API、设计决策、浏览器回归和交付约束的唯一综合记录是 `docs/biu-foundation-components-capabilities.md` 及其 `docs/en/` 英文对应文件；`docs/final-delivery-review.md` 只保存发布审计，不得再建立或保留 `docs/specs/` 阶段性 Spec 目录。

docs/adapters.md

@@ -110,6 +110,8 @@ pnpm build:html-child
 
 ## 4. 自定义 Adapter Contract
 
+自定义 Adapter 可选实现 `updatePage(container, page, context)`，在已挂载页面时接收 locale、认证投影、宿主激活状态等上下文变化；Runtime 会保留当前框架实例并调用此方法。没有该方法的既有 Adapter 继续按原方式在 context 改变时重新挂载，保持兼容。Adapter 管理框架响应式状态时，应通过该方法更新现有实例。
+
 Adapter 文件必须 `default export` 一个对象：
 
 ```ts
@@ -278,17 +280,17 @@ Angular 的构建插件不是 `biu` 官方 Adapter 的一部分；项目需要
 
 ## 8. 生命周期与安全要求
 
-- 切换页面时必须释放框架实例、事件监听和定时器。
+- 普通路由切换时必须释放框架实例、事件监听和定时器；路由显式启用 `keepAlive: true` 时 Runtime 会保留页面实例，页面应在不激活时暂停高成本后台工作。
 - 页面差异通过 `context.code`、`context.portalCode`、`context.environment` 判断；不要从路径层级推断门户。
-- 被 Portal iframe 加载时，Runtime 会在初始化和语言切换时发送 `HOST_CONTEXT`；Adapter 页面使用 `context.locale` 获取最新语言，不要只读取初始化配置。
+- 被 Portal iframe 加载时，Runtime 会在初始化、路由激活变化和语言切换时发送 `HOST_CONTEXT`；Adapter 页面使用 `context.locale` 获取最新语言，并可通过 `context.hostActive` 判断远程 APP 当前是否激活。
 - Adapter 不绕过 `useBiuPermission` 或后端接口鉴权。组件权限仍由后端最终校验。
 - Adapter 不能动态从 CDN 注入基座代码；基座包默认由项目编译时本地依赖提供。
 - 页面私有样式使用独立 `.css` 文件；基座 Layout 样式统一由 `@biugle/biu-preset` 管理。
 - iframe 子应用的 Modal/Drawer 使用 `useBiuOverlay()` 报告 `HOST_CHROME` 遮罩状态；业务组件仍在自己的 iframe 内渲染，不能直接操作 Portal DOM。
 
 ## 9. 全局上下文与 SSO
 
-页面可通过 `useBiuContext()` 获取 `locale`、`theme`、`timezone`、`direction`、`portalCode`、`currentCode` 和只读用户身份；React 页面也可以直接使用 `useBiuLocale`、`useBiuTheme`、`useBiuTimezone`、`useBiuDirection`、`useBiuAuth` 选择器。Portal 切换这些偏好后会重新发送 `HOST_CONTEXT`，Runtime 会同时更新 Zustand，所以 Adapter 页面不应只读取首次初始化值。`auth` 只包含非敏感身份信息；Token 和 session id 不经过 Bridge，登录态由 SSO Cookie/网关完成。
+页面可通过 `useBiuContext()` 获取 `locale`、`theme`、`timezone`、`direction`、`portalCode`、`currentCode`、`hostActive` 和只读用户身份；React 页面也可以直接使用 `useBiuLocale`、`useBiuTheme`、`useBiuTimezone`、`useBiuDirection`、`useBiuAuth` 选择器。Portal 切换这些偏好或路由激活状态后会重新发送 `HOST_CONTEXT`，Runtime 会同时更新 Zustand，所以 Adapter 页面不应只读取首次初始化值。设置 `keepAlive: true` 后，Portal 会保留远程 APP 的整个 iframe；子应用可在 `hostActive === false` 时暂停轮询、动画和订阅。`auth` 只包含非敏感身份信息；Token 和 session id 不经过 Bridge，登录态由 SSO Cookie/网关完成。
 
 ### 基座控制 API