npm - weifuwu - Versions diffs - 0.63.1 → 0.64.0 - Mend

weifuwu 0.63.1 → 0.64.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md +121 -2953
package/dist/ai/client.d.ts +1 -1
package/dist/ai/sse.d.ts +1 -1
package/dist/ai/types.d.ts +2 -2
package/dist/client/ai.d.ts +1 -1
package/dist/client/index.js +3 -3
package/dist/client/types.d.ts +108 -0
package/dist/client/use-chat.d.ts +1 -1
package/dist/components/AiChat/AiChat.d.ts +2 -0
package/dist/components/ContextMenu/ContextMenu.d.ts +1 -1
package/dist/components/Dropdown/Dropdown.d.ts +4 -1
package/dist/components/HoverCard/HoverCard.d.ts +7 -1
package/dist/components/Popover/Popover.d.ts +3 -0
package/dist/components/Tooltip/Tooltip.d.ts +3 -0
package/dist/components/index.js +13 -13
package/dist/components/style.css +164 -0
package/dist/index.d.ts +1 -0
package/dist/index.js +3 -1
package/dist/layout/weifuwu-layout.css +22 -0
package/docs/components.md +314 -0
package/docs/data.md +240 -0
package/docs/environment.md +27 -0
package/docs/examples.md +127 -0
package/docs/frontend-middleware.md +435 -0
package/docs/frontend.md +697 -0
package/docs/layout.md +203 -0
package/docs/mobile.md +109 -0
package/docs/realtime.md +291 -0
package/docs/saas.md +246 -0
package/docs/server.md +356 -0
package/docs/styling.md +130 -0
package/package.json +4 -3

package/README.md CHANGED Viewed

@@ -1,31 +1,72 @@
 # weifuwu
-**一个包的全栈框架** — 后端 HTTP + 前端 VDOM + 组件库 + CSS 设计系统。全自研、零配置、消灭样板。
+**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 92 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
 ```bash
-npm install weifuwu
+npm install weifuwu      # 一个依赖，完整应用栈
 ```
-一个包 = 后端 (`weifuwu`) + 前端 (`weifuwu/client`) + 组件库 (`weifuwu/components`) + 布局系统 (`weifuwu/layout`)。
+**定位**：面向需要完整应用栈、又不想缝合多个框架/服务、且重视代码与数据所有权的开发者——独立开发者、小团队、自托管/私有化部署。尤其当应用包含 **认证 + 实时消息 + AI 对话 + 后台管理** 时，weifuwu 把这些「每个应用都要的地基」全部内置为一行 `app.use(...)`。
+### 五个关键卖点
+| 卖点 | 为什么重要 |
+|------|-----------|
+| **一个包，零构建** | 服务端 `node --import weifuwu/dev` 直跑 `.tsx`；浏览器 CDN import map 即用；CSS 一条 link 即得完整设计系统——没有构建步骤、没有脚手架 |
+| **协议层全自研** | PG v3 / RESP2 / GraphQL schema / OpenAI 流式协议全部自研——确定性、可预测、错误模型统一；诚实裁剪：**不支持的能力明确报错，绝不静默降级** |
+| **消灭样板** | 动态编译免构建、`ctx.data.get` 一个 API 覆盖 SSR 预取/hydration/SPA、自研 DB 客户端免双重编码与 parseRow 样板 |
+| **SaaS 地基随包内置** | rateLimit / email / userSystem / messager / queue / ai 六个中间件**互相咬合**（身份是消息的路由）——从「自建基础设施」变「声明业务」 |
+| **自托管友好** | 运行时仅 esbuild + graphql + ws；部署 = 一个 Node 进程 + Postgres + Redis；数据、代码、模型全部在自己手里 |
+### 一个包 = 五层能力
+| 层 | 入口 | 能力 |
+|----|------|------|
+| 后端 | `weifuwu` | Trie 路由 / 中间件链 / serve / 自研 PG+Redis / SSR / GraphQL / WebSocket |
+| 前端 | `weifuwu/client` | 两阶段组件 / Proxy 渲染 / 数据管道 / 路由 / api·auth·ws·i18n / 移动端原语 |
+| 组件 | `weifuwu/components` | 92 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
+| 样式 | `weifuwu/layout` | 70 布局原语 + 141 主题 Token，零自定义 CSS 文件 |
+| SaaS 地基 | 随包内置 | rateLimit / email / userSystem / messager / queue / ai → `ctx.*` 一行接入 |
 > ⚠️ **注意：前后端都有 `ctx.ui`，但用途完全不同**
 > - **后端** `ctx.ui`（SSR/编译）：`ctx.ui.html`（HTML 模板）、`ctx.ui.js`（TSX→JS 动态编译）、`ctx.ui.css`（CSS 编译）、`ctx.ui.ssr`（组件 SSR）、`ctx.ui.ssrData`（数据序列化）
-> - **前端** `ctx.ui`（渲染引擎）：`ctx.ui.$()`（响应式状态）、`ctx.ui.render()` / `dirty()`（渲染控制）、`useMedia()` / `useBreakpoint()` / `usePopupPosition()` / `useInView()` / `useScrollPosition()`（浏览器事件监听）
+> - **前端** `ctx.ui`（渲染引擎）：`ctx.ui.$()`（响应式状态）、`ctx.ui.render()` / `dirty()`（渲染控制）、`useChat()`（AI 会话）/ `useAsync()`（异步取数）/ `selfId()`（跨组件刷新）/ `useMedia()` / `useBreakpoint()`（响应式断点）/ `usePopupPosition()` / `usePopup()`（弹层定位/组合）/ `useHoverCapable()` / `useLongPress()` / `useVisualViewport()`（移动端原语）/ `useInView()` / `useScrollPosition()`（浏览器事件监听）
 > 后端的是「把页面和代码交给浏览器」，前端的是「在浏览器里驱动 UI」。
+### 与主流方案的关系
+| | weifuwu | Express + React 等 | Next.js 全家桶 |
+|--|---------|------------------|----------------|
+| 依赖 | **1 个包** | 5+ 个框架/库 | 生态绑定 |
+| 构建 | **零**（动态编译直跑 `.tsx`） | 需要 | 需要 |
+| DB 客户端 | **自研协议**（零依赖，确定性输出） | pg + 连接池 | Prisma 等 |
+| AI / Agent | **内置**（agent 循环 + 工具调用 + HITL 审批 + 流式 UI） | 自接 ai-sdk | 自接 |
+| 认证 / 消息 / 队列 | **随包内置、互相咬合** | 自选 + 自缝 | 自选 + 自缝 |
+| 部署 | 一个 Node 进程 + PG + Redis | 各组件自理 | 平台绑定 |
+> 定位不是「替代某个框架」，而是**包换包**：用 weifuwu 一个依赖替换你原本要缝合的整套栈。心智模型有借鉴（两阶段组件接近 React、中间件接近 Express），但每一层都是自研的确定性实现——组件模型见[核心概念](#核心概念)，与 antd/Element Plus/shadcn 的对应见 `design/components-map.md`。
+### 从这里开始
+| 你想… | 去哪 |
+|--------|------|
+| 10 分钟跑通 SPA + SSR | [快速开始](#快速开始) |
+| 立刻体验（跑现成 demo） | 快速开始的「30 秒体验」 |
+| 零后端原型（一个 HTML 文件） | [CDN 快速原型](#cdn-快速原型零构建纯-html) |
+| 按任务找 API（认证/消息/AI/移动端…） | [能力速查](#能力速查任务--api) |
+| 读完整 API 参考 | [文档导航](#文档导航) |
 ---
 ## 设计理念
-### 一句话
-**weifuwu = 一个包的全栈框架：全自研、零配置、消灭样板、SaaS 地基随包内置。** 下面四条核心哲学与十一条技术原则都是这句话的展开——我们不做缝合框架，每一层都自研且可预测。
+> 顶部「定位」回答了**是什么 / 为什么**；以下是**哲学展开**——四条核心哲学与十一条技术原则。
 ### 核心哲学
 **① 一个包，全栈一体。** 后端、前端、组件、样式装在一个 npm 包里，零配置、零构建、纯 link 可用：服务端 `--import weifuwu/dev` 直接跑 `.tsx`（Node loader + esbuild 同步编译）；浏览器 CDN import map 直接跑；CSS 一条 link 即得完整设计系统。
-**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**（已裁剪清单见 `docs/db-clients-plan.md`）。
+**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**（已裁剪清单见 `design/db-clients-plan.md`）。
 **③ 消灭样板。** 框架的每一层都在消灭一类样板代码：
@@ -44,7 +85,7 @@ npm install weifuwu
 **两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
-**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch；也支持手动 `ctx.ui.render()` 精确控制渲染时机。**组件库手动优先、业务层自动优先**——同一框架内按角色选模式（详见[组件库](#组件库-weifuwucomponents)）。
+**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch；也支持手动 `ctx.ui.render()` 精确控制渲染时机。**组件库手动优先、业务层自动优先**——同一框架内按角色选模式（详见[组件库](docs/components.md)）。
 **中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` / `ctx.limit` / `ctx.email` / `ctx.queue` / `ctx.ai` / `ctx.msg` 等），Handler/组件从 `ctx` 读取。
@@ -52,13 +93,13 @@ npm install weifuwu
 **SPA/SSR/Hydration 统一透明** — 同一份路由定义（`routes`）一个组件三场景自动适配：后端 `uiSsr({ routes })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `router({ routes })` + `RouteView` + `mount(..., { hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
-**AI 是一等公民** — 自研 OpenAI 兼容协议（`docs/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批 + embedding 向量化。后端 `ctx.ai` 一个入口：`chat()` / `stream()` / `agent()`（`stream(messages, { emit })` emitter 抽象——事件可接任意通道，`runToResult()` 结构化结果）/ `approve()` / `embed()` / `embedMany()`；前端 `ctx.ui.useChat()`（会话语义）+ `AiChat` 组件（标准对话界面）——流式 token / 工具调用卡 / 审批卡开箱即用，协议对页面完全透明，不用 ai-sdk。
+**AI 是一等公民** — 自研 OpenAI 兼容协议（`design/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批 + embedding 向量化。后端 `ctx.ai` 一个入口：`chat()` / `stream()` / `agent()`（`stream(messages, { emit })` emitter 抽象——事件可接任意通道，`runToResult()` 结构化结果）/ `approve()` / `embed()` / `embedMany()`；前端 `ctx.ui.useChat()`（会话语义）+ `AiChat` 组件（标准对话界面）——流式 token / 工具调用卡 / 审批卡开箱即用，协议对页面完全透明，不用 ai-sdk。
-**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见文末[SaaS 地基模块](#saas-地基模块ratelimit--email--usersystem--messager--queue)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
+**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见[SaaS 地基模块](docs/saas.md)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
 **机制与策略分离** — 框架管**机制**（token 怎么签、消息怎么送达、agent 循环怎么跑），开发者管**策略**（谁能建群、租户隔离 SQL、技能注册表）。这是「诚实裁剪」的积极面：**框架不越界，应用层不被绑架**——agent-platform 迁移验证了边界：多租户隔离（`WHERE tenant_id`）、技能编排、聊天产品模型留在应用层，框架守住通用能力（auth / ai / messager / UI / 数据管道）。
-**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，品牌/组件定制改变量（`--wf-brand-500` / `--wf-btn-radius`），暗色自动（详见[布局系统](#布局系统-weifuwulayout)）。
+**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，品牌/组件定制改变量（`--wf-brand-500` / `--wf-btn-radius`），暗色自动（详见[布局系统](docs/layout.md)）。
 **自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
@@ -166,7 +207,22 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 - 改组件刷新即生效，无需构建步骤
 - 完整可运行示例见 `apps/components-demo`（组件 cheatsheet）与 `apps/agent-platform`（全栈 SaaS 应用）
-> 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」。
+> 需要 **Node.js ≥ 20.6**（`--import weifuwu/dev` 与 `node --test` 依赖）。
+### 30 秒体验（跑现有 demo）
+```bash
+# ① 组件 cheatsheet——92 组件全部可交互预览（零依赖，5 秒起）
+cd apps/components-demo && node server.ts
+# 打开 http://localhost:3000
+# ② 全栈 SaaS 示例——多租户 AI 平台（auth / AI 对话 / 部门聊天 / 知识库 / HITL 审批）
+docker compose up -d postgres redis   # 仓库根目录
+cd apps/agent-platform && npm run seed && npm run dev
+# 打开 http://localhost:3000（admin@demo.com / admin123）
+```
+> 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」——一个 `.html` 文件即可。
 ---
@@ -243,7 +299,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 |------|---------|------|
 | `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
 | `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 92 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 141 个主题 Token + 67 个布局原语 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 141 个主题 Token + 70 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
@@ -282,9 +338,35 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu/client` | **i18n** | 国际化中间件（运行时切换语言） | createApp |
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
-| `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
+| `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect` / `clampToViewport`） | — |
+| `weifuwu/client` | **移动端原语** | `usePopup`（弹层组合器）/ `useHoverCapable` / `useLongPress` / `useVisualViewport`（触屏友好由构造保证，见 [docs/mobile.md](docs/mobile.md)） | — |
 | `weifuwu/components` | **92 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
-| `weifuwu/layout` | **CSS 布局** | 67 个布局原语 + 141 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/layout` | **CSS 布局** | 70 个布局原语 + 141 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+---
+## 能力速查（任务 → API）
+按任务场景找入口（完整参考见对应 docs）：
+| 任务 | 用 | 位置 |
+|------|-----|------|
+| 起 HTTP 服务 + 路由 | `serve(app)` + `new Router()` + `app.get/post/...` | [docs/server.md](docs/server.md) |
+| 渲染页面（SPA / SSR+hydrate） | `ui()` + `uiSsr({ routes })`；`createApp()` + `router({ routes })` + `RouteView` | [docs/realtime.md](docs/realtime.md) · [docs/frontend.md](docs/frontend.md) |
+| 数据持久化 | `postgres()` → `` ctx.sql`SELECT *` `` · `redis()` → `ctx.redis` | [docs/data.md](docs/data.md) |
+| 数据管道（SSR 预取/hydration/SPA） | `ctx.data.get(key)` + `asyncComponent` | [docs/frontend.md](docs/frontend.md) |
+| 用户注册/登录/会话/多租户 | `userSystem()` → `ctx.auth` + `/api/auth/*` | [docs/saas.md](docs/saas.md) |
+| 限流防爆破 | `rateLimit()` + `ctx.limit()` | [docs/saas.md](docs/saas.md) |
+| 发邮件 | `email()` → `ctx.email`（Resend/SMTP） | [docs/saas.md](docs/saas.md) |
+| 实时消息/聊天/通知 | `messager()` → `ctx.msg` + `app.ws` | [docs/saas.md](docs/saas.md) |
+| 后台任务/定时 | `queue()` → `ctx.queue` · `scheduler()` → `ctx.schedule/cron` | [docs/saas.md](docs/saas.md) |
+| AI 对话 / Agent / HITL 审批 | `ai()` → `ctx.ai` + `ctx.ui.useChat()` + `AiChat` | [docs/saas.md](docs/saas.md) |
+| GraphQL / WebSocket | `app.graphql(handler)` · `app.ws(path, handler)` | [docs/realtime.md](docs/realtime.md) |
+| 前端 UI 组件 | `weifuwu/components`（92 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
+| 布局/主题/暗色 | `weifuwu/layout`（70 原语 + 141 Token） | [docs/layout.md](docs/layout.md) |
+| 样式定制（零自定义 CSS） | `--wf-*` 变量覆盖 + 组件定制钩子 | [docs/styling.md](docs/styling.md) |
+| 移动端适配（tap/长按/键盘/弹层） | `usePopup` / `useHoverCapable` / `useLongPress` / `useVisualViewport` | [docs/mobile.md](docs/mobile.md) |
+| 前后端类型安全中间件 | `createMiddleware`（声明注入即类型化） | [docs/server.md](docs/server.md) |
 ---
@@ -380,2953 +462,39 @@ const UserProfile = asyncComponent(async (ctx) => {
 ---
-# 后端 API (`weifuwu`)
-> 以下为完整 API 参考，按需查阅。新手建议先阅读上文的「核心概念」和「快速开始」。
-## Router
-Trie 路由，支持 URL 参数、通配符、中间件链、WebSocket、GraphQL。
-```ts
-import { Router } from 'weifuwu'
-const app = new Router()
-```
-### 路由方法
-每个路由方法接受 `path, ...middlewares[], handler`：
-```ts
-app.get('/users', handler)
-app.post('/users', handler)
-app.put('/users/:id', handler)
-app.patch('/users/:id', handler)     // PATCH
-app.delete('/users/:id', handler)    // DELETE
-app.head('/users', handler)          // HEAD
-app.options('/users', handler)       // OPTIONS
-app.all('/users', handler)           // 所有 HTTP 方法
-```
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `path` | `string` | 路由路径，支持 `:param` 和 `*` 通配符 |
-| `...middlewares` | `Middleware[]` | 路由级中间件（可选） |
-| `handler` | `Handler` 或 `Router` | 处理器或子路由器 |
-### 路由级中间件
-```ts
-declare module 'weifuwu' { interface Context { auth: { userId: string } } }
-const requireAuth: Middleware = (req, ctx, next) => {
-  if (!req.headers.get('authorization')) return new Response('Unauthorized', { status: 401 })
-  ;(ctx as any).auth = { userId: '123' }
-  return next(req, ctx)
-}
-app.get('/users/:id', requireAuth, (req, ctx) => {
-  return Response.json({ id: ctx.params.id, auth: ctx.auth })
-})
-```
-### 参数与查询
-```ts
-app.get('/posts/:category/:slug', (req, ctx) => {
-  ctx.params.category  // URL 参数
-  ctx.params.slug      // URL 参数
-  ctx.query.page       // 查询参数 ?page=1
-  return Response.json(ctx.params)
-})
-```
-### 通配符
-```ts
-app.get('/files/*', (req, ctx) => {
-  ctx.params['*']  // 剩余路径 "a/b/c.txt"
-  return Response.json({ path: ctx.params['*'] })
-})
-```
-### 子路由挂载
-```ts
-const users = new Router()
-users.get('/', listUsers)
-users.get('/:id', getUser)
-app.mount('/api/users', users)
-// → GET /api/users, GET /api/users/:id
-```
-### 插件模式
-```ts
-app.plugin(app => {
-  app.get('/health', () => Response.json({ ok: true }))
-  app.use(cors())
-})
-```
-### 类型安全中间件工厂
-```ts
-import { createMiddleware } from 'weifuwu'
-declare module 'weifuwu' { interface Context { greeting: string } }
-const greet = createMiddleware({
-  injects: ['greeting'],           // 注入的 ctx 字段
-  depends: ['sql'],                // 前置依赖（可选）
-  setup: async (ctx) => ({
-    greeting: 'Hello ' + ctx.params.name
-  }),
-})
-app.use(greet)
-app.get('/hello/:name', (req, ctx) => Response.json({ msg: ctx.greeting }))
-```
-`createMiddleware` 自动生成 `__meta` 元数据用于运行时依赖检查。
-### 查看路由表
-```ts
-console.log(app.routes())
-// → [
-//   "GET      /users",
-//   "POST     /users",
-//   "WS       /chat",
-//   "MIDDLEWARE  [2 global]"
-// ]
-```
-### 路由方法速查
-| 方法 | 说明 |
-|------|------|
-| `app.get(path, ...mws, handler)` | GET |
-| `app.post(path, ...mws, handler)` | POST |
-| `app.put(path, ...mws, handler)` | PUT |
-| `app.patch(path, ...mws, handler)` | PATCH |
-| `app.delete(path, ...mws, handler)` | DELETE |
-| `app.head(path, ...mws, handler)` | HEAD |
-| `app.options(path, ...mws, handler)` | OPTIONS |
-| `app.all(path, ...mws, handler)` | 任意方法 |
-| `app.use(mw)` | 全局中间件 |
-| `app.ws(path, ...mws, handler)` | WebSocket |
-| `app.graphql(path?, handler)` | GraphQL |
-| `app.mount(path, subRouter)` | 挂载子路由 |
-| `app.plugin(fn)` | 插件扩展现有 Router |
-| `app.onError(handler)` | 全局错误处理 |
-| `app.wsHub(hub)` | 注入自定义 Hub（多进程 WebSocket） |
-| `app.onClose(closeable)` | 注册关闭回调 |
-| `app.routes()` | 打印路由表 |
-| `app.close()` | 关闭所有注册的 Closeable 资源 |
----
-## serve — HTTP 服务器
-```ts
-import { serve, Router } from 'weifuwu'
-const app = new Router()
-const server = serve(app, { port: 3000 })
-// 等待就绪
-await server.ready
-console.log(server.port) // 实际端口
-// 停止
-await server.close()
-// 或
-await server.stop(2000)  // 超时毫秒
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `port` | `number` | `0`（随机） | 监听端口 |
-| `hostname` | `string` | `'0.0.0.0'` | 监听地址 |
-| `signal` | `AbortSignal` | — | 通过信号停止 |
-| `maxBodySize` | `number` | `10MB` | 请求体上限（0=无限） |
-| `timeout` | `number` | `120000` | Socket 超时（ms，2 分钟，适配 LLM 生成等长任务） |
-| `keepAliveTimeout` | `number` | `5000` | Keep-Alive 超时 |
-| `headersTimeout` | `number` | `6000` | 请求头超时 |
-| `shutdown` | `boolean` | `true` | 自动注册 SIGTERM/SIGINT |
-| 属性/方法 | 类型/签名 | 说明 |
-|-----------|----------|------|
-| `server.port` | `number` | 实际监听端口（未就绪时 0） |
-| `server.hostname` | `string` | 监听地址 |
-| `server.ready` | `Promise<void>` | 服务器就绪 |
-| `server.close(timeoutMs?)` | `() => Promise<void>` | 优雅关闭 |
-| `server.stop(timeoutMs?)` | `() => Promise<void>` | `close` 别名 |
-`sig-server` 自动注册 SIGTERM/SIGINT → `server.closeAllConnections()` → `router.close()` → `process.exit(0)`。
----
-## cors — CORS 中间件
-```ts
-import { cors } from 'weifuwu'
-// 默认：允许所有来源
-app.use(cors())
-// 自定义
-app.use(cors({
-  origin: 'https://app.example.com',
-  methods: ['GET', 'POST'],
-  allowedHeaders: ['Content-Type', 'Authorization'],
-  credentials: true,
-  exposedHeaders: ['X-Total-Count'],
-  maxAge: 86400,
-}))
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `origin` | `string \| string[] \| (origin) => string` | `'*'` | `credentials: true` 时自动回显请求 origin |
-| `methods` | `string[]` | `GET,HEAD,PUT,PATCH,POST,DELETE` | 允许的方法 |
-| `allowedHeaders` | `string[]` | `Content-Type, Authorization` | 允许的请求头 |
-| `exposedHeaders` | `string[]` | — | 暴露的响应头 |
-| `credentials` | `boolean` | — | 是否允许凭据 |
-| `maxAge` | `number` | — | 预检缓存秒数 |
----
-## serveStatic — 静态文件服务
-```ts
-import { serveStatic } from 'weifuwu'
-// 作为全局中间件（未匹配到文件时走下一个中间件）
-app.use(serveStatic('./public'))
-// 或挂载到特定路径
-app.get('/assets/*', serveStatic('./assets', {
-  index: 'index.html',
-  maxAge: 31536000,
-  immutable: true,
-}))
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `index` | `string` | `'index.html'` | 目录索引文件名 |
-| `maxAge` | `number` | `0` | Cache-Control max-age（秒） |
-| `immutable` | `boolean` | — | 添加 `immutable` 指令（需 maxAge） |
-特性：
-- ETag/304 缓存协商（`if-none-match` + `if-modified-since`）
-- MIME 类型自动检测（支持 30+ 扩展名）
-- 目录遍历保护（`..` / symlink 逃逸 → 403）
-- 目录自动跳转到 index 文件
 ---
-## postgres — PostgreSQL 客户端（自研）
-> **自研 PG v3 协议**（零第三方依赖）——支持 SCRAM-SHA-256 认证、扩展查询（参数化）、类型映射（int8 超范围自动 string 防丢精度）、事务、连接池（acquire 超时防饿死）、schema 写前校验、statement_timeout 慢查询保护。
-```ts
-import { postgres } from 'weifuwu'
-// 注入 ctx.sql（懒连接池）
-app.use(postgres())
-// ① tagged template —— 插值自动参数化（防注入）
-app.get('/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  return Response.json(users)
-})
-// ② jsonb 对象直传——自动序列化，不再有双重编码/parseRow 样板
-app.post('/decks', async (req, ctx) => {
-  const deck = await req.json()
-  await ctx.sql`INSERT INTO decks (title, deck_json) VALUES (${deck.title}, ${deck})`
-  // 读回来自动是对象：rows[0].deck_json === { slides: [...] }（不是字符串）
-})
-// ③ 事务（postgres.js 兼容 begin）
-app.post('/transfer', async (req, ctx) => {
-  await ctx.sql.begin(async sql => {
-    await sql`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
-    await sql`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
-  })
-})
-```
-### 类型映射（自动）
-| 数据库类型 | 返回 JS 类型 |
-|-----------|-------------|
-| json / jsonb | `object`（自动 JSON.parse） |
-| int2 / int4 / int8（安全范围内） | `number` |
-| **int8（超出安全范围）** | **`string`**（防静默丢精度，金额/ID 关键） |
-| float / numeric | `number` |
-| boolean | `boolean` |
-| text / varchar / uuid | `string` |
-| **timestamptz** | **`Date`**（带时区，ISO 解析无本地时区魔法） |
-| timestamp / date / interval | `string`（无时区语义——转 Date 按本地时区解析即时区魔法，诚实裁剪不转） |
-| NULL | `null` |
+## 文档导航
-### 类型层（查询泛型 + schema 写前校验）
-```ts
-// ① 查询结果泛型（编译期类型，无需手写 interface + 断言）
-interface Deck { id: number; title: string; deck_json: { slides: unknown[] } }
-const decks = await ctx.sql.query<Deck>('SELECT id, title, deck_json FROM decks')
-// ② schema 注册 → insert 写前校验（脏数据源头拦截）
-ctx.sql.register('decks', {
-  title: { type: 'text', required: true },
-  status: { type: 'enum', values: ['outline', 'ready'] },
-  deck_json: { type: 'jsonb' },
-})
-await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → ValidationError
-```
+README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模块总览）。完整 API 参考按**开发者角色**拆分在 `docs/`，设计与计划文档在 `design/`：
-### 方法面
+### 后端开发者
-| 方法 | 说明 |
+| 文档 | 内容 |
 |------|------|
-| `ctx.sql\`...\`` | tagged template → 参数化查询（插值=参数，表名需硬编码） |
-| `ctx.sql.query<T>(sql, params?)` | 参数化查询 + 泛型 |
-| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名） |
-| `ctx.sql.begin(fn)` | 事务（回调收到 tagged template sql） |
-| `ctx.sql.transaction(fn)` | 事务（回调收到 `{ query }`） |
-| `ctx.sql.register(table, schema)` | 注册表结构（写前校验） |
-| `ctx.sql.insert(table, row)` | schema 校验 + 参数化插入 |
-| `ctx.sql.insertMany(table, rows[], { batchSize? })` | **批量插入**：多行 VALUES 单次往返（默认 500/批；所有行键必须一致） |
-| `ctx.sql.update(table, set, where, { returning? })` | **参数化 UPDATE**：SET/WHERE 全部参数化，返回 `affectedRows` |
-| `ctx.sql.delete(table, where)` | **参数化 DELETE**：WHERE 必填（防全表误删），返回 `affectedRows` |
-| `ctx.sql\`...\` 内嵌片段` | 条件 SQL 片段（嵌套过滤，参数自动重编号） |
-| `ctx.sql.close()` | 关闭连接池 |
-### 影响行数（affectedRows）
-`INSERT / UPDATE / DELETE / MERGE` 的返回行数组带**非枚举** `affectedRows` 属性（不干扰 `deepEqual`/`JSON.stringify`）：
-```ts
-const r = await ctx.sql`UPDATE messages SET read = true WHERE id = ${id}`
-if (r.affectedRows === 0) return new Response('not found', { status: 404 })
-```
-```ts
-// 批量插入：100 行 1 次往返
-await ctx.sql.insertMany('agent_logs', logs, { batchSize: 500 })
-// 语义化更新/删除：WHERE 全参数化 + 返回影响行数
-await ctx.sql.update('users', { role: 'admin' }, { id: userId })
-await ctx.sql.delete('messages', { id: msgId })
-### 条件片段（嵌套过滤）
-```ts
-const status = req.query.status // 可能为空
-const rows = await ctx.sql`
-  SELECT * FROM orders WHERE amount > ${100}
-    ${status ? ctx.sql`AND status = ${status}` : ctx.sql``}
-`
-// 空片段内联为空，参数自动重编号——同一 SQL 无论条件多少都安全参数化
-```
-### 选项
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `connection` | `string` | `DATABASE_URL` | 连接字符串 |
-| `max`（或 `poolSize`） | `number` | `10` | 连接池大小 |
-| `acquireTimeoutMs` | `number` | `30000` | 池全忙时 acquire 超时（防饿死，0=无限） |
-| `statementTimeoutMs`（或 `statementTimeout`） | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
-| `idleTimeoutMs` | `number` | `0` | 空闲连接回收（超时未用关闭，容量收缩后自动重建；0=禁用） |
-| `onQuery` | `(sql, durationMs, rowCount, traceId?) => void` | — | 查询观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
-### 幂等迁移（内置）
-`postgres()` 返回的中间件自带迁移跟踪（`_weifuwu_migrations` 表），模块启动时检查-执行-记录三步幂等：
-```ts
-const db = postgres()
-await db.migrate()        // ① 建迁移跟踪表（幂等）
-if (!(await db.isMigrated('users'))) {       // ② 检查是否已迁移
-  await db.sql.unsafe(`CREATE TABLE users (...)`)
-  await db.markMigrated('users')             // ③ 记录（幂等，重复调用无害）
-}
-app.use(db)
-```
-> 多副本部署时天然安全：`markMigrated` 用 `ON CONFLICT DO NOTHING`，两个实例同时迁移也不会重复执行。
-### 错误映射（自动）
-`ctx.sql` 查询错误自动映射为 `HttpError`，业务无需手写 catch：
-| 错误码 | 含义 | HTTP |
-|--------|------|------|
-| `23505` | 唯一约束冲突 | **409** |
-| `23503` / `23502` / `23514` | 外键 / 非空 / 检查约束 | **400** |
-| `22P02` / `22003` | 类型 / 数值错误 | **400** |
-> 未映射的错误码原样抛出（带 `code` 属性，如 `42P01` 表不存在）。
-> **裁剪声明**：逻辑复制 / 大对象 / 显式游标 / 二进制 COPY 不支持（明确抛 `ProtocolError('unsupported')`，而非静默出错）。
----
-## redis — Redis 客户端（自研）
-> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。**二进制安全**：`getBuffer(key)` 原样返回字节（缓存序列化 payload 不损坏）。
-```ts
-import { redis } from 'weifuwu'
-app.use(redis())
-// ① TTL 安全 —— 直接传秒，不会写错
-app.post('/cache/:key', async (req, ctx) => {
-  const { value } = await req.json()
-  await ctx.redis.set(ctx.params.key, value, 3600)  // ioredis 要 set(k, v, 'EX', 3600)
-})
+| [docs/server.md](docs/server.md) | HTTP 服务层：Router / serve / cors / serveStatic / HttpError / 响应辅助 / parseBody |
+| [docs/data.md](docs/data.md) | 数据层：postgres（PG v3 自研协议）/ redis（RESP2 自研协议） |
+| [docs/realtime.md](docs/realtime.md) | 实时与渲染：scheduler / ui（SSR + JS/CSS 编译）/ graphql / WebSocket |
+| [docs/saas.md](docs/saas.md) | SaaS 地基：rateLimit / email / userSystem / messager / queue / ai |
-// ② JSON 零样板 —— 自动序列化（AI 缓存场景）
-app.get('/cache/:key', async (req, ctx) => {
-  const val = await ctx.redis.jsonGet(ctx.params.key)  // 自动 JSON.parse
-  return Response.json(val ?? { miss: true })
-})
-// ③ 缓存便捷 —— 读-算-写一体，null 不缓存（防穿透）
-app.get('/llm/:id', async (req, ctx) => {
-  const result = await ctx.redis.cache(`llm:${ctx.params.id}`, async () => {
-    return await generateLLM(ctx.params.id)  // miss 才执行
-  }, 3600)
-  return Response.json(result)
-})
-// ④ Pub/Sub —— 发布用 ctx.redis，订阅用独立连接（回调式，断线自动重连恢复订阅）
-app.post('/events', async (req, ctx) => {
-  await ctx.redis.publish('events', JSON.stringify({ type: 'deck.created' }))
-})
-const sub = ctx.redis.createSubscriber()
-await sub.connect()
-await sub.subscribe('events', (channel, message) => {
-  // 收到实时消息
-})
-await sub.psubscribe('jobs:*', (channel, message) => {
-  // 模式匹配订阅
-})
+### 前端开发者
-// ⑤ 任意命令透传 + keyPrefix 隔离
-await ctx.redis.command('LRANGE', 'list', '0', '-1')
-app.use(redis({ keyPrefix: 'api:' }))  // 之后所有 key 自动加前缀
-await ctx.redis.set('user', 1)         // 实际写入 'api:user'
-```
-### 方法面
-| 方法 | 说明 |
+| 文档 | 内容 |
 |------|------|
-| `get / set(key, val, ttl?) / del / incr / expire / ttl` | 基础命令（set 直接传秒） |
-| `jsonGet / jsonSet(key, val, ttl?)` | JSON 自动序列化 |
-| `cache(key, fn, ttl)` | 缓存读-算-写（null 不缓存防穿透） |
-| `publish(channel, msg)` | Pub-Sub 发布 |
-| `createSubscriber()` | 独立订阅连接（`subscribe`/`psubscribe` 回调式） |
-| `hset / hget / hgetall / hdel` | hash 字段读写（`hgetall` → `Record`，缺失 `{}`） |
-| `lpush / rpush / lpop / rpop / lrange` | list 队列操作（`lrange` 支持负数区间） |
-| `sadd / srem / smembers` | set 成员操作（`sadd` 重复不加） |
-| `zadd / zrange` | zset 有序集（score 升序） |
-| `mget / mset / exists / setnx / incrby` | 批量读写 / 存在性 / 原子设值（锁基础）/ 增量 |
-| `pipeline()` | 管道：批量命令一次往返（池级，key 自动加前缀） |
-| `command(name, ...args)` | 底层命令透传 |
-| `close()` | 关闭连接池 |
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
-| `poolSize` | `number` | `5` | 连接池大小 |
-| `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
-| `commandTimeoutMs` | `number` | `0` | 命令超时（阻塞命令 resolve(null)；防挂起。0=禁用） |
-| `socketTimeoutMs` | `number` | `0` | socket 响应超时（僵尸连接自愈：pending 有命令且超时无数据 → 主动断开重连。0=禁用） |
-> **连接健康**：断线自动剔除死连接并重建（池不萎缩）；`CLIENT KILL`/网络抖动后服务自愈，命令不命中死连接。
-> **裁剪声明**：集群（MOVED 路由）/ 哨兵 / 自动管道不支持（standalone 优先）。
----
-## scheduler — 计划任务（即时/延时/cron）
-> 依赖 `queue`（触发后入队执行）。三类任务：即时（queue.add 已有）、延时（`ctx.schedule`）、定时（`ctx.cron`）。
-```ts
-import { queue, scheduler } from 'weifuwu'
-const q = queue()
-app.use(q)
-app.use(scheduler({ queue: q }))       // 依赖 ctx.queue（触发后入队）
-// 延时任务（单次）：delayMs 或指定时间
-await ctx.schedule('email.send', { to, body }, { delayMs: 30_000 })
-await ctx.schedule('report.build', {}, { when: new Date('2026-09-01T00:00:00Z') })
-// cron 定时任务（重复）：每分钟触发 → 入队执行
-ctx.cron('* * * * *', 'heartbeat.check', { scope: 'health' })
-// 改需求 = 重新注册（同 name 覆盖更新，旧定义不残留）
-ctx.cron('*/5 * * * *', 'heartbeat.check', { scope: 'health' })
-// 停用 = cancel（删定义 + 清理 pending 触发点）
-await ctx.cancelCron('heartbeat.check')
-// 执行端：与 queue 完全一致
-const worker = ctx.queue.worker('email.send', async (job) => { ... })
-```
-- **延时**：ZSET（score=触发时间戳）+ 守护循环（独立连接）→ 到期 `ZREM` 原子抢占（多实例不重复）→ `queue.add`
-- **多应用隔离**：`scheduler({ prefix })`——ZSET/HASH 应用级共享，多应用共用 redis 时必须各自 prefix（同应用多实例共享 prefix = 协作消费）
-- **cron**：HASH 注册表（**field = name，同 name 重新注册 = 覆盖更新**，改表达式不残留旧定义）+ 滚动生成触发点（`ZADD NX` 幂等）→ 复用延时链路；`nextRunAt` 原子推进
-- **取消**：`ctx.cancelCron(name)` 删定义 + 清理 pending 触发点（停用 cron 必须 cancel——定义无 TTL 会累积）
-- **崩溃恢复**：未消费触发点留在 ZSET，重启后补扫立即触发（at-least-once，幂等由业务保证）
-- **cron 表达式**：5 字段（分 时 日 月 周），支持 `*`/步进/列表/范围；时区 = 服务器本地；非法表达式注册即抛错
-- **裁剪**：❌ cron 秒/年/别名（@daily）/特殊字符（L/W/#）、时区配置、单次任务取消（v2）、分布式锁（原子命令抢占替代）
-- **文档红线**：cron 定义持久化在 HASH——进程重启后守护循环恢复即继续触发（无需重新注册）；**停用必须 `cancelCron`**（定义无 TTL，不取消会永久触发）
-## ui — SSR 渲染 + JS/CSS 编译
-```ts
-import { ui } from 'weifuwu'
-app.use(ui())
-```
-| ctx 注入 | 签名 | 说明 |
-|----------|------|------|
-| `ctx.ui.html` | `` (strings, ...values) => Response `` | HTML 模板 (转义防 XSS) |
-| `ctx.ui.html.unsafe(str)` | `(string) => string` | 插入原始 HTML |
-| `ctx.ui.js(entryPath)` | `(string) => Promise<Response>` | esbuild 编译 TSX → JS bundle |
-| `ctx.ui.css(entryPath)` | `(string) => Promise<Response>` | 读取 CSS 文件 → CSS Response（如安装 postcss + @tailwindcss/postcss 则自动编译） |
-| `ctx.ui.ssr(Comp, props?, { data })` | `(Component, props, opts?) => Promise<string>` | 服务端渲染组件 → HTML 片段（async 工厂自动 await；HtmlSafe 内联不二次转义） |
-| `ctx.ui.ssrData(data)` | `(Map) => string` | 序列化 SSR 数据 → `<script>window.__DATA__=...</script>`（`<` 转义防 XSS） |
-### ctx.ui.html — HTML 模板
+| [docs/frontend.md](docs/frontend.md) | 前端核心：createApp / 组件模型 / 状态管理 / 条件与列表 / ref / 类型 |
+| [docs/frontend-middleware.md](docs/frontend-middleware.md) | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
+| [docs/components.md](docs/components.md) | 组件库（92 个组件 + 使用示例 + 组件列表） |
+| [docs/layout.md](docs/layout.md) | 布局系统：70 个布局原语 + 141 个主题 Token |
+| [docs/styling.md](docs/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
-模板插值自动转义（`& < > "` → 实体），防 XSS：
+### 通用
-```ts
-app.get('/page', (req, ctx) => ctx.ui.html`
-  <h1>${title}</h1>          <!-- 自动转义 -->
-  <div>${ctx.ui.html.unsafe(richHtml)}</div>  <!-- 不转义 -->
-`)
-```
-### ctx.ui.js — 编译 TSX → JS
-```ts
-app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))   // 相对路径
-app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/client'))   // 或包名
-```
-使用 esbuild 编译：
-- `bundle: true`, `format: 'esm'`, `platform: 'browser'`
-- `jsx: 'automatic'`, `jsxImportSource: 'weifuwu/client'`
-- 带 mtime 缓存验证（开发时编辑文件后自动失效）
-### ctx.ui.css — CSS 编译
-```ts
-app.get('/style.css', (req, ctx) => ctx.ui.css('./src/style.css'))               // 相对路径
-app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))   // 或包名
-```
-- 无编译工具时直接返回原始 CSS
-- 检测到已安装 `postcss` + `@tailwindcss/postcss` 时自动编译 Tailwind CSS
-- 支持包名（`weifuwu/layout/style.css`, `weifuwu/components/style.css`）或文件路径
-- 带 mtime 缓存验证（开发时编辑文件后自动失效）
-### ctx.ui.ssr — SSR 渲染组件 → HTML
-将组件（含 async 工厂组件）在服务端渲染为完整 HTML 片段，数据经 `ctx.data` 预取并序列化进 `window.__DATA__`（客户端 hydration 时同步命中，不重跑请求）：
-```ts
-const BlogPage = asyncComponent(async (ctx) => {
-  const post = await ctx.data.get(`/api/posts/${ctx.params.slug}`, fetchPost)
-  return (_init, ctx) => () =>
-    h('article', {},
-      h('h1', {}, post.title),
-      h('div', { innerHTML: post.body }),
-    )
-})
-app.get('/blog/:slug', async (req, ctx) => {
-  const data = new Map()
-  const html = await ctx.ui.ssr(BlogPage, {}, { data })   // HtmlSafe：模板内联不二次转义
-  return ctx.ui.html`
-    <!DOCTYPE html>
-    <html><body>
-      <div id="root">${html}</div>
-      ${ctx.ui.ssrData(data)}
-      <script src="/static/app.js"></script>
-    </body></html>
-  `
-})
-```
-- 事件处理器/ref 剥离，文本自动转义（XSS），`class`/`style` 对象序列化，`innerHTML` 原样输出
-- Fragment/Portal 子节点就地内联
-- `ctx.ui.ssrData(data)` 输出 `<script>window.__DATA__=...</script>`（JSON `<` 转义防 XSS）
-- 服务端 ctx shim：`$`（dirty no-op）、`ctx.data` 预取去重、`selfId` 请求级隔离
-### Hydration — 客户端收养服务端 HTML
-服务端 HTML + `window.__DATA__`（ctx.data 种子）到达客户端后，`mount(..., { hydrate: true })` **收养现有 DOM**（不重建、不闪跳），只接线事件/ref/$：
-```ts
-import { createApp } from 'weifuwu/client'
-createApp()
-  .mount('#root', BlogPage, { hydrate: true })   // 容器已有服务端 HTML
-```
-- **游标收养**：元素/文本按位置匹配现有 DOM；tag 不匹配 → 局部替换；文本不一致 → 就地修正；服务端多余节点 → 收尾清理
-- **async 工厂 hydration**：工厂 `ctx.data.get` 从 `__DATA__` 同步命中（不重跑请求）→ 渲染与服务端一致 → 收养
-- hydration 后 `$`/dirty/事件全量可用（与纯 SPA 无差别）
-- 诚实裁剪：Portal 内容就地收养（不移动到 `#__wf_portal`）；渲染期非确定性（Date/random）会导致 mismatch（dev 警告）
-### uiSsr — 路由级 SSR（声明即渲染）
-共享路由定义，前后端同一份声明——后端匹配即自动 SSR，无需手写 handler/模板/序列化：
-```tsx
-// routes.tsx —— 前后端共用
-import type { RouteDef } from 'weifuwu/client'
-import { BlogPage } from './pages/BlogPage.tsx'
-export const routes: RouteDef[] = [
-  { path: '/blog/:slug', component: BlogPage, title: '博客' },
-]
-// server.ts —— 一行中间件：GET 匹配 → 注入 ctx.route.params → await 组件工厂 → 完整 HTML + __DATA__ + bundle
-import { uiSsr } from 'weifuwu'
-app.use(uiSsr({ routes, bundle: '/static/blog.js' }))
-// blog-hydrate.ts —— 客户端：同一份 routes，router() 注入 ctx.route.params（两端同源）
-createApp()
-  .use(router({ routes }))
-  .mount('#root', routes[0].component, { hydrate: true })
-```
-- 组件工厂读 `ctx.route.params`（`/blog/:slug` → `ctx.route.params.slug`）——后端 uiSsr / 前端 router **同源注入**
-- 未匹配 → next()（交给 API/静态/404）；非 GET → next()
-- 可自定义 `title` / `template`
-### weifuwu/dev — 服务端直接跑 .tsx
-Node 原生 TS 只剥离类型（不支持 JSX）。`weifuwu/dev` 注册 esbuild loader，服务端直接跑 `.tsx`（零构建）：
-```json
-{
-  "scripts": {
-    "dev": "node --import weifuwu/dev server.ts",
-    "start": "node --import weifuwu/dev server.ts"
-  }
-}
-```
-- 前后端同一 JSX 运行时（`jsxImportSource: weifuwu/client`）→ 两端 VNode 一致 → hydration 可靠
-- 与 `ctx.ui.js` 前端动态编译同一理念：无构建、无产物、改代码即生效
----
-## graphql — GraphQL 端点
-> **SDL + resolvers 绑定为自研实现**（`makeExecutableSchema`，56 行替代 @graphql-tools/schema）——支持根类型与嵌套类型字段 resolver、默认属性查找。
-```ts
-import type { GraphQLHandler } from 'weifuwu'
-const handler: GraphQLHandler = async (req, ctx) => ({
-  schema: `
-    type Query {
-      hello: String
-      users: [User]
-    }
-    type User { id: ID, name: String }
-  `,
-  resolvers: {
-    Query: {
-      hello: () => 'world',
-      users: () => [{ id: 1, name: 'Alice' }],
-    },
-  },
-  rootValue: {},
-  context: (req, ctx) => ({ user: ctx.user }),
-  graphiql: true,
-  maxDepth: 10,
-  timeout: 30000,
-})
-// 挂载到 /
-app.graphql(handler)
-// 或挂载到自定义路径
-app.graphql('/graphql', handler)
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `schema` | `string \| GraphQLSchema` | — | SDL 字符串或 Schema 对象 |
-| `resolvers` | `any` | — | 解析器（schema 为字符串时必填）|
-| `rootValue` | `any` | — | 根值 |
-| `context` | `(req, ctx) => object` | — | 上下文工厂 |
-| `graphiql` | `boolean` | — | 启用 GraphiQL IDE |
-| `maxDepth` | `number` | `10` | 查询深度限制（0=关闭）|
-| `timeout` | `number` | `30000` | 执行超时（ms，0=关闭）|
-GET 请求支持 query 参数查询；POST 支持 JSON body。启用 `graphiql: true` 时，GET 无 `?query=` 参数返回 GraphiQL IDE 页面。
----
+| 文档 | 内容 |
+|------|------|
+| [docs/examples.md](docs/examples.md) | 组合场景示例：登录表单 / 数据列表 + 搜索 / 消息提示 |
+| [docs/environment.md](docs/environment.md) | 环境变量与开发命令 |
+| [docs/mobile.md](docs/mobile.md) | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
+| [design/](design/) | 设计与计划文档（组件地图 / AI 协议契约 / 移动端指南 / 数据库客户端计划 / 设计系统 / 各阶段计划） |
-## WebSocket
-```ts
-app.ws('/chat/:room', {
-  open(ws, ctx) {
-    ws.send(`欢迎加入 ${ctx.params.room} 房间`)
-    ctx.hub?.join(ctx.params.room, ws)
-  },
-  message(ws, ctx, data) {
-    // data: string | Buffer
-    ctx.hub?.send(ctx.params.room, `用户: ${data}`)
-  },
-  close(ws, ctx) {
-    ctx.hub?.leave(ws)
-  },
-  error(ws, ctx, error) {
-    console.error('WS error:', error)
-  },
-})
-```
-| 回调 | 参数 | 说明 |
-|------|------|------|
-| `open(ws, ctx)` | `WebSocket`, `Context` | 连接建立 |
-| `message(ws, ctx, data)` | `WebSocket`, `Context`, `string \| Buffer` | 收到消息 |
-| `close(ws, ctx)` | `WebSocket`, `Context` | 连接关闭 |
-| `error(ws, ctx, error)` | `WebSocket`, `Context`, `Error` | 错误 |
-### Hub — WebSocket 房间
-```ts
-// 注入 hub → ctx.hub
-app.ws('/chat/:room', {
-  open(ws, ctx)  { ctx.hub.join(ctx.params.room, ws) },
-  message(ws, ctx, data) { ctx.hub.send(ctx.params.room, String(data)) },
-  close(ws, ctx) { ctx.hub.leave(ws) },
-})
-// 自定义 Hub（Redis 后端）
-import type { Hub } from 'weifuwu'
-const redisHub: Hub = { ... }
-app.wsHub(redisHub)
-```
-| Hub 方法 | 说明 |
-|----------|------|
-| `join(key, ws)` | WebSocket 加入房间 |
-| `leave(ws)` | WebSocket 离开所有房间 |
-| `send(key, message)` | 向房间广播消息 |
-| `close()` | 关闭 Hub |
-WebSocket 原生 `ws.send()` 发送，`ws.on('message', cb)` WebSocket 接收。
-> **实时应用推荐用 `messager()`**（SaaS 地基模块）：协议内置（`connected/subscribe/ping`）+ 持久化 + 跨进程广播 + 点对点，不必自写 Hub/协议——见[消息系统章节](#messager--消息系统)。
----
-## HttpError — HTTP 错误
-```ts
-import { HttpError } from 'weifuwu'
-app.get('/secure', () => {
-  if (!condition) throw new HttpError('Forbidden', 403)
-  // serve() 自动捕获并返回对应状态码
-})
-```
-| API | 说明 |
-|-----|------|
-| `new HttpError(msg, status)` | 创建 HTTP 错误，name = 'HttpError' |
-> 请求体上限常量 `DEFAULT_MAX_BODY`（10MB）见上方 serve 选项表 `maxBodySize`。
----
-## 响应辅助函数
-> 以下为完整 API 参考，按需查阅。五个 SaaS 地基模块（rateLimit / email / userSystem / messager / queue）见文末「SaaS 地基模块」章节。
-消除 `Response.json(...)` 重复模式：
-```ts
-import { ok, created, noContent, badRequest, unauthorized, forbidden, notFound, conflict, unprocessable, tooManyRequests, serverError, redirect } from 'weifuwu'
-app.get('/users/:id', async (req, ctx) => {
-  const user = await findUser(ctx.params.id)
-  if (!user) return notFound('用户不存在')
-  return ok(user)
-})
-app.post('/users', async (req, ctx) => {
-  const body = await parseBody(req)
-  const user = await createUser(body)
-  return created(user)
-})
-```
-| 函数 | 状态码 | Content-Type |
-|------|--------|-------------|
-| `ok(data, init?)` | 200 | `application/json` |
-| `created(data, init?)` | 201 | `application/json` |
-| `noContent(init?)` | 204 | — |
-| `badRequest(msg?)` | 400 | `application/json` |
-| `unauthorized(msg?)` | 401 | `application/json` |
-| `forbidden(msg?)` | 403 | `application/json` |
-| `notFound(msg?)` | 404 | `application/json` |
-| `conflict(msg?)` | 409 | `application/json` |
-| `unprocessable(msg?)` | 422 | `application/json` |
-| `tooManyRequests(msg?)` | 429 | `application/json` |
-| `serverError(msg?)` | 500 | `application/json` |
-| `redirect(url, status?)` | 302 (默认) | — |
----
-## parseBody — 请求体解析
-```ts
-import { parseBody } from 'weifuwu'
-app.post('/users', async (req, ctx) => {
-  const body = await parseBody<{ name: string; email: string }>(req)
-  // JSON 解析失败自动 throw HttpError(400)
-  return ok(body)
-})
-```
-| 行为 | 说明 |
-|------|------|
-| JSON 格式正确 | 返回解析后的数据 |
-| JSON 格式错误 | `throw new HttpError('Invalid JSON body', 400)` |
-| GET/HEAD 请求 | 返回 `{}` |
----
-## 后端类型
-```ts
-import type { Context, Handler, Middleware, ErrorHandler, User, Closeable } from 'weifuwu'
-import type { HttpError } from 'weifuwu'
-import type { ServeOptions, Server } from 'weifuwu'
-import type { Hub, WebSocketHandler } from 'weifuwu'
-import type { WebSocket } from 'weifuwu'
-import type { CORSOptions } from 'weifuwu'
-import type { ServeStaticOptions } from 'weifuwu'
-import type { PostgresOptions, PostgresClient, PostgresInjected } from 'weifuwu'
-import type { RedisOptions, RedisClient, RedisInjected } from 'weifuwu'
-import type { MessagerOptions, MessagerClient, MessagerInjected } from 'weifuwu'
-import type { GraphQLOptions, GraphQLHandler } from 'weifuwu'
-```
-| 类型 | 签名 | 说明 |
-|------|------|------|
-| `Context` | `interface` | `{ params, query, mountPath, user, loaderData?, env?, [key]: unknown }` |
-| `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` | 请求处理器 |
-| `Middleware<In, Out>` | `(req, ctx: In, next) => Response` | 中间件，含 `__meta` |
-| `ErrorHandler<T>` | `(error, req, ctx: T) => Response` | 错误处理器 |
-| `Closeable` | `interface` | `{ close(): Promise<void> }` |
-| `User` | `interface` | `{ id, role?, tenant?, [key]: unknown }` |
-| `HttpError` | `class` | `extends Error`，含 `status` 属性 |
----
-# 前端 API (`weifuwu/client`)
-> 以下为完整 API 参考，按需查阅。新手建议先阅读上文的「组件模型」和「状态管理」。
-零外部 npm 运行时依赖。组件签名：`(initProps, ctx) => (props) => VNode`（两阶段模型，外层 mount 只一次，内层 render 每次变化时执行）。无状态组件可简写为 `() => () => VNode`。
-构建配置（esbuild）：
-```js
-esbuild.build({
-  jsx: 'automatic',
-  jsxImportSource: 'weifuwu/client',
-  bundle: true,
-})
-```
----
-## createApp — 应用引导
-```tsx
-import { createApp } from 'weifuwu/client'
-const app = createApp()
-// 注册中间件
-app.use(middleware1)
-app.use(middleware2)
-// 挂载到 DOM
-app.mount('#root', RootComponent)
-// 获取当前 ctx
-console.log(app.ctx)
-// 销毁
-app.destroy()
-```
-| 方法 | 说明 |
-|------|------|
-| `createApp()` | 创建应用实例 |
-| `app.use(mw)` | 注册 AppMiddleware |
-| `app.mount(selector, RootComponent)` | 挂载到 DOM |
-| `app.destroy()` | 卸载应用 |
-| `app.ctx` | 当前 WfuiContext |
----
-## 组件模型
-```tsx
-import type { Component, WfuiContext } from 'weifuwu/client'
-// 两阶段组件：mount（只一次）→ render（每次 dirty/props 变化）
-const Counter: Component = (_init, ctx) => {
-  // ── mount ──
-  let count = 0
-  // ── render ──
-  return (props) =>
-    h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
-}
-// 无状态组件：只有 render
-const Badge: Component = () =>
-  (props) => h('span', { class: `badge-${props.variant}` }, props.children)
-```
-### 类型流（props 泛型 + ctx 注入）
-```tsx
-import type { Component } from 'weifuwu/client'
-import type { ApiInjected, RouteInjected } from 'weifuwu/client'
-// ① props 泛型：JSX 使用时自动类型检查（传错类型编译期报错）
-interface DeckCardProps { title: string; pages: number }
-const DeckCard: Component<DeckCardProps> = (_init, ctx) =>
-  (props) => <div>{props.title} / {props.pages} 页</div>
-// <DeckCard title="x" pages={8} />     ✓
-// <DeckCard title="x" pages="8" />     ✗ 编译期报错
-// ② ctx 注入声明：use(api()).use(router()) 后组件声明依赖，ctx 直接访问
-const Home: Component<{}, ApiInjected & RouteInjected> = (_init, ctx) => {
-  ctx.api.get('/users')   // ✓ 有类型
-  ctx.app.navigate('/x')  // ✓ 有类型
-  return () => <h1>Home</h1>
-}
-// 未声明的注入字段编译期报错——注入从"文档约定"变成"类型保证"
-createApp()
-  .use(api())                    // 注入 ctx.api
-  .use(router({ routes }))       // 注入 ctx.route / ctx.app
-  .mount('#root', Home)          // mount 时类型累积完整
-```
-> 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/client` 导入）。
-| 规则 | 说明 |
-|------|------|
-| 组件签名 | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
-| mount 阶段 | 外层函数只执行一次，初始化状态 |
-| render 阶段 | 内层函数每次 dirty/props 变化时执行，返回 VNode |
-| 无 class | 无 `this`，无实例方法 |
-| 无 hook | 无 `useState` / `useEffect` / `useMemo` |
-| 状态 | 闭包变量 + `ctx.ui.render()` 手动触发，或 `ctx.ui.$()` 响应式容器 |
-| ref 引用 | `ref={el => { if (el) init; else cleanup }}` 获取 DOM |
-### JSX 工厂
-```tsx
-// 由 esbuild 自动调用（jsxImportSource: 'weifuwu/client'）
-import { h, jsx, jsxs, jsxDEV, Fragment } from 'weifuwu/client'
-// h 支持 variadic children
-h('div', { class: 'x' }, child1, child2)
-// Fragment
-<><div>A</div><div>B</div></>
-```
-| 导出 | 用途 |
-|------|------|
-| `h(type, props, ...children)` | hyperscript |
-| `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
-| `Fragment` | 片段 |
-| `Portal` / `createPortal(children, portalKey?)` | 渲染到 `document.body#__wf_portal` 独立容器（弹层/对话框，脱离父级 overflow 裁剪） |
-```tsx
-import { createPortal } from 'weifuwu/client'
-// 内容渲染到 body 下的独立容器（不在父组件的 DOM 树内）
-const Tooltip = (_init, ctx) =>
-  (props) => createPortal(
-    <div class="tooltip">{props.text}</div>
-  )
-// 配合 ctx.ui.selfId('name') 可从任何地方精准刷新 portal 内容
-ctx.ui.render(['name'])
-```
----
-## 状态管理
-### ctx.ui 方法速查
-| 方法 | 签名 | 一句话说明 |
-|------|------|-----------|
-| `$()` | `$(): Record<string, any>` | 深度 Proxy 响应式状态容器，赋值自动触发渲染（**推荐首选**） |
-| `render()` | `render(ids?: string[])` | 同步强制渲染；无参 = 当前组件，传参 = 指定组件列表 |
-| `dirty()` | `dirty(ids?: string[])` | 异步渲染（微任务批处理合并）；`$` 内部就是调它 |
-| `selfId()` | `selfId(name: string)` | 注册组件自定义 ID，配合 `render(['id'])` 跨组件精准刷新 |
-| `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
-| `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
-| `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
-| `useInView()` | `useInView(opts)` | 可见性观察（IntersectionObserver 封装，替代组件自建 scroll 监听）；`isIn` 响应式 + `ready` |
-| `useScrollPosition()` | `useScrollPosition({ getScroller? })` | 滚动位置跟踪（全局 scroll 监听 + rAF 节流）；`y` 响应式，容器/视口通用 |
-> 每个方法的完整说明见下文对应章节。
-### Render 机制总览
-| API | 触发时机 | 渲染方式 | 作用域 | 使用场景 |
-|------|---------|---------|--------|---------|
-| `$.x = val` | 赋值后自动 | 微任务批量（异步） | 当前组件 | **日常 UI 状态** — 表单输入、切换开关、异步数据加载等 |
-| `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | 当前/指定 | **绕过 Proxy 后手动标记** |
-| `ctx.ui.render()` | 主动调用 | 立即同步 | 当前/指定 | **需要立即拿到最新 DOM** — DOM 测量、动画触发 |
-| `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
-| `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动 dirty |
-| `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动 dirty |
-| `ctx.ui.usePopupPosition()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **弹层坐标跟随** — scroll/resize 时自动重算 fixed 坐标 |
-| `ctx.ui.useInView()` | 注册监听 | IO 合成器线程评估 | 当前组件 | **可见性观察**（IO 封装，无 scroll-linked 警告）— Affix/BackTop/InView 统一使用；rootMargin/threshold 支持函数 |
-| `ctx.ui.useScrollPosition()` | 注册监听 | 全局 scroll + rAF 节流 | 当前组件 | **滚动位置跟踪** — `y` 响应式（视口/内部容器通用），Affix/VirtualList 使用 |
-`render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
-### 闭包变量 + `ctx.ui.render()`（简单场景）
-```tsx
-const Counter: Component = (_init, ctx) => {
-  let count = 0
-  return (props) =>
-    h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
-}
-```
-适合状态极少的简单组件。每次修改后手动调用 `ctx.ui.render()` 同步刷新 DOM。
-### `ctx.ui.$()` — 响应式 Proxy（推荐首选）
-`ctx.ui.$()` 返回**深度 Proxy** 容器。任意层级赋值操作自动触发渲染（微任务批量合并）：
-```tsx
-const FormPage: Component = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.email = ''
-  $.loading = false
-  return (props) =>
-    h('input', {
-      value: $.email,
-      onInput: (e: any) => { $.email = e.target.value }
-    })
-}
-```
-**深度 Proxy 拦截**：
-- `$.x = val` → 自动排队重渲染
-- `$.obj.a = 1` → 自动 dirty（嵌套对象递归包装）
-- `$.arr.push(val)` / `$.arr[0].x = y` → 自动 dirty（数组变异 + 嵌套属性拦截）
-- `delete $.x` → 自动 dirty
-- 每个组件实例独立 Proxy，同名变量不冲突
-**注意**：mount/render 中 `$.x = val` **不触发渲染**，仅事件/timer/Promise.then 中生效。这是有意设计——初始化和 mount 阶段设置状态不应触发额外渲染。
-**何时用 `$`**：所有需要触发 UI 重新渲染的状态。90% 以上的场景用 `$` 就够。
-**何时不用**：
-- 不需要触发渲染的内部缓存（用闭包变量 `let`）
-- 简单组件只有一两个状态变量（闭包变量 + `render()` 更轻量）
-### 响应式自适应组件
-#### `ctx.ui.useMedia(query, callback)` — 响应式媒体查询
-注册媒体查询监听，值变化时自动调用 callback（callback 内赋值 `$` 触发 dirty）：
-```tsx
-const Card = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.isMobile = false
-  // 立即回调一次（取当前值），之后变化时自动重新回调
-  ctx.ui.useMedia('(max-width: 640px)', (v) => { $.isMobile = v })
-  return (props) => (
-    <div class={$.isMobile ? 'wf-stack' : 'wf-row'}>
-      {!$.isMobile && <Sidebar />}
-      <Content />
-    </div>
-  )
-}
-```
-`callback` 在 mount 时立即执行一次，之后断点变化时再次执行。赋值给 `$` 的属性自动触发渲染。
-#### `ctx.ui.useBreakpoint(callback)` — 命名断点
-预设三个断点名称：`mobile`（<640px）、`tablet`（640-1023px）、`desktop`（≥1024px）：
-```tsx
-const Layout = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  ctx.ui.useBreakpoint((vp) => { $.vp = vp })
-  return (props) =>
-    <div class={`sidebar-${$.vp}`}>
-      {$.vp === 'mobile' ? <BottomNav /> : <SideNav />}
-      {$.vp === 'mobile' ? <MobileContent /> : <Content />}
-    </div>
-}
-```
-也支持自定义断点：
-```tsx
-ctx.ui.useBreakpoint(
-  { narrow: '(max-width: 480px)', wide: '(min-width: 1200px)' },
-  (vp) => { $.size = vp },
-)
-```
-#### `ctx.ui.usePopupPosition(options)` — 弹层坐标跟随
-解决弹出层（Popover / Tooltip / Dropdown / DatePicker 等）在 **页面滚动 / 窗口缩放后不跟随触发元素** 的问题。基于 `position: fixed` + `getBoundingClientRect()`（视口坐标）的弹层，滚动后坐标需要重算——本 API 用全局 scroll/resize 监听（rAF 节流）自动重算并精准刷新当前组件。
-```tsx
-const DatePicker = (_init, ctx) => {
-  let show = false
-  let inputEl: HTMLElement | null = null
-  let prevOpen = false
-  // mount 阶段注册：scroll/resize 时自动重算 pos
-  const pos = ctx.ui.usePopupPosition({
-    el: () => inputEl,                  // 锚定元素（ref 保存）
-    isOpen: () => show,                 // 弹层是否显示
-    compute: (r) => ({ top: r.bottom + 4, left: r.left }),  // rect → 坐标
-  })
-  return (props) => {
-    const isOpen = show
-    // 打开瞬间算一次初始坐标（受控/非受控统一覆盖）
-    if (isOpen && !prevOpen) pos.refresh()
-    prevOpen = isOpen
-    return h('div', {}, [
-      h('input', {
-        ref: (el) => { inputEl = el as HTMLElement },
-        onClick: () => { show = !show; ctx.ui.render() },
-      }),
-      isOpen ? h('div', { style: { top: pos.top, left: pos.left } }) : null,
-    ].filter(Boolean))
-  }
-}
-```
-要点：
-- `pos` 是稳定对象，render 闭包直接读取 `top/left/width`，滚动重算原地更新，无需重新绑定
-- `pos.refresh()` 只重算不渲染——配合打开路径上已有的 `render()`，避免重复渲染
-- 监听是**全局单例**（capture 捕获所有嵌套滚动容器 + rAF 节流），按组件 selfId 注册，组件多时开销 O(1)
-- `compute` 是纯函数（rect → 坐标），可单独单测
-已内置接入的组件：**Popover / Tooltip / Dropdown / DatePicker / Chart**（tooltip）——它们的弹出层在页面滚动、嵌套容器滚动、窗口缩放时都会自动跟随触发元素，无需额外配置。
-#### `ctx.ui.selfId(name)` — 跨组件精准刷新
-用于全局事件通知、Portal 远程控制、兄弟组件协调等场景——绕过多层 props 传递，直接按 ID 刷新目标组件：
-```tsx
-// 组件 A：mount 阶段注册自定义 ID
-const StatsPanel = (_init, ctx) => {
-  ctx.ui.selfId('stats')
-  const $ = ctx.ui.$()
-  $.data = []
-  return (props) => h('div', {}, String($.data.length))
-}
-// 组件 B（或其他任何地方）用 ID 精准刷新
-ctx.ui.render(['stats'])        // 同步刷新
-// 或：ctx.ui.dirty(['stats'])   // 异步批处理版本
-```
-**语义**：
-- 必须在 **mount 阶段**调用（组件初始化时），注册后组件即可被 `render(['id'])` / `dirty(['id'])` 精准定位
-- **同名冲突直接抛错**，每个自定义 ID 必须全局唯一
-- 配合 `selfId` 注册的组件在跨组件场景下无需把刷新逻辑层层传 props
-#### CSS 层响应式（不碰 JS）
-配合 `weifuwu/layout` 的断点变体，纯 CSS 实现布局方向切换：
-```html
-<!-- 小屏堆叠，桌面并排 -->
-<div class="wf-stack wf-stack@md"></div>
-<!-- 小屏隐藏侧栏 -->
-<aside class="wf-hidden wf-block@md"></aside>
-```
-可用断点变体：
-| 原语 | 变体 | 效果 |
-|------|------|------|
-| `wf-stack` | `@sm` `@md` `@lg` | 断点以上改为横向排列 |
-| `wf-row` | `@sm` `@md` `@lg` | 断点以上保持横向 |
-| `wf-hidden` | `@sm` `@md` `@lg` | 断点以上隐藏 |
-| `wf-block` | `@sm` `@md` `@lg` | 断点以上显示 |
-断点尺寸：`--wf-bp-sm: 640px` / `--wf-bp-md: 768px` / `--wf-bp-lg: 1024px` / `--wf-bp-xl: 1280px`
-### `ctx.ui.dirty()` — 异步标记脏
-异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
-与 `render()` 的区别：`dirty()` 是**异步**（微任务批量合并，同帧多次调用只渲染一次），`render()` 是**同步**（立即执行 VDOM diff + patch）。日常 UI 状态用 `$` 或 `dirty()`，需要立即拿到最新 DOM（测量/动画/第三方库）时用 `render()`。
-### `ctx.ui.render()` — 同步强制渲染
-与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。无参时只刷新当前组件，传参时可精准刷新指定组件。
-**何时必须用 `render()`**：
-```tsx
-// 1. DOM 测量（读取 offsetHeight/scrollWidth 等）
-// 用 ref 在 DOM 创建后操作
-ref: (el) => {
-  if (!el) return
-  el.style.height = 'auto'
-  ctx.ui.render()
-  const h = el.offsetHeight
-  el.style.height = h + 'px'
-}
-// 2. 动画触发（需要确保上一帧 DOM 已提交）
-function startAnimation() {
-  $.animating = true
-  ctx.ui.render()                // 同步刷新 DOM
-  el.startViewTransition(...)    // 拿到最新 DOM 启动动画
-}
-// 3. 第三方库需要在事件回调中读取最新 DOM
-onClick: () => {
-  $.selected = !$.selected
-  ctx.ui.render()                // 确保 DOM 已更新
-  thirdPartyLib.measure(el)      // 读取最新状态
-}
-```
-**规则**：能用 `$` 就用 `$`。只有当你**必须同步拿到最新 DOM 状态**时才用 `render()`。
-### 三种方式速查
-```tsx
-// 自动：$.x = val — 微任务批量，绑定当前组件
-const $ = ctx.ui.$()
-$.count++
-$.name = 'hello'         // 多次赋值合并为一次渲染
-// 手动：ctx.ui.render() — 同步，无参=当前，传参=指定
-let count = 0
-count++
-ctx.ui.render()          // DOM 立刻更新
-ctx.ui.render(['stats']) // 精准刷新指定组件
-// 异步：ctx.ui.dirty() — 微任务批量，同 render() 作用域
-ctx.ui.dirty()
-ctx.ui.dirty(['stats'])  // 批处理合并
-```
-**性能说明**：
-- `$.x = val` 和 `dirty()` 都是微任务批量合并
-- `render()` 从 dirty 组件**向下**遍历（scope render），兄弟组件不遍历
-- **三态 skip 自动优化**：组件重新渲染时，框架自动检查三个维度：
-  - **props**（含 children 元素级比较）——值没变则不渲染
-  - **`$` 状态**——没被 dirty 标记则不渲染
-  - **ctx 版本**——ctx 没变化则不渲染
-  三个条件全部满足时跳过整个子树（零 `_render` 调用、零 `patchValue` 遍历）
-- **lastIndex keyed diff**：列表 diff 采用正向 lastIndex 算法（React 同款），顺序不变时零 `insertBefore`。对比传统的逆序循环全量移动，DOM 修改从 O(N) 降到 O(0)。
-- 示例：DemoButton 点击一次，DOM 修改从 34 次降到 **1 次**（仅变更文本节点的 `textContent`）
-### 实践建议
-**组件库**（可分享组件）推荐手动模式：
-```tsx
-const DatePicker = (_init, ctx) => {
-  let show = false             // let 不触发渲染
-  return (props) =>
-    h('input', {
-      onClick: () => { show = true; ctx.ui.render() }
-    })
-}
-```
-行为只由 `render()` 显式控制，不依赖 `$`，测试中 `render()` 直接 mock 为空函数。
-**业务层**推荐自动模式：
-```tsx
-const OrderPage = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.orders = []                // $ 赋值自动触发渲染
-  $.loading = false
-  return (props) => h('div', {}, $.loading ? h(Spinner) : h(OrderList, { orders: $.orders }))
-}
-```
-省事、安全、`$` 绑定所属组件不波及兄弟。
-同一个组件内可以按变量混用两种模式：需要渲染的用 `$`，不需要的用 `let`。
-### VDOM diff 优化机制
-weifuwu 的 VDOM 在每次 render 时自动执行**三态 skip 判定**，减少不必要的组件渲染和 DOM 操作：
-```
-canSkip = (props 没变) AND ($ 没脏) AND (ctx 版本一致)
-          ↑ 值级浅比较    ↑ VNode dirty 标记  ↑ 全局版本号
-```
-三个维度各自独立判断，AND 合并。任何一个维度说
----
-## 条件与列表
-使用原生 JS 控制流：
-```tsx
-// 条件
-{cond ? <A /> : <B />}
-{cond && <A />}
-// 列表 — 必须指定 key
-{items.map(item => (
-  <div key={item.id}>{item.name}</div>
-))}
-```
----
-## ref 管理 DOM
-使用 `ref` prop 获取元素引用，适合管理第三方库或读取 DOM：
-```tsx
-const Timer: Component = (_init, ctx) => {
-  let timer: ReturnType<typeof setInterval> | undefined
-  return (props) =>
-    h('div', {
-      ref: (el) => {
-        if (el) {
-          timer = setInterval(() => console.log('tick'), 1000)
-        } else {
-          clearInterval(timer)
-        }
-      },
-    }, 'Timer')
-}
-```
-`ref` 在元素创建时调用 `ref(el)`，元素移除时调用 `ref(null)`。
-`ref` 不接受返回值，清理逻辑直接在 `else` 分支处理。
-对于**内嵌元素**（非根元素），直接在目标元素上放 `ref`：
-```tsx
-return h('div', {},
-  h('input', {
-    type: 'text',
-    ref: (el) => el?.focus(),
-  })
-)
-```
-### 异步组件
-在 mount 阶段发起请求，数据通过 `$.x = val` 自动触发渲染：
-```tsx
-const UserProfile: Component = (initProps, ctx) => {
-  const $ = ctx.ui.$()
-  $.loading = true
-  fetch(`/api/user/${initProps.id}`)
-    .then(r => r.json())
-    .then(user => { $.user = user; $.loading = false })
-  return (props) =>
-    $.loading
-      ? h('div', {}, '加载中...')
-      : h('div', {}, $.user?.name ?? '')
-}
-```
-### asyncComponent 工厂（async 组件）— 同步式数据声明
-`async (ctx) => (initProps, ctx) => (props) => VNode` — 工厂层（async，只执行一次并缓存）声明数据/加载代码，mount/render 保持同步。数据经闭包注入组件，渲染无 loading 分支：
-```tsx
-import { asyncComponent } from 'weifuwu/client'
-const UserProfile = asyncComponent(async (ctx) => {
-  const user = await ctx.data.get(`/api/user/${ctx.params.id}`)
-  return (_init, ctx) => {
-    const $ = ctx.ui.$()
-    $.liked = false                        // 客户端状态（交互后变化）
-    return (props) =>
-      h('div', {},
-        h('p', {}, user.name),             // 服务端状态（闭包，SSR 进 HTML）
-        h('button', { onClick: () => $.liked = !$.liked }, $.liked ? '❤️' : '🤍'),
-      )
-  }
-})
-```
-- **客户端**：首次渲染占位 → 工厂 resolve 后整树重渲染补全（SPA）；数据经 `ctx.data` 缓存（hydration 时从 `__DATA__` 同步命中，不重跑请求）
-- **服务端**：`ctx.ui.ssr()` 直接 await 工厂 → 数据进 HTML（无占位）
-- 工厂缓存绑定页面上下文：路由导航/登录登出时自动失效，工厂以新 ctx 重新执行
-- 会变的数据：初始值 seed 自服务端数据（`$.count = data.count`），交互改 `$`；初始状态必须确定性（禁止 `window.innerWidth` 直接初始化 → SSR/hydration mismatch）
----
-## router + RouteView — 前端路由
-```tsx
-import { createApp, router, RouteView } from 'weifuwu/client'
-import type { RouteDef, WfuiContext } from 'weifuwu/client'
-const routes: RouteDef[] = [
-  { path: '/', component: Home },
-  { path: '/users', component: UserList },
-  { path: '/users/:id', component: UserDetail },
-]
-createApp()
-  .use(router({
-    routes,
-    mode: 'history',  // 或 'hash'
-    notFound: NotFoundPage,
-  }))
-  .mount('#root', () => () => <RouteView />)  // 根组件也要两阶段：外层返回 render 函数
-```
-### 嵌套布局
-```tsx
-const routes = [
-  {
-    path: '/dashboard',
-    layout: DashboardLayout,      // 持久布局（包含 RouteView）
-    children: [
-      { path: '/overview', component: Overview },
-      { path: '/settings', component: Settings },
-    ],
-  },
-]
-function DashboardLayout(_props: {}, ctx: WfuiContext) {
-  return (props) => (
-    <div style="display:flex">
-      <aside>导航菜单</aside>
-      <main><RouteView /></main>  {/* 渲染子路由 */}
-    </div>
-  )
-}
-```
-### 编程式导航
-```tsx
-// 在任意组件中
-ctx.app?.navigate('/users/123?tab=profile')
-```
-| ctx 注入 | 类型 | 说明 |
-|----------|------|------|
-| `ctx.route.path` | `string` | 当前路由路径 |
-| `ctx.route.params` | `Record<string, string>` | URL 参数 |
-| `ctx.route.query` | `Record<string, string>` | 查询参数 |
-| `ctx.app.navigate(path)` | `(string) => void` | 编程式导航 |
-| RouterOptions | 类型 | 默认值 | 说明 |
-|---------------|------|--------|------|
-| `routes` | `RouteDef[]` | — | 路由定义 |
-| `mode` | `'history' \| 'hash'` | `'history'` | 路由模式 |
-| `notFound` | `Component` | — | 404 页面 |
-| RouteDef | 类型 | 说明 |
-|----------|------|------|
-| `path` | `string` | 路径（支持 `:param`） |
-| `component` | `Component` | 页面组件 |
-| `layout` | `Component` | 布局组件（内含 `<RouteView />`） |
-| `children` | `RouteDef[]` | 子路由 |
-| `auth` | `boolean` | 是否需要认证（配合 auth 中间件） |
-| `title` | `string` | 页面标题（自动设置 `document.title`） |
----
-## api — HTTP 客户端中间件
-```tsx
-import { createApp, api } from 'weifuwu/client'
-createApp()
-  .use(api({ baseURL: '/api' }))
-  .mount('#root', App)
-// 在组件中使用
-async function loadUsers(ctx: WfuiContext) {
-  const users = await ctx.api?.get<User[]>('/users')
-  const user = await ctx.api?.get<User>('/users/1')
-  const created = await ctx.api?.post<User>('/users', { name: 'Alice' })
-  await ctx.api?.put('/users/1', { name: 'Bob' })
-  await ctx.api?.patch('/users/1', { name: 'Bob' })
-  await ctx.api?.delete('/users/1')
-}
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `baseURL` | `string` | `''` | API 基础路径 |
-| `headers` | `Record<string, string>` | `{ 'Content-Type': 'application/json' }` | 默认请求头 |
-| `onRequest` | `(req) => { url, init }` | — | 请求拦截器 |
-| `onResponse` | `(res) => Promise<T>` | — | 响应拦截器 |
-| `timeout` | `number` | `0`（无超时） | 请求超时（ms）|
-| ctx.api 方法 | 签名 | 说明 |
-|-------------|------|------|
-| `api.get(url, opts?)` | `<T>(string, ApiRequestOptions?) => Promise<T>` | GET |
-| `api.post(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | POST |
-| `api.put(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | PUT |
-| `api.patch(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | PATCH |
-| `api.delete(url, opts?)` | `<T>(string, ApiRequestOptions?) => Promise<T>` | DELETE |
-```ts
-// 错误处理
-try {
-  await ctx.api!.get('/users')
-} catch (e) {
-  if (e instanceof ApiError) {
-    console.log(e.status, e.body)  // e.g. 404, 'Not Found'
-  }
-}
-```
-`ApiError`：`{ status: number, body: string }`，继承 `Error`。
-| ApiRequestOptions | 类型 | 说明 |
-|-------------------|------|------|
-| `headers` | `Record<string, string>` | 本次请求自定义请求头 |
-| `signal` | `AbortSignal` | 取消请求 |
----
-## auth — 认证中间件
-```tsx
-import { createApp, auth } from 'weifuwu/client'
-createApp()
-  .use(auth())
-  .mount('#root', App)
-// 在组件中
-function Profile(_props: {}, ctx: WfuiContext) {
-  return (props) => {
-    if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
-    return <p>欢迎, {ctx.auth?.user?.name}</p>
-  }
-}
-// 登录
-ctx.auth?.login(token, { id: 1, name: 'Alice' }, refreshToken)
-// 登出
-ctx.auth?.logout()
-// 更新用户信息
-ctx.auth?.setUser({ id: 1, name: 'Bob' })
-// 刷新 token
-await ctx.auth?.refresh()  // → boolean
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `storage` | `Storage` | `localStorage` | 存储方式 |
-| `tokenKey` | `string` | `'weifuwu_token'` | Token 存储 key |
-| `userKey` | `string` | `'weifuwu_user'` | 用户信息存储 key |
-| `refreshTokenKey` | `string` | `'weifuwu_refresh'` | Refresh token 存储 key |
-| `refreshEndpoint` | `string` | `'/api/auth/refresh'` | 刷新端点 |
-| ctx.auth | 类型 | 说明 |
-|----------|------|------|
-| `.token` | `string \| null` | JWT token |
-| `.user` | `any` | 用户对象 |
-| `.isLoggedIn` | `boolean` | 是否已登录（基于 token 存在） |
-| `.login(token, user, refreshToken?)` | `void` | 登录 |
-| `.logout()` | `void` | 登出（清除存储） |
-| `.setUser(user)` | `void` | 更新用户信息 |
-| `.refresh()` | `Promise<boolean>` | 刷新 token（自动检测过期） |
-启动时自动检测 token 是否过期（JWT `exp` 提前 30 秒），过期则自动调用 `refresh()`。
----
-## ws — WebSocket 客户端中间件
-```tsx
-import { createApp, ws } from 'weifuwu/client'
-createApp()
-  .use(ws({ url: '/ws' }))
-  .mount('#root', App)
-// 发送消息
-ctx.ws?.send({ type: 'chat', body: 'hello' })
-// 接收消息 — 返回 unsubscribe 函数
-const unsubscribe = ctx.ws?.onMessage((msg) => {
-  console.log('收到:', msg)
-})
-// 清理
-unsubscribe?.()
-```
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `url` | `string` | `'/ws'` | WebSocket 连接地址 |
-| `reconnectInterval` | `number` | `3000` | 重连间隔（ms） |
-| `maxReconnect` | `number` | `10` | 最大重连次数 |
-| `pingInterval` | `number` | `30000` | 心跳发送间隔 |
-| `pingTimeout` | `number` | `10000` | 心跳超时断开 |
-| ctx.ws | 类型 | 说明 |
-|--------|------|------|
-| `.send(msg)` | `(unknown) => void` | 发送 JSON 消息 |
-| `.onMessage(fn)` | `(fn) => () => void` | 订阅消息，返回 unsubscribe |
-| `.isConnected` | `boolean` | 连接状态 |
-| `.close()` | `() => void` | 断开连接 |
-自动重连（指数退避）、心跳保活、JSON 序列化/反序列化。
----
-## i18n — 国际化中间件
-```tsx
-import { createApp, i18n } from 'weifuwu/client'
-createApp()
-  .use(i18n({
-    locale: 'zh-CN',
-    messages: {
-      'title': '仪表盘',
-      'welcome': '欢迎光临',
-    },
-  }))
-  .mount('#root', App)
-// 组件中使用
-<h1>{ctx.i18n?.t('title')}</h1>
-<p>{ctx.i18n?.t('welcome')}</p>
-// 运行时切换语言
-ctx.i18n?.setLocale('en-US')
-// → 自动触发根组件重渲染（所有组件使用新语言文案）
-```
-| I18nOptions | 类型 | 默认值 | 说明 |
-|-------------|------|--------|------|
-| `locale` | `string` | `'zh-CN'` | 初始语言 |
-| `messages` | `Record<string, string>` | `{}` | 翻译键值对 |
-| `components` | `Record<string, Record<string, string>>` | `{}` | 组件文案覆盖 |
-| ctx.i18n | 类型 | 说明 |
-|----------|------|------|
-| `.t(key, fallback?)` | `(string, string?) => string` | 翻译 |
-| `.locale` | `string` | 当前语言 |
-| `.setLocale(lang)` | `(string) => void` | 切换语言（触发重渲染） |
-| `.components` | `Record<string, Record<string, string>>` | 组件文案映射 |
-内置语言包：
-```ts
-import { zhCN, enUS } from 'weifuwu/client'
-```
-- `zh-CN`：默认中文
-- `en-US`：英文
-组件文案（Button 的 `加载中...`、FileUpload 的 `点击或拖拽上传文件` 等）随语言自动切换。组件内部通过 `ctx.i18n?.components?.ComponentName.field` 读取。
-组件支持 `props.locale` 局部覆盖语言。
----
-## ErrorBoundary — 错误边界
-```tsx
-import { ErrorBoundary } from 'weifuwu/client'
-<ErrorBoundary fallback={<p>出错了，请刷新页面</p>}>
-  <UserProfile />
-</ErrorBoundary>
-// fallback 也可以是一个接收 error 的函数
-<ErrorBoundary fallback={({ error }) => (
-  <div>
-    <p>出错了: {String(error)}</p>
-    <button onClick={() => location.reload()}>重试</button>
-  </div>
-)}>
-  <UserProfile />
-</ErrorBoundary>
-```
-| ErrorBoundaryProps | 类型 | 默认值 | 说明 |
-|--------------------|------|--------|------|
-| `fallback` | `VNode \| ((props: { error }) => VNode) \| null` | `null` | 错误时渲染的内容 |
-| `children` | `any` | — | 子组件 |
-捕获子组件 render 时的错误 → 渲染 fallback。清除 `error` 即可重试。
----
-## confirm — 确认对话框
-两种用法，共享同一视觉与行为（基于 Modal 封装）：
-**① 命令式 `ctx.confirm()`（推荐，操作前询问）**
-```tsx
-import { createApp } from 'weifuwu/client'
-import { confirm } from 'weifuwu/components'
-createApp()
-  .use(confirm())
-  .mount('#root', App)
-// 任意代码中（组件事件、async 逻辑）
-async function handleDelete(ctx: WfuiContext) {
-  const ok = await ctx.confirm?.('确定删除这条记录？', {
-    title: '确认删除',
-    confirmText: '删除',
-    cancelText: '取消',
-    variant: 'danger',  // 'primary' | 'danger'
-  })
-  if (ok) {
-    // 执行删除...
-  }
-}
-```
-**② 声明式 `<Confirm>`（需要受控状态时）**
-```tsx
-import { Confirm } from 'weifuwu/components'
-<Confirm
-  open={confirming}
-  title="确认删除"
-  message="确定删除这条记录？"
-  confirmText="删除"
-  variant="danger"
-  onConfirm={() => doDelete()}
-  onCancel={() => setConfirming(false)}
-/>
-```
-| ConfirmOptions | 类型 | 默认值 | 说明 |
-|----------------|------|--------|------|
-| `title` | `string` | `'确认操作'` | 对话框标题 |
-| `confirmText` | `string` | `'确定'` | 确认按钮文字 |
-| `cancelText` | `string` | `'取消'` | 取消按钮文字 |
-| `variant` | `'primary' \| 'danger'` | `'primary'` | 按钮样式变体 |
-| `width` | `string` | Modal 默认 | 对话框宽度 |
-- `ctx.confirm()` 返回 `Promise<boolean>`，ESC / 点击遮罩 / 取消 → resolve(false)
-- 组件化渲染（Modal + portal），自动锁定滚动 + 焦点陷阱，i18n 文案可配置
-- 多次调用各自独立渲染（叠放语义），互不干扰
----
-## toast — 命令式消息提示
-`ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
-```tsx
-import { createApp } from 'weifuwu/client'
-import { toast } from 'weifuwu/components'
-createApp()
-  .use(toast({ position: 'top-right', duration: 3000, max: 3 }))
-  .mount('#root', App)
-// 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
-ctx.toast?.('保存成功', 'success')
-ctx.toast?.('请求失败', 'error')
-ctx.toast?.('普通消息')          // 默认 type = 'info'
-```
-| ToastOptions | 类型 | 默认值 | 说明 |
-|-------------|------|--------|------|
-| `position` | `ToastPosition` | `'top-right'` | 容器位置 |
-| `duration` | `number` | `3000` | 默认自动消失时间（ms），0 = 不消失 |
-| `max` | `number` | `3` | 最大显示条数，超出移除最早 |
-单条可覆盖自动消失时间：`ctx.toast('慢一点消失', 'info', 5000)`。
-与声明式 `<Toast toasts={...}/>` 共存：声明式用于局部列表（合并消息、自定义布局），命令式用于全局一次性反馈。
----
-## ScrollLock / FocusTrap
-```tsx
-import { lockScroll, unlockScroll } from 'weifuwu/client'
-import { trapFocus } from 'weifuwu/client'
-// 锁定/解锁滚动（支持嵌套计数）
-lockScroll()
-unlockScroll()
-// 焦点陷阱 — 返回 cleanup 函数
-const cleanup = trapFocus(containerElement)
-cleanup()  // 恢复之前的焦点
-```
-| API | 说明 |
-|-----|------|
-| `lockScroll()` | 锁定 body 滚动（iOS 兼容） |
-| `unlockScroll()` | 解锁滚动，恢复滚动位置 |
-| `trapFocus(el)` | Tab/Shift+Tab 在容器内循环，返回 cleanup |
----
-## extendCtx — 上下文扩展
-```tsx
-import { extendCtx } from 'weifuwu/client'
-// 在 AppMiddleware 中创建新 ctx，原 ctx getter 通过原型链继承
-function myMw(ctx: WfuiContext): WfuiContext {
-  return extendCtx(ctx, { myField: 'value' })
-}
-```
-`extendCtx` 使用 `Object.create(ctx)` 保持原型链，再用 `Object.assign` 添加新字段。保证 getter 不被快照化。
----
-## 前端类型
-```tsx
-import type { VNode, VNodeType, Component, WfuiContext, AppMiddleware, RouteDef } from 'weifuwu/client'
-import type { ApiClient, ApiOptions, ApiRequestOptions, ApiError } from 'weifuwu/client'
-import type { AuthClient, AuthOptions } from 'weifuwu/client'
-import type { ErrorBoundaryProps } from 'weifuwu/client'
-import type { I18nOptions, I18nState, LocalePackage } from 'weifuwu/client'
-import type { PopupPositionOptions, PopupPosition } from 'weifuwu/client'
-import type { ConfirmProps, ConfirmOptions } from 'weifuwu/components'
-import type { ToastOptions, ToastPosition } from 'weifuwu/components'
-import type { RouterOptions } from 'weifuwu/client'
-```
-| 类型 | 说明 |
-|------|------|
-| `VNode` | `{ type, props, key? }` |
-| `VNodeType` | `string \| Component \| typeof Fragment` |
-| `Component<P>` | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
-| `WfuiContext` | `{ ui, route?, app?, ws?, api?, auth?, i18n?, confirm?, toast?, [key]: unknown }` |
-| `AppMiddleware` | `(ctx: WfuiContext) => WfuiContext` |
-| `RouteDef` | `{ path, component?, layout?, children?, auth?, title? }` |
-| `ApiClient` | `{ get, post, put, patch, delete }` |
-| `ApiError` | `class { status, body } extends Error` |
-| `AuthClient` | `{ token, user, isLoggedIn, login, logout, setUser, refresh }` |
-| `I18nOptions` | `{ locale?, messages?, components? }` |
-| `I18nState` | `{ locale, t, setLocale, components }` |
-| `ErrorBoundaryProps` | `{ fallback?, children? }` |
-| `ConfirmProps` | `{ open?, title?, message?, confirmText?, cancelText?, variant?, width?, onConfirm?, onCancel? }` |
-| `ConfirmOptions` | `{ title?, confirmText?, cancelText?, variant?, width? }` — 命令式 ctx.confirm 选项 |
-| `ToastOptions` | `{ position?, duration?, max? }` — 命令式 ctx.toast 配置 |
-| `PopupPositionOptions` | `{ el, isOpen, compute }` — 弹层位置跟踪配置（见 usePopupPosition） |
-| `PopupPosition` | `{ top, left, width?, refresh }` — 弹层位置跟踪器 |
----
-# 组件库 (`weifuwu/components`)
-92 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
-> **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`docs/components-map.md`](./docs/components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
-```ts
-import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
-import 'weifuwu/components/style.css'   // 包含 Token + 67 布局原语 + 组件样式，一次性引入
-```
-### 使用示例
-```tsx
-// ├─ 按钮
-<Button variant="primary" onClick={() => alert('提交')}>提交</Button>
-<Button variant="ghost" loading>加载中</Button>
-<Button variant="danger" size="lg" block>删除</Button>
-// ├─ 输入框
-<Input placeholder="请输入邮箱" />
-<Input label="用户名" name="username" required error="必填" />
-<Input type="password" hint="至少6位" />
-<Input name="email" type="email" disabled placeholder="name@example.com" />
-// ├─ 选择器
-<Select options={[{ value: 'a', label: '选项A' }]} placeholder="请选择" />
-<Select searchable options={options} onChange={v => setVal(v)} />
-// ├─ 复选框 / 开关 / 单选
-<Checkbox checked={agree} onChange={setAgree} label="同意协议" />
-<Switch checked={enabled} onChange={setEnabled} />
-<RadioGroup options={[{ value: '1', label: '男' }, { value: '2', label: '女' }]} value={gender} />
-// ├─ 表格
-<Table columns={[{ key: 'id', label: 'ID', sortable: true }, { key: 'name', label: '名称' }]}
-       data={rows} sortKey="id" sortOrder="asc" onSort={(k, o) => setSort(k, o)} />
-// ├─ 模态框 / 确认框 / 抽屉
-<Modal open={show} title="提示" onClose={() => setShow(false)} width="500px" closable>
-  <p>确认删除？</p>
-</Modal>
-<Confirm open={confirming} message="确定删除？" variant="danger" onConfirm={doDelete} onCancel={() => setConfirming(false)} />
-// 命令式：await ctx.confirm?.('确定删除？') —— 组件里直接调用
-<Drawer open={open} title="详情" onClose={() => setOpen(false)} position="right">内容</Drawer>
-// ├─ 消息提示
-<Toast toasts={items} position="top-right" max={5} onRemove={id => remove(id)} />
-<Alert variant="warning" closable>注意：磁盘空间不足</Alert>
-// ├─ 标签 / 徽标 / 头像
-<Badge variant="primary">消息</Badge>
-<Badge variant="success" dot>通过</Badge>
-<Tag variant="primary" closable onClose={() => {}}>标签</Tag>
-<Avatar name="张三" size="lg" />
-// ├─ 卡片 / 统计卡片
-<Card variant="outlined" padding="md">卡片内容</Card>
-<StatCard label="总用户" value="1,234" trend="up" trendLabel="12%" />
-// ├─ 标签页 / 下拉菜单
-<Tabs items={[{ key: 'a', label: '标签A' }, { key: 'b', label: '标签B' }]} active="a" onChange={setTab} />
-<Dropdown items={[{ label: '编辑', onClick: () => {} }, { label: '删除', variant: 'danger' }]}>操作</Dropdown>
-// ├─ 分页 / 步骤条
-<Pagination total={100} page={1} pageSize={10} onChange={setPage} />
-<Steps items={[{ key: 's1', label: '第一步' }, { key: 's2', label: '第二步' }]} current={1} />
-// ├─ 滑块 / 进度条
-<Slider min={0} max={100} value={50} onChange={setValue} />
-<ProgressBar value={75} label="75%" />
-// ├─ 面包屑 / 分割线
-<Breadcrumb items={[{ label: '首页' }, { label: '用户管理' }]} />
-<Divider />
-<Divider>分割文字</Divider>
-// ├─ 加载 / 空状态 / 骨架屏
-<Loading text="加载中..." />
-<EmptyState text="暂无数据" hint="请先创建一条记录"><Button>新建</Button></EmptyState>
-<Skeleton variant="text" lines={3} />
-<Skeleton variant="table" lines={5} cols={4} />
-<Skeleton variant="avatar" />
-<Skeleton variant="image" />
-// ├─ 表单验证
-<Form validation={{ email: [{ required: true, message: '请输入邮箱' }] }}
-      onSubmit={values => ctx.api?.post('/login', values)}   // ctx.api 由中间件注入
-      onError={errors => setErrors(errors)}>
-  <Field label="邮箱" error={errors.email}>
-    <Input name="email" />
-  </Field>
-  <Button type="submit">登录</Button>
-</Form>
-// ├─ 新增批次组件（全量实现）
-<Rate value={3} onChange={setRate} />                                        // 评分
-<ToggleGroup type="single" options={toolbar} value={fmt} />                  // 工具栏切换
-<CheckboxGroup options={members} value={selected} onChange={setSelected} />   // 多选列表
-<PinInput length={6} value={code} onChange={setCode} />                       // 验证码
-<CopyButton value="https://weifuwu.dev" label="复制" />                     // 复制
-<ColorPicker value={color} showInput onChange={setColor} />                   // 颜色
-<Notification /> + notification.success({ title, description })               // 队列通知
-<Collapse items={docs} active={open} />                                       // 行内折叠
-<Tree data={orgTree} checkable checkedKeys={keys} />                          // 树形（父子联动）
-<Cascader options={regions} value={['zj','hz']} />                            // 级联选择
-<Transfer data={members} targetKeys={selected} />                             // 穿梭框
-<Command items={commands} open={open} onOpenChange={setOpen} />               // ⌘K 命令面板
-<Carousel autoplay>{slides}</Carousel>                                        // 轮播
-<Resizable defaultSize={180}>…</Resizable>                                    // 拖拽分割
-<Calendar month={5} year={2025} events={events} />                            // 月历
-<Watermark text="内部资料">…</Watermark>                                      // 水印
-<VirtualList height={400} itemHeight={36} items={rows} renderItem={render} /> // 虚拟列表
-<QRCode value="https://weifuwu.dev" size={128} />                            // 二维码（自研编码）
-<Img src="photo.png" preview />                                              // 图片点击放大
-<BackTop /> <Affix offsetTop={64}>…</Affix>                                   // 回顶 / 固定
-<HoverCard content={<UserCard />}>…</HoverCard>                               // 悬停富内容
-<Mentions options={users} value={text} />                                     // @提及
-<ContextMenu items={actions}>…</ContextMenu>                                  // 右键菜单
-<Menubar menus={menus} />                                                     // 水平菜单
-<InfiniteScroll hasMore onLoadMore>…</InfiniteScroll>                        // 无限滚动
-```
-> 所有组件引用 `--wf-*` CSS 变量做主题，详见下文的「样式定制指南」。
-### 生命周期映射
-组件没有生命周期函数。每个阶段对应到代码的明确位置：
-```
-mount ──────────────────────────────────────────
-  const Counter = (_init, ctx) => {       ← mount（只一次）
-    let count = 0                           ← 初始化状态
-    return (props) => {                     ← render 函数
-      // ...                                 ← 每次 dirty/props 变化执行
-    }
-  }
-ref ────────────────────────────────────────────
-  h('div', {
-    ref: (el) => {
-      if (el) { /* 元素已创建 */ }           ← 相当于 onmounted
-      else     { /* 元素已移除 */ }           ← 相当于 onunmount
-    }
-  })
-props 变化 ─────────────────────────────────────
-  return (props) => {
-    // 每次 render 都收到最新 props           ← 相当于 onupdate
-    if (props.value !== prevValue) { ... }
-  }
-```
-| 旧概念 | 新写法 |
-|--------|--------|
-| `onmount` | mount 外层函数直接写 |
-| `onmounted` | `ref` 的 `if (el)` 分支 |
-| `onunmount` | `ref` 的 `else` 分支 |
-| `onupdate` | render 内层函数收新 props 自行比较 |
-| `全局刷新` | `ctx.ui.render(['_wf_root'])` |
-| `局部刷新` | `ctx.ui.render()` 或 `$.x = val` |
-| `跨组件刷新` | `ctx.ui.selfId('name')` + `render(['name'])` |
-## 组件列表
-### 表单核心
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Button | `Button` | `variant`, `size`, `loading`, `disabled`, `block`, `type` | 按钮 |
-| Input | `Input` | `label`, `name`, `type`, `value`, `placeholder`, `required`, `disabled`, `error`, `hint`, `onInput`, `onChange` | 输入框 |
-| Textarea | `Textarea` | `rows`, `maxLength`, `showCount`, `error` | 文本域 |
-| Select | `Select` | `options: SelectOption[]`, `placeholder`, `searchable` | 下拉选择 |
-### 表单选择
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Checkbox | `Checkbox` | `checked`, `label`, `onChange` | 复选框 |
-| Switch | `Switch` | `checked`, `label`, `onChange` | 开关 |
-| RadioGroup | `RadioGroup` | `options: RadioOption[]`, `value`, `name` | 单选组 |
-| Slider | `Slider` | `min`, `max`, `step`, `value`, `onChange` | 滑块 |
-### 表单增强
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Form | `Form` | `onSubmit`, `validation` | 表单容器 |
-| Field | `Field` | `label`, `error`, `required`, `hint` | 字段包装 |
-| FileUpload | `FileUpload` | `accept`, `multiple`, `maxSize`, `onChange` | 文件上传 |
-| SearchInput | `SearchInput` | `value`, `placeholder`, `onInput`, `onClear` | 搜索框 |
-| SegmentedControl | `SegmentedControl` | `options: SegmentedOption[]`, `value`, `onChange`, `size` | 分段选择器 |
-| ProgressBar | `ProgressBar` | `value`, `max`, `label`, `showValue` | 进度条 |
-| InputNumber | `InputNumber` | `value`, `min`, `max`, `step`, `precision`, `onChange` | 数字输入（增减按钮） |
-| PasswordInput | `PasswordInput` | `value`, `onInput`, `autoComplete` | 密码输入（可见性切换） |
-| TagsInput | `TagsInput` | `value: string[]`, `maxTags`, `allowDuplicates` | 标签输入（中文输入法感知） |
-### 数据展示
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Table | `Table` | `columns: TableColumn[]`, `data`, `loading`, `sortKey`, `sortOrder`, `onSort`, `onRowClick` | 表格 |
-| Card | `Card` | `variant`, `outlined`, `padding`, `clickable`, `hover`, `active`, `onClick` | 卡片 |
-| Badge | `Badge` | `variant: BadgeVariant`, `dot` | 徽标 |
-| Tag | `Tag` | `variant: 'default'\|'primary'\|'success'\|'danger'`, `closable`, `onClose` | 标签 |
-| Avatar | `Avatar` | `src`, `name`, `size`, `color` | 头像 |
-| AvatarGroup | `AvatarGroup` | `items`, `max`, `size` | 头像组（堆叠 + 溢出 +N） |
-| Timeline | `Timeline` | `items: TimelineItem[]`, `mode`, `reverse` | 时间线（执行日志/历史） |
-| Descriptions | `Descriptions` | `items: DescriptionItem[]`, `column`, `bordered` | 描述列表（详情页字段） |
-| Markdown | `Markdown` | `content` | AI 回复渲染（安全子集 parser） |
-| CodeBlock | `CodeBlock` | `code`, `lang`, `title` | 代码块（语言标签 + 复制） |
-| Highlight | `Highlight` | `text`, `query: string \| string[]` | 搜索词高亮（mark） |
-| List | `List` | `items`, `renderItem`, `divided`, `header/footer/empty` | 通用列表 |
-| Result | `Result` | `status`, `title`, `desc`, `extra` | 结果页（成功/失败/警告/信息） |
-| Icon | `Icon` | `name: IconName`, `size` | 图标（内置 25 个 stroke 图标，currentColor 随字号） |
-| StatCard | `StatCard` | `label`, `value`, `trend: 'up'\|'down'`, `trendLabel`, `icon`, `animate` | 统计卡片 |
-| PageHeader | `PageHeader` | `title`, `sub`, `display` | 页面标题（actions 放 children） |
-| Img | `Img` | `src`, `alt`, `fallback`, `loading`, `width`, `height` | 图片（含 fallback） |
-| InView | `InView` | `once`, `threshold`, `rootMargin`, `placeholder`, `onEnter` | 进入视窗后懒加载内容 |
-### 数据反馈
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Modal | `Modal` | `open`, `title`, `onClose`, `width`, `footer`, `closable` | 模态框 |
-| Confirm | `Confirm` | `open`, `message`, `confirmText`, `cancelText`, `variant`, `onConfirm`, `onCancel` | 确认对话框（同 `ctx.confirm()` 命令式） |
-| Drawer | `Drawer` | `open`, `title`, `position: DrawerPosition`, `onClose`, `footer` | 抽屉 |
-| Tooltip | `Tooltip` | `content`, `position: TooltipPosition`, `disabled` | 工具提示（hover/focus 触发） |
-| Popover | `Popover` | `content`, `position: PopoverPosition`, `trigger`, `open`, `onOpenChange`, `disabled` | 弹出层 |
-| Toast | `Toast` | `toasts: ToastItem[]`, `position`, `max`, `onRemove` | 消息提示 |
-| Alert | `Alert` | `variant: AlertVariant`, `closable`, `onClose` | 警告提示（内容放 children） |
-| Loading | `Loading` | `text` | 加载中 |
-| EmptyState | `EmptyState` | `icon`, `text`, `hint` | 空状态（操作放 children） |
-| Skeleton | `Skeleton` | `variant: SkeletonVariant`, `lines`, `cols`, `width`, `height` | 骨架屏 |
-### 导航组件
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Breadcrumb | `Breadcrumb` | `items: BreadcrumbItem[]` | 面包屑 |
-| Menu | `Menu` | `items: MenuItem[]`, `activeKey`, `onSelect` | 侧栏导航（分组 + 图标 + 方向键） |
-| Tabs | `Tabs` | `items: TabItem[]`, `active`, `onChange` | 标签页 |
-| Dropdown | `Dropdown` | `trigger`, `items: DropdownItem[]`, `open`, `onOpenChange` | 下拉菜单 |
-| Pagination | `Pagination` | `total`, `page`, `pageSize`, `onChange` | 分页 |
-| Steps | `Steps` | `items: StepItem[]`（`{ key, label }`）, `current`, `active` | 步骤条 |
-| Accordion | `Accordion` | `items: AccordionItem[]`, `multiple` | 手风琴 |
-### 新增批次（全量 92 组件）
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Rate | `Rate` | `value`, `count`, `onChange`, `allowClear`, `readOnly`, `size` | 评分（键盘方向键/Home/End） |
-| Typography | `Title` `Text` `Paragraph` | `Title: level 1-5`；`Text: type/strong/underline/strike/mark/code`；`Paragraph: ellipsis` | 语义排版（Title/Text/Paragraph 三组件） |
-| Label | `Label` | `htmlFor`, `required` | 独立标签（必填星号） |
-| AspectRatio | `AspectRatio` | `ratio` | 宽高比容器（内容填满） |
-| Toggle | `Toggle` | `pressed`, `onPressedChange`, `variant`, `size` | 切换按钮（shadcn 对齐） |
-| ToggleGroup | `ToggleGroup` | `type: 'single'\|'multiple'`, `options`, `value`, `onChange` | 切换组 |
-| CheckboxGroup | `CheckboxGroup` | `options`, `value: string[]`, `onChange`, `cols` | 复选框组（栅格列数） |
-| PinInput | `PinInput` | `length`, `value`, `onChange`, `type` | 验证码输入（自动聚焦/粘贴分派/回退） |
-| CopyButton | `CopyButton` | `value`, `label`, `onCopy` | 复制按钮（clipboard + execCommand 降级） |
-| ColorPicker | `ColorPicker` | `value`, `onChange`, `showInput`, `preset` | 颜色选择（预设色板 + hex 输入） |
-| HoverCard | `HoverCard` | `content`, `position`, `openDelay`, `closeDelay` | 悬停富内容卡（shadcn） |
-| Notification | `Notification` | 命令式 `notification.success/error/warning/open` | 队列式通知（antd 对齐） |
-| BackTop | `BackTop` | `visibilityHeight`, `target`, `smooth` | 回到顶部（滚动超阈值显示） |
-| Affix | `Affix` | `offsetTop`, `target` | 固定定位（滚动超阈值钉住） |
-| ContextMenu | `ContextMenu` | `items: ContextMenuItem[]`（`{ label, onClick, variant: 'danger' }`） | 右键菜单（光标定位 + 方向键） |
-| Mentions | `Mentions` | `options: { value, label }[]`, `value`, `onChange`, `prefix` | @提及（composition 抑制） |
-| Collapse | `Collapse` | `items: CollapseItem[]`（`{ key, title, content, loading }`）, `active`, `multiple` | 行内折叠（异步 loading） |
-| Tree | `Tree` | `data: TreeNode[]`, `expandedKeys`, `checkedKeys`, `checkable`, `selectedKeys`, `onCheck/onExpand/onSelect` | 树（递归 + 勾选父子联动 + 半选传播） |
-| Cascader | `Cascader` | `options: CascaderOption[]`, `value: string[]`, `onChange` | 级联选择（多列推进） |
-| Transfer | `Transfer` | `data: { key, label }[]`, `targetKeys`, `onChange`, `titles` | 穿梭框（选中 + 批量移动） |
-| Command | `Command` | `items: CommandItem[]`, `open`, `onOpenChange`, `shortcut` | 命令面板（⌘K 全局 + 键盘流） |
-| Menubar | `Menubar` | `menus: { key, label, items }[]` | 水平菜单栏（←→ 切换 + ↓ 展开） |
-| Carousel | `Carousel` | `children`, `autoplay`, `interval`, `loop`, `showArrows/Dots` | 轮播（箭头/圆点/循环/自动播放） |
-| Resizable | `Resizable` | `direction`, `defaultSize`, `min/maxSize` | 拖拽分割面板（pointer + 键盘方向键） |
-| Calendar | `Calendar` | `month`, `year`, `events`, `selectedDate`, `onMonthChange/onSelectDate` | 月历（事件点 + 月切换 + 选日） |
-| Watermark | `Watermark` | `text`, `fontSize`, `rotate`, `zIndex` | 水印（canvas 平铺） |
-| VirtualList | `VirtualList` | `items`, `height`, `itemHeight`, `renderItem`, `overscan` | 虚拟列表（spacer + 可见窗口，1000+ 条） |
-| InfiniteScroll | `InfiniteScroll` | `hasMore`, `loadMore`, `children`, `loader` | 触底加载（IntersectionObserver） |
-| QRCode | `QRCode` | `value`, `ecLevel`, `size`, `color`, `bgColor` | 二维码（自研 Reed-Solomon，版本 1-6） |
-### 图表
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Chart | `Chart` | `type: ChartType`, `data`, `options`, `title`, `area` | SVG 图表（line/bar/pie）|
-| DatePicker | `DatePicker` | `mode: DatePickerMode`, `value`, `onChange`, `placeholder`, `disabled` | 日期选择器（date/datetime/time/range）|
-| Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled` | 富文本编辑器，零依赖 |
-### 布局
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| Divider | `Divider` | `vertical` | 分割线（水平带文字放 children，`vertical` 垂直） |
-### AI 交互原语（wf: 协议配套）
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| AiChat | `AiChat` | `chat`, `maxHeight?`, `labels?`, `renderMessage?`, `renderToolArgs?` | 标准 AI 对话界面：气泡 + 工具卡 + 审批卡 + 自动滚动 + 错误重试（接收 `ctx.ui.useChat()` handle） |
-| MessageBubble | `MessageBubble` | `content`, `role`, `status`, `actions` | 独立消息气泡（业务聊天页复用） |
-| ToolCallCard | `ToolCallCard` | `call`, `progress?`, `result?`, `renderArgs?` | 工具调用卡片：running（进度条）/ ok / error 三态（协议 §4） |
-| ApprovalCard | `ApprovalCard` | `request`, `status?`, `onApprove`, `onReject` | 人工审批卡片：待批（允许/拒绝+备注）/ 已批 / 已拒 / 超时（协议 §4.5） |
-### 全局工具
-| 组件 | 导入名 | 关键 Props | 说明 |
-|-----|--------|-----------|------|
-| ThemeSwitch | `ThemeSwitch` | `mode: 'auto'\|'light'\|'dark'`, `onChange`, `storageKey` | 主题切换（auto/light/dark，localStorage 持久化）；另有 `applyTheme()` / `getTheme()` 命令式工具 |
----
-# 布局系统 (`weifuwu/layout`)
-纯 CSS 布局原语 + 工具类 + 141 个主题 Token。不绑定任何 JS 框架。
-> **学习路径与命名规范**：见 [`docs/style-guide.md`](./docs/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
-> **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
-> 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
-```html
-<link rel="stylesheet" href="/node_modules/weifuwu/layout">
-```
-或在 weifuwu 服务端通过 `ctx.ui.css` 直接引用包名（`ctx.ui.css` 自动解析 exports map）：
-```ts
-// 方案 A：组件 + 布局全部搞定（推荐）
-app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
-// 方案 B：只用布局
-app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
-```
-也支持相对路径：`ctx.ui.css('./src/style.css')`。
-## 67 个布局原语
-| 类别 | 原语 | 效果 |
-|------|------|------|
-| **排列** | `wf-stack` `wf-stack@sm/md/lg` | 纵向 flex + gap（断点变体→横向） |
-| | `wf-stack-reverse` `@sm/md/lg` | 纵向反向 |
-| | `wf-row` `wf-row@sm/md/lg` | 横向 flex + wrap + gap |
-| | `wf-row-reverse` `@sm/md/lg` | 横向反向 |
-| | `wf-nowrap` | flex-wrap: nowrap |
-| | `wf-cluster` | 换行居中簇 |
-| **分布** | `wf-split` | justify-content: space-between |
-| | `wf-center` | 双轴居中 |
-| | `wf-right` | justify-content: flex-end |
-| | `wf-around` | space-around |
-| | `wf-evenly` | space-evenly |
-| **对齐** | `wf-top` | align-items: flex-start |
-| | `wf-bottom` | align-items: flex-end |
-| | `wf-stretch` | align-items: stretch |
-| **弹性** | `wf-fill` | flex: 1 + min-width: 0 |
-| | `wf-fixed` | flex: none |
-| | `wf-auto` | flex: auto |
-| | `wf-shrink` | min-width/height: 0 |
-| **Z轴** | `wf-cover` | position: fixed + inset: 0 |
-| | `wf-pop` | position: absolute |
-| | `wf-anchor` | position: relative |
-| | `wf-layer` | position: relative + z-index |
-| | `wf-sticky` | position: sticky |
-| **容器** | `wf-surface` | 基础面（border-radius + shadow + bg） |
-| | `wf-grid` | display: grid + --wf-cols |
-| | `wf-container` | max-width + margin: auto |
-| | `wf-scroll` | overflow: auto |
-| | `wf-clip` | overflow: hidden |
-| **显隐** | `wf-hidden` `wf-hidden@sm/md/lg` | display: none |
-| | `wf-block` `wf-block@sm/md/lg` | display: block |
-| | `wf-inline` | display: inline |
-| | `wf-inline-block` | display: inline-block |
-| | `wf-contents` | display: contents |
-| **间距** | `wf-p-*` / `wf-px-*` / `wf-py-*`（xs~2xl） | padding：全/水平/垂直，引用 `--wf-space-*` |
-| | `wf-mt-*` / `wf-mb-*` / `wf-my-*`（xs~2xl） | margin：top/bottom/垂直 |
-| | `wf-mx-auto` / `wf-my-auto` | margin: auto 居中 |
-| | `wf-gap-*`（xs~2xl） | 为 flex/grid 原语设置 `--wf-gap` |
-| **尺寸** | `wf-w-full` / `wf-h-full` / `wf-w-auto` | 宽/高 100%、auto |
-| **边框** | `wf-border` / `wf-border-t/b/l/r` | 1px 边框（`--wf-border-width` + `--wf-color-border`） |
-| **面工具** | `wf-bg-secondary/tertiary/brand/success/warning/error/info` | 语义背景色（`--wf-color-*-bg`） |
-| | `wf-pill` | 胶囊圆角（999px，状态徽章/标签/色块） |
-| | `wf-rounded-sm` `wf-rounded` `wf-rounded-md` `wf-rounded-lg` | 圆角工具（`--wf-radius-*`） |
-| **气泡** | `wf-bubble` / `wf-bubble--own` / `wf-bubble--ai` | 聊天气泡（pre-wrap + 折行内建） |
-| **打印** | `wf-print-hidden` / `wf-print-block` | 导出 PDF 时隐藏工具区 / 恢复块级 |
-| **行高** | `wf-leading-tight` `wf-leading-base` `wf-leading-relaxed` | line-height（`--wf-line-height-*`） |
-| **指针** | `wf-pointer` / `wf-not-allowed` | cursor: pointer / not-allowed |
-| **内容排版** | `wf-prose` | 富文本正文（文章/博客/文档，一个类包 h2/p/ul/blockquote/pre…） |
-| **外壳** | `wf-app-shell` | 应用外壳：侧边栏 + 主区 grid（`--wf-sidebar-width`） |
-| | `wf-sidebar` `wf-sidebar-header` `wf-sidebar-body` `wf-sidebar-footer` | 侧边栏：品牌区/导航区/底部用户区，sticky 全高 |
-| | `wf-nav` `wf-nav-group` `wf-nav-item` `wf-nav-icon` | 导航：分组标题 + 链接项（`--active` 激活态） |
-| | `wf-main` | 主内容区（padding + min-width: 0） |
-| | `wf-text-*` 排版工具 | 见下文「排版工具」 |
-### 排版工具（`wf-text-*`）
-| 工具 | 效果 |
-|------|------|
-| `wf-text-left/center/right` | text-align |
-| `wf-text-xs…5xl` | 字号（`--wf-font-size-*`） |
-| `wf-text-secondary/tertiary/disabled/brand` | 中性色阶 |
-| `wf-text-success/warning/error/info` | 语义色文本（`--wf-color-*`） |
-| `wf-text-medium/semibold/bold` | 字重 |
-| `wf-tracking-normal/wide/wider` | letter-spacing |
-| `wf-uppercase/lowercase/capitalize` | text-transform |
-| `wf-pre-wrap` | white-space: pre-wrap + word-break（聊天气泡/代码） |
-| `wf-break-word` | overflow-wrap + word-break |
-| `wf-text-nowrap` | white-space: nowrap |
-| `wf-truncate` | 单行省略（ellipsis） |
-| `wf-line-clamp-2/3` | 多行截断 |
-## 141 个主题 Token
-**双层结构**：原始层（Primitive，色值只定义一次，品牌/暗色调校改这里）+ 语义层（Semantic，组件消费）。
-```css
-/* ── 原始层 — 品牌/中性色值 + 暗色值，主题定制改这一层 ── */
---wf-brand-500 / --wf-brand-600 / --wf-brand-50   /* 品牌主色/悬停/浅底 */
---wf-slate-900…50 / --wf-white                     /* 中性阶 */
---wf-dark-*                                        /* 暗色值（暗色模式经间接层引用，零硬编码） */
-/* ── 语义层 — 组件消费，暗色/主题切换覆盖这里 ── */
-/* 品牌色 */
---wf-color-primary / --wf-color-primary-hover / --wf-color-primary-bg
-/* 语义色 */
---wf-color-success / --wf-color-success-bg
---wf-color-warning / --wf-color-warning-bg
---wf-color-error / --wf-color-error-bg
---wf-color-info / --wf-color-info-bg
-/* 语义文字色（P2）：浅底可读 700 级，文字用 -text、填充用 500 级 */
---wf-color-primary-text / --wf-color-success-text / --wf-color-warning-text / --wf-color-error-text / --wf-color-info-text
---wf-color-on-brand   /* 实心品牌/语义底上的文字与图标 */
---wf-overlay          /* 浮层遮罩（Modal/Drawer），暗色自动加深 */
-/* 文字色 */
---wf-color-text / --wf-color-text-secondary / --wf-color-text-tertiary / --wf-color-text-disabled
-/* 背景色 */
---wf-color-bg / --wf-color-bg-secondary / --wf-color-bg-tertiary
-/* 边框色 */
---wf-color-border / --wf-color-border-light / --wf-color-border-dark
-/* 字体 */
---wf-font-sans / --wf-font-mono
-/* 字号: xs sm base lg xl 2xl 3xl 4xl 5xl display */
---wf-font-size-*
-/* 字重: normal medium semibold bold */
---wf-font-weight-*
-/* 行高: tight normal relaxed */
---wf-line-height-*
-/* 字距: normal wide wider */
---wf-letter-spacing-*
-/* 间距: xs sm md lg xl 2xl */
---wf-space-*
-/* 间隔: xs sm md lg xl 2xl */
---wf-gap-*
-/* 圆角: sm md lg xl */
---wf-radius-*
-/* 阴影: sm md lg */
---wf-shadow-*
-/* 动效（P0）：时长阶梯/缓动曲线/位移量，全站动效统一引用 */
---wf-dur-fast / --wf-dur-base / --wf-dur-slow
---wf-ease-out / --wf-ease-in / --wf-ease-snap
---wf-motion-sm / --wf-motion-md / --wf-motion-lg
-/* 表头/分组标题（P5）：CJK 感知，默认 none/0，英文可覆盖 */
---wf-heading-case / --wf-heading-tracking
-/* 数字（P5）：tabular-nums 防宽度抖动（wf-nums 工具类） */
---wf-nums
-/* 其他 */
---wf-border-width / --wf-focus-ring
---wf-transition-duration / --wf-transition-timing
---wf-accent-color / --wf-caret-color
---wf-opacity-disabled / --wf-opacity-overlay
---wf-pop-z / --wf-cover-z
-/* 应用外壳 */
---wf-sidebar-width
-```
-### 暗色模式
-两种激活方式（显式 `data-theme` 优先级更高）：
-```ts
-// 1. 手动切换
-// document.documentElement.setAttribute('data-theme', 'dark')
-// document.documentElement.setAttribute('data-theme', 'light') // 强制亮色
-// 2. 自动：系统暗色偏好（无需任何代码）
-// 系统为暗色时自动生效；加 data-theme="light" 可强制亮色
-```
-暗色值定义在原始层 `--wf-dark-*`（只写一次），`_dark.css` 两段仅做语义映射——改暗色调校只动原始层，无硬编码色值。
----
-# 样式定制指南
-## 组件定制钩子（零覆盖 CSS）
-关键组件视觉全部变量化——定制只需设一个变量（默认值 = 现有 token）：
-```html
-<style>
-  :root {
-    --wf-brand-500: #7c3aed;      /* 品牌换色：改原始层一个值，全站跟随 */
-    --wf-dark-brand-500: #a78bfa; /* 暗色品牌（可选） */
-    --wf-modal-width: 640px;      /* 组件定制：设一个变量 */
-    --wf-btn-radius: 999px;
-    --wf-field-height: 44px;
-    --wf-card-shadow: 0 8px 24px rgba(0,0,0,.12);
-  }
-</style>
-```
-钩子清单：`--wf-btn-*` `--wf-card-*` `--wf-field-*` `--wf-modal-*` `--wf-drawer-width` `--wf-toast-*` `--wf-alert-radius` `--wf-badge-radius` `--wf-tag-radius` `--wf-switch-radius` `--wf-popover-*` `--wf-tooltip-radius` `--wf-dropdown-min-width` `--wf-datepicker-*`。
-**覆盖优先级（@layer）**：`@layer tokens, base, layout, utilities, components`——你写的未分层 CSS 天然最高优先级；也可用 `@layer utilities` 精准覆盖我们。
-## 零自定义 CSS 模式（推荐）
-一个项目只需要引用**一个 CSS 文件**（`weifuwu/components/style.css`，内含 Token + 布局原语 + 组件样式），
-业务代码全部由组件 + `wf-*` 原语承担，**不需要再写 `style.css`**：
-```tsx
-// 组件 → 页面功能块；wf-* 原语 → 块之间的空间关系；--wf-* → 业务色值
-<PageHeader title="仪表盘" sub="欢迎回来">
-  <Button variant="primary">+ 新建</Button>
-</PageHeader>
-<div class="wf-row wf-gap-lg">
-  <StatCard label="总用户" value="1,234" trend="up" trendLabel="12%" />
-</div>
-```
-主题定制（品牌色/圆角/字体）不需要独立文件——**内联在 HTML 的 `<style>` 里即可**：
-```html
-<style>
-  :root {
-    --wf-color-primary: #6366f1;
-    --wf-radius: 8px;
-  }
-</style>
-```
-完整的零样式示例：`apps/components-demo`（组件 + 原语即插即用，无手写样式）。
-诚实例外（合理场景，仍可内联 `<style>` 解决）：打印/PDF 导出规则、第三方库宿主样式、
-业务特有的一次性视觉（如色板选择器交互）。
-## 全局主题变量
-所有组件引用 `--wf-*` CSS 变量。在根元素覆盖即可定制主题：
-```css
-:root {
-  --wf-color-primary: #6366f1;
-  --wf-color-primary-hover: #4f46e5;
-  --wf-radius: 8px;
-  --wf-font-sans: 'Inter', system-ui, sans-serif;
-}
-```
-## 暗色模式
-两种激活方式（显式 `data-theme` 优先级高于系统偏好）：
-```ts
-// 手动切换
-document.documentElement.setAttribute('data-theme', 'dark')
-// 强制亮色（系统为暗色时也保持亮色）
-document.documentElement.setAttribute('data-theme', 'light')
-```
-未设置 `data-theme` 时，自动跟随系统偏好：`@media (prefers-color-scheme: dark)` 下自动切换暗色。
-所有 `--wf-*` 变量在暗色下自动切换。可自定义暗色变量：
-```css
-[data-theme="dark"] {
-  --wf-color-bg: #1a1a2e;
-  --wf-color-text: #e0e0e0;
-  --wf-color-border: #2a2a4a;
-}
-/* 自定义系统自动暗色的变量（需与上面同步） */
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme="light"]) {
-    --wf-color-bg: #1a1a2e;
-    --wf-color-text: #e0e0e0;
-    --wf-color-border: #2a2a4a;
-  }
-}
-```
-## 组件级覆盖
-```css
-/* 覆盖 Button 主色 */
-.wf-btn--primary {
-  background: #06b6d4;
-  border-color: #06b6d4;
-}
-/* 覆盖 Modal 圆角 */
-.wf-modal-content {
-  border-radius: 16px;
-}
-```
-## 作用域主题
-```html
-<div style="--wf-color-primary: #f59e0b;">
-  <!-- 此区域内组件使用金色主题，外部不受影响 -->
-  <button class="wf-btn wf-btn--primary">金色按钮</button>
-</div>
-```
-CSS 变量会沿 DOM 树继承，利用这一点可实现多主题共存。
----
-# 组合场景示例
-## 登录表单
-```tsx
-const LoginPage = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.errors = {}
-  $.submitting = false
-  return (props) =>
-    h('div', { class: 'wf-stack', style: { maxWidth: 400, margin: '40px auto' } },
-      h(Card, { padding: 'lg' },
-        h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
-          h('h2', {}, '登录'),
-          h(Form, {
-            validation: {
-              email: [{ required: true, pattern: /@/, message: '请输入有效邮箱' }],
-              password: [{ required: true, minLength: 6, message: '密码至少6位' }],
-            },
-            onSubmit: async (values) => {
-              $.submitting = true
-              await ctx.api?.post('/login', values)   // api 客户端由中间件注入 ctx.api
-              $.submitting = false
-            },
-            onError: (errors) => { $.errors = errors },
-          }, [
-            h(Field, { label: '邮箱', error: $.errors.email },
-              h(Input, { name: 'email', type: 'email', placeholder: 'name@example.com' })),
-            h(Field, { label: '密码', error: $.errors.password },
-              h(Input, { name: 'password', type: 'password' })),
-            h(Button, { type: 'submit', loading: $.submitting, block: true }, '登录'),
-          ])
-        )
-      )
-    )
-}
-```
-## 数据列表 + 搜索
-```tsx
-const UserList = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.keyword = ''
-  $.sortKey = 'name'
-  $.sortOrder = 'asc'
-  const users = [
-    { id: 1, name: '张三', email: 'zhang@example.com', role: '管理员' },
-    { id: 2, name: '李四', email: 'li@example.com', role: '编辑' },
-  ]
-  return (props) => {
-    // 派生数据必须在 render 内计算（每次 render 读最新 $.keyword）
-    const filtered = users.filter(u =>
-      !$.keyword || u.name.includes($.keyword) || u.email.includes($.keyword)
-    )
-    return h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
-      h('div', { class: 'wf-row', style: { justifyContent: 'space-between', alignItems: 'center' } },
-        h(SearchInput, { placeholder: '搜索用户...', value: $.keyword, onInput: (e: Event) => { $.keyword = (e.target as HTMLInputElement).value } }),
-        h(Button, { variant: 'primary' }, '新建用户'),
-      ),
-      h(Table, {
-        columns: [
-          { key: 'id', label: 'ID', width: 60 },
-          { key: 'name', label: '姓名', sortable: true },
-          { key: 'email', label: '邮箱', sortable: true },
-          { key: 'role', label: '角色' },
-        ],
-        data: filtered,
-        sortKey: $.sortKey,
-        sortOrder: $.sortOrder,
-        onSort: (key, order) => { $.sortKey = key; $.sortOrder = order },
-        emptyText: '无匹配用户',
-      }),
-      h(Pagination, { total: filtered.length, page: 1, pageSize: 10, onChange: (p: number) => {} }),
-    )
-  }
-}
-```
-## 消息提示
-```tsx
-// 在任意组件中调用
-let toastId = 0
-function showToast(ctx: WfuiContext, type: ToastType, message: string) {
-  // 通过 ctx 管理 Toast 列表
-  const $ = ctx.ui.$()
-  $.toasts = $.toasts ?? []
-  const id = String(++toastId)
-  $.toasts = [...$.toasts, { id, type, message }]
-  // 自动消失
-  if (type !== 'error') {
-    setTimeout(() => {
-      $.toasts = $.toasts.filter((t: any) => t.id !== id)
-    }, 3000)
-  }
-}
-// 页面中使用
-const App = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.toasts = []
-  return (props) =>
-    h('div', {}, [
-      h(Button, {
-        onClick: () => showToast(ctx, 'success', '操作成功'),
-      }, '显示提示'),
-      h(Toast, {
-        toasts: $.toasts,
-        position: 'top-right',
-        max: 3,
-        onRemove: (id) => { $.toasts = $.toasts.filter((t: any) => t.id !== id) },
-      }),
-    ])
-}
-```
----
-# 环境变量
-| 变量 | 用途 | 模块 |
-|------|------|------|
-| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres()` |
-| `REDIS_URL` | Redis 连接字符串 | `redis()` |
----
-# 开发命令
-```bash
-npm run build       # 构建 dist/
-npm run typecheck   # TypeScript 类型检查
-npm test            # 运行 node --test
-node scripts/release.mjs <version>   # 发布
-```
-```bash
-# 测试前启动依赖服务
-docker compose up -d
-```
----
-# SaaS 地基模块（rateLimit / email / userSystem / messager / queue）
-五个模块（限流 / 邮件 / 用户系统 / 消息系统 / 队列）以中间件形态随包提供，`app.use(...)` 一行接入。
-四个内建模块组成一个"基本 SaaS 底座"：认证、异步任务、限流、邮件——零新增依赖
-（只依赖已自研的 redis / postgres 客户端与 node 标准库）。
-## rateLimit — 限流
-```ts
-import { rateLimit } from 'weifuwu'
-app.use(redis())                                        // 依赖 ctx.redis
-app.use(rateLimit({ windowMs: 60_000, max: 100 }))      // 全局限流（默认固定窗口）
-app.get('/api/search', async (req, ctx) => {
-  await ctx.limit('search', { max: 30, windowMs: 60_000 })  // 手动限流，超限抛 429
-})
-// 登录/注册防爆破：ctx.limit 默认按 IP 维度（每 IP 独立计数）
-app.post('/api/auth/register', async (req, ctx) => {
-  await ctx.limit('register', { max: 5, windowMs: 60_000 }) // 每 IP 每分钟 5 次
-})
-// 系统级总量限制：scope: 'global' 全局共享维度
-await ctx.limit('total-jobs', { max: 1000, windowMs: 60_000, scope: 'global' })
-// 登录防爆破（配合 userSystem）：组合键 ip:email（key 接收标准 Request，取头拿 IP）
-app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}:${req.headers.get('x-user-email')}`, max: 5, windowMs: 15 * 60_000 }))
-```
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `windowMs` | `60000` | 时间窗口 |
-| `max` | `100` | 窗口内最大请求 |
-| `key` | X-Forwarded-For | 限流键（生产环境配置反向代理注入） |
-| `algorithm` | `fixed` | `fixed`（INCR+EXPIRE，原子）\| `sliding`（ZSET，仅 redis） |
-| `store` | `redis` | `redis`（多实例一致）\| `memory`（仅单实例/开发） |
-- 响应自动带 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` / `Retry-After`
-- 多实例共享计数：计数在 redis，水平扩展天然一致
-## email — 邮件发送
-```ts
-import { email } from 'weifuwu'
-app.use(email({ from: 'no-reply@your.app', adapter: 'resend', resend: { apiKey: process.env.RESEND_API_KEY } }))
-// 或 adapter: 'smtp' + smtp: { host, port, user, pass }（自研 SMTP 客户端，零依赖）
-app.post('/api/notify', async (req, ctx) => {
-  await ctx.email.send({ to: 'user@x.com', subject: '通知', html: '<h1>hi</h1>' })
-})
-```
-- 适配器：`resend`（默认，一个 POST）/ `smtp`（自研 node:net + node:tls：EHLO/STARTTLS/AUTH PLAIN/DATA/dot-stuffing，非 ASCII subject 自动 RFC2047 编码）/ 自定义函数
-- 裁剪：附件、退信/送达率（服务商职责）、批量营销不支持
-## userSystem — 用户系统
-```ts
-import { userSystem } from 'weifuwu'
-const db = postgres()
-await db.migrate()
-const users = userSystem({ sql: db.sql, secret: process.env.AUTH_SECRET })
-await users.migrate()          // 幂等建表（users + sessions）
-app.use(db)
-app.use(users)                 // 注入 ctx.user / ctx.auth
-users.routes(app)              // POST /api/auth/register|login|logout|refresh + GET /api/auth/me
-app.get('/me', (req, ctx) => ok(ctx.user))        // 已注入
-app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
-```
-- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/client` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
-- **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
-- **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
-- **多租户感知**：`issueSession` 的 token payload 携带 `tenantId`（来自 `user.tenant`）——中间件自动注入 `ctx.tenantId`，并将会话字段（userId/tenantId/email/name/role）合并到 `ctx.auth`，多租户应用免写 token 解码/租户中间件（数据隔离 SQL 是应用职责）
-- **`routes` 支持 `exclude`**：`users.routes(app, { exclude: ['register'] })`——应用自定义注册流程（如注册时建租户）时跳过框架路由
-- **裁剪**：OAuth、邮箱验证邮件（给底层 API 自接）、多因素、RBAC 权限引擎（只留 `role` 字段）、租户隔离 SQL（框架只做感知，`WHERE tenant_id` 属应用层）
-## messager — 消息系统
-```ts
-import { messager } from 'weifuwu'
-const db = postgres()
-await db.migrate()
-const msg = messager({ sql: db.sql, redis: rds })   // redis 可选：跨进程广播
-await msg.migrate()            // 幂等建表（conversations + members + messages）
-app.use(db)
-app.use(msg)                   // 注入 ctx.msg
-msg.routes(app)                // /api/messages/*（会话/历史/发消息/已读）
-app.ws('/ws', msg.handler())        // 标准 WS 协议内置
-// 业务代码：持久化 + 鉴权 + 广播 + 未读 + 历史，一次调用
-const conv = await ctx.msg.createConversation(ctx.user.id, { type: 'group', memberIds: ['u2'] })
-await ctx.msg.sendMessage(conv.id, { senderType: 'user', senderId: ctx.user.id, content: '你好' })
-ctx.msg.broadcast(`conv:${conv.id}`, { type: 'order_chat', orderId: 'o1' })  // 任意实时事件
-ctx.msg.sendTo('u2', { type: 'mention' })       // 用户维度点对点
-```
-- **数据模型**：`_weifuwu_conversations` / `_weifuwu_conversation_members` / `_weifuwu_messages`（`sender_type + sender_id` 不 FK users——user/agent/system 消息天然可存）；direct 会话同对用户唯一、历史游标分页、未读数（`last_read_at`）、编辑/删除软删
-- **实时协议内置**：`handler()` 提供 `connected / subscribe→subscribed / unsubscribe / ping→pong`——前端 `ctx.ws.send({ type: 'subscribe', room })` 直接可用，两端协议由框架定义
-- **跨进程**：`redis` 选项 → Redis pub/sub 广播（psubscribe 模式），多实例部署天然一致；无 redis 优雅降级单进程。
-  **环回去重**：`broadcast` = 本地直发 + Redis publish，本实例的 subscriber 会收到自己 publish 的消息——publish 携带实例唯一标识 `_pid`（`wf:{pid}:{seq}`），订阅回调跳过自己的环回，保证每个事件恰好投递一次（防 token 级事件重复/乱序）
-- **与 userSystem 咬合**：`sendTo(ctx.user.id)` 按身份路由、`createConversation(ctx.user.id)` 创建者即身份、成员校验自动对齐——身份是消息的路由，消息是身份的交互
-- **裁剪**：已读回执状态机（只做未读数）、附件存储、全文搜索、消息确认/重试（可靠投递用 queue）、移动端推送
-## queue — 可靠任务队列
-```ts
-import { queue } from 'weifuwu'
-const q = queue()              // 默认 REDIS_URL
-app.use(q)                     // 注入 ctx.queue
-app.post('/api/generate', async (req, ctx) => {
-  await ctx.queue.add('llm.batch', { prompt: '...' }, { attempts: 3 })
-  return new Response(null, { status: 202 })  // 立即 202，任务后台执行
-})
-// 消费者（独立进程或同进程均可，多开安全）
-const worker = q.worker('llm.batch', async (job) => {
-  await runLLM(job.data)       // 失败自动重试 → 用尽进 DLQ（q:llm.batch:dead）
-}, { concurrency: 5, visibilityTimeout: 30_000 })
-await worker.start()
-await worker.stop()            // 优雅停止
-```
-- **语义**：at-least-once（handler 可能重复执行——幂等由业务保证）；Redis Streams 消费组，多 worker 实例不重复消费
-- **可靠性**：失败 → 延迟重试（间隔 = `visibilityTimeout`，ZSET 延迟队列）→ attempts 用尽 → DLQ；worker 崩溃 → pending 由其他实例 `XAUTOCLAIM` 接管
-- 裁剪：延迟调度（除重试外）、cron、优先级、指数退避、速率限制不支持
-## ai — LLM 对话（自研协议 + 零依赖客户端）
-```ts
-import { ai } from 'weifuwu'
-const a = ai()          // DEEPSEEK_API_KEY / BASE_URL / MODEL 自动读 env，默认 deepseek-v4-flash
-app.use(a)              // 注入 ctx.ai（worker/非请求场景也可直接 a.chat()）
-// 流式对话：路由一行返回 SSE（wf: 协议，详见 docs/ai-contract.md）
-app.post('/api/chat', async (req, ctx) => {
-  const { messages } = await req.json()
-  return ctx.ai.stream({ messages }, {
-    signal: req.signal,                                    // 断开即取消 provider 请求
-    traceId: req.headers.get('x-trace-id') ?? undefined,   // 追踪关联（协议 §7）
-  })
-})
-// 非流式（worker/后台）：
-const res = await a.chat({ messages: [{ role: 'user', content: 'hi' }] })
-// agent 引擎：工具循环 + 人工审批（HITL）
-const agent = a.agent({
-  systemPrompt: '你是助手。查询天气时调用 query_weather 工具。',
-  tools: [{
-    name: 'query_weather',
-    description: '查询城市天气',
-    parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
-    run: async (args, { emit }) => {
-      emit('wf:tool_progress', { toolCallId: 'x', step: 1, total: 2, message: '查询中…', status: 'running' })
-      return { city: args.city, temp: 25 }
-    },
-  }],
-  humanInTheLoop: true,   // 每个工具执行前等人工审批
-})
-app.post('/api/agent', async (req, ctx) => {
-  const { messages } = await req.json()
-  return agent.run(messages, { signal: req.signal, traceId: req.headers.get('x-trace-id') ?? undefined })
-})
-// HITL 审批响应（前端点"允许/拒绝" → POST 到这里）
-app.post('/api/approve', async (req, ctx) => {
-  ctx.ai.approve(await req.json())   // { id, decision, modifiedArgs?, note? }
-  return new Response(null, { status: 200 })
-})
-```
-前端解码（`weifuwu/client`）：
-```ts
-import { aiStream } from 'weifuwu/client'
-const handle = aiStream('/api/chat', { messages }, {
-  onToken: (text) => { /* 增量 append 到消息 */ },
-  onToolCall: (call) => { /* 渲染工具卡片 */ },
-  onDone: () => { /* 收尾 */ },
-  onError: (e) => { /* 按 e.code 降级 */ },
-  onEvent: (name, data) => { /* x:* 自定义事件透传 */ },
-})
-handle.abort()  // 用户停止/组件卸载/导航跳走
-```
-前端对话层（会话语义 + 标准界面，协议对页面透明）：
-```tsx
-// ctx.ui.useChat：会话语义（消息累积/工具内嵌/审批/重试），返回页面同一个 $
-const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
-// $.messages / $.input / $.streaming / $.error / $.usage / $.step
-// $.send() / $.stop() / $.retry() / $.clear() / $.approve('approved', note?)
-// AiChat：标准对话界面（气泡 / 工具卡 / 审批卡 / 自动滚动 / 错误重试）
-return () => <AiChat chat={$} />
-// agent 模式消息内嵌：msg.toolCalls（ToolCallCard 直接消费）/ msg.approval（ApprovalCard）
-```
-> 分层：`ctx.ai`（后端协议）→ `aiStream`（传输解码）→ `useChat`（会话语义）→ `AiChat`（标准界面）。要完全自定义 UI 的应用用 useChat + 自有渲染；要 5 分钟出界面用 AiChat。
-- **协议**：`wf:` 命名空间（message_start/token/tool_call/tool_progress/usage/done/error + agent 扩展 step/approval_request），SSE 下行 + POST 上行，错误即值、未知事件透传、`x:*` 自定义事件（详见 [docs/ai-contract.md](./docs/ai-contract.md)）
-- **agent 引擎**：`a.agent({ systemPrompt, tools, humanInTheLoop })` 工具循环（LLM → tool_call → 执行 → 回喂 → 重复）；工具可 `emit` 进度/自定义事件、接收 `signal` 取消；HITL 审批（`ctx.ai.approve` 响应，拒绝≠终止、modified 改参、超时兜底）
-- **emitter 抽象**：`agent.stream(messages, { emit })`——`wf:*` 事件（step/token/tool_result/usage/done）可接任意通道（SSE/WS/回调），协议不焊死在传输层；`agent.runToResult(messages)` 返回结构化结果 `{ content, steps, usage }`（非流式/worker 场景）
-- **embedding**：`ctx.ai.embed(text)` / `embedMany(texts)` 向量化（默认 `DASHSCOPE_API_KEY` + `text-embedding-v4`，compatible-mode 端点）；未配置抛 `AiError('unsupported')`（惰性检查，不静默降级）——知识库/语义检索开箱即用
-- **零依赖**：自研 OpenAI 兼容客户端（fetch + SSE 解析），默认 DeepSeek，`baseUrl` 可换任意 OpenAI 兼容端点（Ollama/vLLM/Moonshot…）
-- **追踪**：前端自动生成 `X-Trace-Id` → 后端以之作为 `message_start.id` → 工具内请求继承同一 traceId，整个 agent run 一次搜完
-- **裁剪**：Anthropic 原生协议、审批持久化（连接断=会话亡）暂不支持；多 agent 编排不承诺（子 agent = 工具已支持）；embedding 仅文本（图片/多模态不做）
-## 组合示例：注册 → 验证邮件 → 欢迎任务 → 登录防爆破
-```ts
-app.use(redis())
-app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}`, max: 5, windowMs: 60_000 }))  // 防爆破
-app.use(email({ from: 'no-reply@x.com', adapter: 'resend', resend: { apiKey } }))
-app.use(db)
-app.use(users)
-users.routes(app)
-// 注册：限流守卫 → 用户系统 → 验证邮件 → 欢迎任务入队
-app.post('/api/auth/register', async (req, ctx) => {
-  await ctx.limit(`register:${req.ip}`, { max: 10, windowMs: 60_000 })
-  const result = await ctx.auth.register(await req.json())
-  const token = ctx.auth.createToken('verify', { sub: result.user.id }, { ttlSeconds: 86400 })
-  await ctx.email.send({ to: result.user.email, subject: '验证邮箱', html: `...?token=${token}` })
-  await ctx.queue.add('welcome.flow', { userId: result.user.id })
-  return created(result)
-})
-const worker = q.worker('welcome.flow', async (job) => { /* 欢迎流程 */ })
-await worker.start()
-```
+> `docs/` 用户文档随 npm 包发布（`files: ['dist/', 'README.md', 'docs/']`）——`node_modules/weifuwu/docs` 可离线查阅；`design/` 设计/计划文档仅仓库内。