weifuwu 0.74.0 → 0.76.0

package/docs/components.md

@@ -2,14 +2,14 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-109 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+113 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 > **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`docs/components-map.md`](components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
 > **自定义组件开发**：见 [docs/custom-components.md](custom-components.md)——usePopup/useControlled/对话框/AI 组件/类型纪律逐步指南。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
-import 'weifuwu/components/style.css'   // 包含 Token + 57 布局原语 + 136 工具类 + 组件样式，一次性引入
+import 'weifuwu/components/style.css'   // 包含 Token + 58 布局原语 + 136 工具类 + 组件样式，一次性引入
 ```
 
 ### 使用示例
@@ -26,9 +26,10 @@ import 'weifuwu/components/style.css'   // 包含 Token + 57 布局原语 + 136
 <Input type="password" hint="至少6位" />
 <Input name="email" type="email" disabled placeholder="name@example.com" />
 
-// ├─ 选择器
+// ├─ 选择器（options 支持平铺项与分组混用：{ label, options } → optgroup）
 <Select options={[{ value: 'a', label: '选项A' }]} placeholder="请选择" />
 <Select searchable options={options} onChange={v => setVal(v)} />
+<Select options={[{ label: '一线', options: [{ value: 'bj', label: '北京' }] }, { value: 'other', label: '其他' }]} />
 
 // ├─ 复选框 / 开关 / 单选
 <Checkbox checked={agree} onChange={setAgree} label="同意协议" />
@@ -647,7 +648,11 @@ 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） |
+| JsonSchemaForm | `JsonSchemaForm` | `schema`, `value?`, `onChange?`, `onSubmit?`, `submitLabel?` | JSON Schema（对象子集）→ 参数输入表单：类型映射 + required/范围校验 + 嵌套/数组（工具参数输入面；不支持项告警降级） |
+| ReasoningBlock | `ReasoningBlock` | `content`, `label?`, `defaultExpanded?`, `streaming?` | CoT 推理折叠展示（thinking 模式 `reasoning_content`；aria-expanded + 键盘可达 + 流式脉冲） |
+| CitationCard | `CitationCard` | `items`, `label?`, `maxVisible?`, `defaultExpanded?`, `onOpen?` | RAG 引用来源展示：折叠「引用 N 条」+ 条目（序号/标题/来源/片段/链接）+ 溢出 +N；onOpen 时全部可点（调用方处理跳转） |
+| SessionList | `SessionList` | `sessions`, `activeId?`, `onSelect?`, `onNew?`, `onRename?`, `onDelete?`, `searchable?` | 会话管理列表：分组（今天/昨天/更早）+ 选中高亮 + 搜索 + 行内重命名（Enter 确认/Escape 取消）/删除 + 键盘方向键导航 |
+| ApprovalCard | `ApprovalCard` | `request`, `status?`, `onApprove(modifiedArgs?)`, `onReject`, `argsSchema?` | 人工审批卡片：待批（允许/拒绝+备注）/ 已批 / 已拒 / 超时；`argsSchema` 提供时渲染「修改参数」（JsonSchemaForm 预填 args，提交带修改后参数 → `onApprove(modifiedArgs)` → 父层选 modified 决策） |
 
 ### 全局工具
 

package/docs/custom-components.md

@@ -1,8 +1,8 @@
 # 自定义组件开发指南
 
 
-> ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
-> 用 weifuwu/client 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
+> ⚠️ **weifuwu/client 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> 用 weifuwu/ui-dom 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
 > 前置：[前端概念](frontend.md)（两阶段模型/ctx.ui）+ [组件列表](components.md)。
 
 ---
@@ -10,7 +10,7 @@
 ## 0. 最小骨架
 
 ```tsx
-import { h, type Component } from 'weifuwu/client'
+import { h, type Component } from 'weifuwu/ui-dom'
 
 // Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
 const Badge: Component<{ text: string; color?: string }> = () =>
@@ -76,7 +76,7 @@ const MyPopover: Component<{ content: string }> = (_init, ctx) => {
 全屏对话框（焦点 trap + 滚动锁 + 退场动画）不在 usePopup 范围——用 **`ctx.ui.useDialog`** 组合器（Modal/Drawer 同款：退场状态机 + 滚动锁 + 焦点 trap + animationend 卸载）：
 
 ```tsx
-import { createPortal } from 'weifuwu/client'
+import { createPortal } from 'weifuwu/ui-dom'
 
 const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx) => {
   const dialog = ctx.ui.useDialog({ name: 'MyDialog' })   // mount 创建
@@ -98,7 +98,7 @@ const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx)
 ```
 
 > `dialog.rootRef` 挂到 portal 根（lockScroll + animationend 退场监听）；`panelRef` 挂到面板（trapFocus）。
-> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/client` 导出（特殊场景组装用）。
+> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/ui-dom` 导出（特殊场景组装用）。
 
 ## 4. AI 组件
 
@@ -135,10 +135,9 @@ const UserCard = async (initProps, ctx) => {
 }
 ```
 
-- 渲染器按「返回值是 Promise」判别：客户端未 resolve → 占位（`Placeholder`），resolve 后整树补全；SSR 直接 await（无占位）
+- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；动态挂载兑底占位 + 局部补全；SSR 直接 await
 - 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
-- 占位显示：无边界 → null；`<Suspense fallback={...}>` → 占位处显示 fallback（可选）
-- 代码分割/昂贵一次性资源：`asyncComponent(async (ctx) => { const { default: def } = await import('./view'); return def })`（WeakMap 全局一次，兼容保留）
+- 占位显示：动态挂载的 async 组件占位 = 注释节点，resolve 后局部补全（Suspense 边界已裁剪）
 - **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
 
 ## 6. 类型纪律（编译期防线）
@@ -168,17 +167,23 @@ const Page: Component<{}, { api: ApiInjected['api'] }> = (_init, ctx) => {
 
 ## 7. 测试写法
 
+**官方测试原语 `weifuwu/ui-dom/testing`**（子路径，随包发布）——自研组件测试用官方工具，不手抄：
+
 ```tsx
-function renderVNode(Comp: any, props: any, ctx: any) {
-  const result = Comp(props, ctx)
-  return typeof result === 'function' ? result(props) : result
-}
+import { renderVNode, mountComponent, findByClass, createTestCtx } from 'weifuwu/ui-dom/testing'
+// 仓库内开发用相对路径：from '../../ui-dom/testing.ts'
 
-const ctx = { ui: { $: () => ({}), render: () => {}, dirty: () => {}, useControlled: (o: any) => ({ value: o.value, setValue: o.onChange ?? (() => {}), controlled: o.value !== undefined }) } }
-const vnode = renderVNode(Toggle, {}, ctx)
+const vnode = renderVNode(Toggle, {}, createTestCtx())
 // 断言 vnode 结构（子组件 VNode.type 是组件函数，不是标签名）
+
+// 交互流转（内部 let 状态）用 mountComponent（同实例 re-render）：
+const render = mountComponent(Toggle, {}, createTestCtx())
+render() // 初始
+// ... 触发点击/输入 ...
+render() // 重渲染，状态保留
 ```
 
+- 弹层组件：`createPopupMock(isOpen)` 注入 `createTestCtx({ ui: { usePopup: () => popup } })`
 - 类型流测试：`@ts-expect-error` 负例（见 [type-flow.test.ts](../src/components/type-flow.test.ts)）
 - 组件测试跑在 node --test；DOM 事件级测试需 `document.body.appendChild(container)`
 

package/docs/data.md

@@ -27,9 +27,11 @@ app.post('/decks', async (req, ctx) => {
   // 读回来自动是对象：rows[0].deck_json === { slides: [...] }（不是字符串）
 })
 
-// ③ 事务（postgres.js 兼容 begin）
+// ③ 事务（中间件实例 pg.transaction——不在 ctx.sql 接口）
+const pg = postgres()
+app.use(pg)
 app.post('/transfer', async (req, ctx) => {
-  await ctx.sql.begin(async sql => {
+  await pg.transaction(async sql => {
     await sql`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
     await sql`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
   })
@@ -105,20 +107,12 @@ const q = queue({ redis })
 | timestamp / date / interval | `string`（无时区语义——转 Date 按本地时区解析即时区魔法，诚实裁剪不转） |
 | NULL | `null` |
 
-### 类型层（查询泛型 + schema 写前校验）
+### 类型层（查询泛型）
 
 ```ts
-// ① 查询结果泛型（编译期类型，无需手写 interface + 断言）
+// 查询结果泛型（编译期类型，无需手写 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
+const decks = await ctx.sql`SELECT id, title, deck_json FROM decks` as Deck[]
 ```
 
 ### 方法面
@@ -126,17 +120,13 @@ await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → Validati
 | 方法 | 说明 |
 |------|------|
 | `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()` | 关闭连接池 |
+| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名；`$1` 占位符） |
+| `ctx.sql.query` | **Query Language**：`sql.query.from('users').where({...}).run()`（AST 双后端） |
+| `ctx.sql.raw\`...\`` | 逃生舱片段（`NOW() - interval '7 days'`——真库透传/内存裁剪） |
+| `pg.transaction(fn)` | 事务（中间件实例；回调收到 callable sql，postgres.js 兼容 begin 语义） |
+| `pg.migrate()` / `markMigrated` / `isMigrated` | 幂等迁移（`_weifuwu_migrations` 表） |
+| `pg.poolStats()` | 连接池摘要（active/idle/waiting/max） |
+| `ctx.sql.close()` / `pg.close()` | 关闭连接池 |
 
 ### 影响行数（affectedRows）
 
@@ -147,14 +137,6 @@ 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
@@ -281,10 +263,11 @@ await ctx.redis.set('user', 1)         // 实际写入 'api:user'
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
+| `url` | `string` | `REDIS_URL` 环境变量（两者都缺 → 构造抛错，禁止静默回退 localhost） | 连接字符串 |
 | `poolSize` | `number` | `5` | 连接池大小 |
 | `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
 | `commandTimeoutMs` | `number` | `0` | 命令超时（阻塞命令 resolve(null)；防挂起。0=禁用） |
+| `onCommand` | `(command, args, durationMs, traceId?) => void` | — | 命令观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
 | `socketTimeoutMs` | `number` | `0` | socket 响应超时（僵尸连接自愈：pending 有命令且超时无数据 → 主动断开重连。0=禁用） |
 
 > **连接健康**：断线自动剔除死连接并重建（池不萎缩）；`CLIENT KILL`/网络抖动后服务自愈，命令不命中死连接。

package/docs/environment.md

@@ -7,7 +7,7 @@
 | 变量 | 用途 | 模块 | 默认 |
 |------|------|------|------|
 | `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres()` | —（必填） |
-| `REDIS_URL` | Redis 连接字符串 | `redis()` | `redis://localhost:6379` |
+| `REDIS_URL` | Redis 连接字符串 | `redis()` | —（必填；缺 env 且未传 `url` 构造抛错，不静默回退 localhost） |
 | `AUTH_SECRET` | userSystem HMAC 签名密钥（≥16 字符） | `userSystem()` | 可传 `options.secret` |
 | `DEEPSEEK_API_KEY` | LLM 对话 provider API key | `ai()` | — |
 | `DEEPSEEK_BASE_URL` | LLM 对话 provider 端点 | `ai()` | `https://api.deepseek.com/v1` |

package/docs/frontend-middleware.md

@@ -1,93 +1,79 @@
 # 前端中间件与工具（weifuwu/ui-dom）
 
-> ⚠️ **`weifuwu/client` 已删除**——中间件（api/auth/ws/i18n）现位于 `weifuwu/ui-dom`，新 API 见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（UIRouter + uiServe），见 [frontend-ui-dom.md](frontend-ui-dom.md)。
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-## router + RouteView — 前端路由
+## UIRouter — 前端路由
 
 ```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 函数
+import { UIRouter, uiServe, h } from 'weifuwu/ui-dom'
+import type { UIHandler } from 'weifuwu/ui-dom'
+
+const app = new UIRouter()
+app.get('/', () => h(Home, {}))
+app.get('/users', () => h(UserList, {}))
+app.get('/users/:id', (loc, ctx) => h(UserDetail, { id: ctx.params.id }))
+app.notFound(() => h(NotFound, {}))
+app.use(toast())                    // 中间件（ctx 注入）——app.use(mw)
+
+uiServe(app, { root: '#root' })     // 客户端落地（hydrate: true 收养 SSR HTML）
 ```
 
-### 嵌套布局
+### 嵌套布局（中间件两阶段）
 
 ```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>
-  )
+const DashboardLayout: UIMiddleware = async (_loc, ctx, children) => {
+  const $ = ctx.ui.$()
+  $.open = true
+  return async (loc, c) => {
+    const child = await children(loc, c)   // 子路由/嵌套路由内容
+    return h('div', { class: 'wf-row' },
+      h('aside', {}, '导航菜单'),
+      h('main', {}, child),
+    )
+  }
 }
+app.use(DashboardLayout)
 ```
 
 ### 编程式导航
 
 ```tsx
-// 在任意组件中
+// 在任意组件/页面中（uiServe 注入）
 ctx.app?.navigate('/users/123?tab=profile')
 ```
 
 | ctx 注入 | 类型 | 说明 |
 |----------|------|------|
+| `ctx.params` / `ctx.query` | `Record<string, string>` | 路由参数 / URL query（顶层注入） |
 | `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 页面 |
+| UIRouter API | 签名 | 说明 |
+|--------------|------|------|
+| `get(path, handler)` | `(string, UIHandler)` | 页面路由（handler = async 组件：`async (location, ctx) => vnode`） |
+| `use(prefix, sub)` / `use(mw)` | `(string, UIRouter) \| (mw)` | 子路由树挂载 / 中间件（ctx 注入） |
+| `notFound(handler)` | `(UIHandler)` | 404 页面 |
+| `mode` | `'history' \| 'hash'` | 路由模式（默认 history） |
 
-| RouteDef | 类型 | 说明 |
-|----------|------|------|
-| `path` | `string` | 路径（支持 `:param`） |
-| `component` | `Component` | 页面组件 |
-| `layout` | `Component` | 布局组件（内含 `<RouteView />`） |
-| `children` | `RouteDef[]` | 子路由 |
-| `auth` | `boolean` | 是否需要认证（配合 auth 中间件） |
-| `title` | `string` | 页面标题（自动设置 `document.title`） |
+| UIHandler | 类型 | 说明 |
+|-----------|------|------|
+| 签名 | `(location, ctx) => Promise<VNode> \| VNode` | 页面 = 异步组件（`ctx.data.get` 三场景；async 组件无需包装） |
+| 返回值 | `VNode \| null` | 数据结构（落地由 uiServe/ssrPage 决定） |
 
 ---
 
 ## api — HTTP 客户端中间件
 
 ```tsx
-import { createApp, api } from 'weifuwu/client'
+import { UIRouter, api, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(api({ baseURL: '/api' }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(api({ baseURL: '/api' }))
+uiServe(app, { root: '#root' })
 
 // 在组件中使用
 async function loadUsers(ctx: WfuiContext) {
@@ -139,11 +125,11 @@ try {
 ## auth — 认证中间件
 
 ```tsx
-import { createApp, auth } from 'weifuwu/client'
+import { UIRouter, auth, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(auth())
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(auth())
+uiServe(app, { root: '#root' })
 
 // 在组件中
 function Profile(_props: {}, ctx: WfuiContext) {
@@ -191,11 +177,11 @@ await ctx.auth?.refresh()  // → boolean
 ## ws — WebSocket 客户端中间件
 
 ```tsx
-import { createApp, ws } from 'weifuwu/client'
+import { UIRouter, ws, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(ws({ url: '/ws' }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(ws({ url: '/ws' }))
+uiServe(app, { root: '#root' })
 
 // 发送消息
 ctx.ws?.send({ type: 'chat', body: 'hello' })
@@ -231,10 +217,10 @@ unsubscribe?.()
 ## i18n — 国际化中间件
 
 ```tsx
-import { createApp, i18n } from 'weifuwu/client'
+import { UIRouter, i18n, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(i18n({
+const app = new UIRouter()
+app.use(i18n({
     locale: 'zh-CN',
     messages: {
       'title': '仪表盘',
@@ -268,7 +254,7 @@ ctx.i18n?.setLocale('en-US')
 内置语言包：
 
 ```ts
-import { zhCN, enUS } from 'weifuwu/client'
+import { zhCN, enUS } from 'weifuwu/ui-dom'
 ```
 
 - `zh-CN`：默认中文
@@ -283,7 +269,7 @@ import { zhCN, enUS } from 'weifuwu/client'
 ## ErrorBoundary — 错误边界
 
 ```tsx
-import { ErrorBoundary } from 'weifuwu/client'
+import { ErrorBoundary } from 'weifuwu/ui-dom'
 
 <ErrorBoundary fallback={<p>出错了，请刷新页面</p>}>
   <UserProfile />
@@ -316,12 +302,12 @@ import { ErrorBoundary } from 'weifuwu/client'
 **① 命令式 `ctx.confirm()`（推荐，操作前询问）**
 
 ```tsx
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 import { confirm } from 'weifuwu/components'
 
-createApp()
-  .use(confirm())
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(confirm())
+uiServe(app, { root: '#root' })
 
 // 任意代码中（组件事件、async 逻辑）
 async function handleDelete(ctx: WfuiContext) {
@@ -372,12 +358,12 @@ import { Confirm } from 'weifuwu/components'
 `ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
 
 ```tsx
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 import { toast } from 'weifuwu/components'
 
-createApp()
-  .use(toast({ position: 'top-right', duration: 3000, max: 3 }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(toast({ position: 'top-right', duration: 3000, max: 3 }))
+uiServe(app, { root: '#root' })
 
 // 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
 ctx.toast?.('保存成功', 'success')
@@ -400,8 +386,8 @@ ctx.toast?.('普通消息')          // 默认 type = 'info'
 ## ScrollLock / FocusTrap
 
 ```tsx
-import { lockScroll, unlockScroll } from 'weifuwu/client'
-import { trapFocus } from 'weifuwu/client'
+import { lockScroll, unlockScroll } from 'weifuwu/ui-dom'
+import { trapFocus } from 'weifuwu/ui-dom'
 
 // 锁定/解锁滚动（支持嵌套计数）
 lockScroll()
@@ -423,7 +409,7 @@ cleanup()  // 恢复之前的焦点
 ## extendCtx — 上下文扩展
 
 ```tsx
-import { extendCtx } from 'weifuwu/client'
+import { extendCtx } from 'weifuwu/ui-dom'
 
 // 在 AppMiddleware 中创建新 ctx，原 ctx getter 通过原型链继承
 function myMw(ctx: WfuiContext): WfuiContext {

package/docs/frontend-ui-dom.md

@@ -3,7 +3,7 @@
 > **weifuwu 前端唯一运行时**（`weifuwu/ui-dom`，随 npm 包发布）：
 > **UIRouter（纯路由 + ctx 注入链）+ uiServe（渲染运行时）+ ssrPage/hydration**，
 > 复用 `weifuwu/components`（VNode 契约唯一来源，组件零修改）。
-> 已取代 `weifuwu/client`（createApp/router 已删除）。
+> 已取代 `weifuwu/client`——前端运行时唯一入口（createApp/router 旧 API 已删除）。
 >
 > 概念对齐：**req = window.location**，**res = VNode**（数据结构），
 > **uiServe = VDOM**（落地机制），**params/query 在 ctx**（对齐后端 `ctx.params`）。
@@ -161,5 +161,7 @@ uiServe(app, { root: '#root', hydrate: true })
 ## demo
 
 `apps/ui-router-demo`：UIRouter + uiServe + components（Button/Input/Tag/Dropdown）
-+ toast 注入 + 嵌套路由 + SSR/hydrate 端到端。
++ toast 注入 + 嵌套路由 + SSR/hydrate 端到端（原生 async 组件页 `/async` 验证
+占位补全 + `__DATA__` 三场景）。server 用 weifuwu serve + `ui()` 中间件
+（`ctx.ui.js` 编译前端 / `ctx.ui.css` 组件样式 / `/*` → ssrPage）。
 启动：`node apps/ui-router-demo/server.ts` → http://localhost:3100