weifuwu 0.75.0 → 0.77.0

package/dist/ui-dom/vnode.d.ts

@@ -7,7 +7,7 @@
  *   --jsxImportSource=weifuwu/ui-dom
  */
 import type { WfuiContext } from './types.ts';
-export type VNodeType = string | Component<any, any> | AsyncComponent | typeof Fragment | typeof Portal;
+export type VNodeType = string | Component<any, any> | typeof Fragment | typeof Portal;
 /**
  * VNode 子节点合法值——组件可返回/渲染的多态内容。
  * 递归联合：string/number/VNode/array/null/boolean 任意组合。
@@ -24,55 +24,40 @@ export interface VNode {
     _remoteEl?: HTMLElement | undefined;
     /** VNode 的 DOM 归属：'local' 在父 DOM 树下，'remote' 在别处 */
     _placement?: 'local' | 'remote';
-    /** 两阶段组件的 render 函数（mount 返回的函数） */
-    _render?: (props: Record<string, unknown>) => VNode | null;
+    /** 两阶段组件的 render 函数（mount 返回的函数——强制异步：props 变化时可 await 数据） */
+    _render?: (props: Record<string, unknown>) => Promise<VNode | null>;
     /** 组件实例 ID（如 '_wf_0'） */
     _id?: string;
     /** 自定义组件 ID（ctx.ui.selfId() 注册，跨组件精准刷新） */
     _customId?: string;
     /** 组件输出的 DOM 父节点 */
     _parentNode?: Node;
+    /** 父 vnode 引用（动态挂载补全向上找持有组件） */
+    _parentVNode?: VNode;
     /** 组件输出的第一个 DOM 节点 */
     _refNode?: Node | null;
-    /** 原生 async 组件缓存（vnode 级按实例）：in-flight Promise → resolved renderFn（diff 传递继承） */
-    _asyncDef?: ((props: Record<string, unknown>) => VNode | null) | Promise<((props: Record<string, unknown>) => VNode | null)> | null;
     /** Fragment 展开后的多个直属 DOM 节点范围（diff 对齐用，见 diff.ts） */
     _childNodes?: Node[];
-    /** 组件 mount/render 时的 ctx 版本号（供三态 skip 判定） */
+    /** 组件 renderFn 上次执行时的 ctx 版本号（buildVNode 剪枝 + diff 三态 skip 的版本比较——
+     *  bumpCtxVersion 递增后版本不同 → 强制重跑 renderFn，如 i18n 切换语言） */
     _ctxVersion?: number;
 }
 /**
- * 两阶段组件：外层 = mount（一次），内层 = render（每次 dirty/props 变化）。
+ * 两阶段异步组件（weifuwu 唯一组件形态）：
+ *   async (initProps, ctx) => Promise<renderFn>
+ * 外层 = mount（一次，可 await 数据），内层 = renderFn（每次 dirty/props 变化——**强制异步**，
+ * 可 await 数据；统一异步心智：两阶段都可 await，无「同步组件 vs 异步组件」二元形态）。
  * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
- */
-export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => ((props: P) => VNode | null) | null;
-/**
- * 异步组件（统一签名——与 Component 同参，唯一差别是 async）：
- *   async (initProps, ctx) => Promise<renderFn | null>
  *
- * 渲染器统一判别「返回值 instanceof Promise」：
- *   客户端：占位 → resolve 后整树重渲染（vnode 级 _asyncDef 按实例缓存）
- *   SSR/hydration：直接 await（无占位）
+ * renderFn 签名：async (props) => Promise<VNode | null>——同步 renderFn 是类型错误
+ * （diff 永不执行 renderFn——渲染器在 buildVNode 阶段 await，同步上下文拿不到 vnode）。
+ * 渲染器按「返回值是 Promise」判别（主路径 buildVNode await 全部工厂 + renderFn）。
  */
-export type AsyncComponent<C extends object = {}, P = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<((props: P) => VNode | null) | null>;
+export type RenderFn<P> = (props: P) => Promise<VNode | null>;
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<RenderFn<P> | null>;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;
-/**
- * 占位显示策略组件（原生 async 组件未 resolve 时的占位 vnode）。
- * 渲染时查 ctx 原型链上最近的 Suspense 边界：有 → fallback；无 → null（向后兼容）。
- */
-export declare const Placeholder: Component;
-/**
- * Suspense 边界（可选）：子树内 async 组件占位时显示 fallback。
- * 渲染器对 type === Suspense 的组件在 childCtx 挂 _suspense（Object.create 继承 → 子树可见）。
- * 语义：占位处局部显示 fallback（非 React 整树回滚）；无边界时占位为 null。
- *
- * ```tsx
- * h(Suspense, { fallback: h(Spinner) }, h(UserProfile, {}))
- * ```
- */
-export declare const Suspense: Component;
 /** JSX 类型声明 — 使 TypeScript 理解自定义 JSX 运行时 */
 export declare function jsx(type: VNodeType, props: Record<string, any> | null, key?: string | null): VNode;
 export declare const jsxs: typeof jsx;
@@ -80,6 +65,9 @@ export declare function jsxDEV(type: VNodeType, props: Record<string, any> | nul
 /** `h`（hyperscript）支持 variadic children: `h('div', {class:'x'}, child1, child2)` */
 export declare function h(type: VNodeType, props: Record<string, any> | null, ...children: VNodeChild[]): VNode;
 export declare function isNative(vnode: VNode): boolean;
+/** 递归文本/数组归一化（children 数组展开——嵌套数组扁平化，DOM 范围对齐）。
+ *  栈展开（索引遍历替代 shift/unshift 头部操作——长数组 O(n) 而非 O(n²)）；逆序入栈 + pop 保持原顺序 */
+export declare function normalizeChildren(c: VNodeChild | undefined | null): VNodeChild[];
 export declare function isComponent(vnode: VNode): boolean;
 export declare function isFragment(vnode: VNode): boolean;
 export declare function isPortal(vnode: VNode): boolean;

package/docs/components-map.md

@@ -38,7 +38,7 @@
 |------|---------|------|-------------|-----------|---------|
 | 输入框 | `<Input label error hint variant>` | Input | Input | Input | weifuwu 自带 label/error/hint 包装（antd 需 Form.Item）；`variant="borderless"` 内联编辑 |
 | 文本域 | `<Textarea rows showCount maxLength>` | Input.TextArea | Input textarea | Textarea | weifuwu 独立组件 + 字数统计 |
-| 选择器 | `<Select options searchable multiple>` | Select | Select | Select / Combobox | **searchable + 键盘 ↑↓ + multiple 已实现**（近 Combobox） |
+| 选择器 | `<Select options searchable multiple>` | Select | Select | Select / Combobox | **searchable + 键盘 ↑↓ + multiple + optgroup 分组已实现**（近 Combobox） |
 | 复选框 | `<Checkbox checked label>` | Checkbox | Checkbox | Checkbox | 等价 |
 | 复选组 | `<CheckboxGroup options value>` | Checkbox.Group | Checkbox 组 | — | 数组受控 + 栅格列数 |
 | 单选 | `<RadioGroup options value>` | Radio.Group | Radio | RadioGroup | 等价 |
@@ -115,6 +115,10 @@
 | `<CodeBlock code lang>` | 代码块 + 语言标签 + 复制按钮 |
 | `<MessageBubble role status>` | 聊天气泡（独立复用，AiChat 抽取） |
 | `<ToolCallCard>` | AI 工具调用状态机（running/ok/error） |
+| `<JsonSchemaForm schema value onSubmit>` | JSON Schema → 参数输入表单：类型映射 + 必填/范围校验 + 嵌套/数组（工具参数输入面；不支持项告警降级） |
+| `<ReasoningBlock content>` | CoT 推理折叠展示（thinking 模式 reasoning_content；流式脉冲） |
+| `<CitationCard items>` | RAG 引用来源列表：折叠 + 序号/标题/来源/片段/链接 + 溢出 +N |
+| `<SessionList sessions>` | 会话管理：分组（今天/昨天/更早）+ 搜索 + 重命名/删除/新建 + 键盘导航 |
 | `<ApprovalCard>` | HITL 人工审批卡片（pending/approved/rejected/timeout） |
 | `<Editor>` | 富文本编辑器（contentEditable + 工具栏/表格/图片，零依赖） |
 | `<ThemeSwitch>` | 明暗主题切换（CSS 变量驱动，配 `data-theme`） |
@@ -122,6 +126,19 @@
 | `<AspectRatio>` | 宽高比容器（内容填满） |
 | `<CopyButton>` | 复制（clipboard + execCommand 降级 + 成功状态机） |
 
+## 第九批：AI 差异化（109 → 111 组件，2026-08）
+
+> 三库业务组件覆盖 ~100% 后的差异化期——补 AI **输入层 + 推理展示层**。
+> 完整设计/裁剪见 `design/ai-differentiation-plan.md`。
+
+| 组件 | 类型 | 三库等价 | 要点 |
+|------|------|---------|------|
+| **JsonSchemaForm** | 新增 | @rjsf（依赖重，weifuwu 零依赖子集） | JSON Schema（对象子集）→ 参数输入表单：string/number/integer/boolean/enum/object/array 类型映射 + required/范围校验 + 嵌套/数组增删；不支持项（$ref/组合 schema）告警降级 |
+| **ReasoningBlock** | 新增 | 三库无 | CoT 推理折叠展示：aria-expanded + 键盘可达 + 流式脉冲 |
+| **AiChat 集成** | 增强 | — | `WfDone.reasoning`（additive，收尾一次性下发）+ use-chat 聚合 + toChatMessages 回传 `reasoning_content`（thinking 模式闭环） |
+
+> 协议变更：`wf:done` 新增可选 `reasoning` 字段（向后兼容），见 `design/ai-contract.md` §3.4。
+
 ## 快速迁移路径（三库 → weifuwu）
 
 ```tsx

package/docs/components.md

@@ -2,14 +2,14 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-109 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+113 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`（两阶段组件，与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步），引用 `--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="同意协议" />
@@ -132,9 +133,9 @@ import 'weifuwu/components/style.css'   // 包含 Token + 57 布局原语 + 136
 
 ```
 mount ──────────────────────────────────────────
-  const Counter = (_init, ctx) => {       ← mount（只一次）
+  const Counter = async (_init, ctx) => {   ← mount（只一次，可 await）
     let count = 0                           ← 初始化状态
-    return (props) => {                     ← render 函数
+    return async (props) => {               ← renderFn（强制异步）
       // ...                                 ← 每次 dirty/props 变化执行
     }
   }
@@ -148,7 +149,7 @@ ref ─────────────────────────
   })
 
 props 变化 ─────────────────────────────────────
-  return (props) => {
+  return async (props) => {
     // 每次 render 都收到最新 props           ← 相当于 onupdate
     if (props.value !== prevValue) { ... }
   }
@@ -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

@@ -13,31 +13,51 @@
 import { h, type Component } from 'weifuwu/ui-dom'
 
 // Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
-const Badge: Component<{ text: string; color?: string }> = () =>
-  (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
+const Badge: Component<{ text: string; color?: string }> = async () =>
+  async (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
 ```
 
-- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => VNode` 每次渲染执行
-- 不需要状态就不调 `ctx.ui.$()`；需要交互才用
+- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => Promise<VNode>` 每次渲染执行（renderFn 强制异步——可 await 数据）
+- 有状态组件用闭包 `let` + 事件里 `ctx.ui.render()`（render-only）；不需要渲染的状态不调 `render()`
+
+### mount 与 render 的职责（事件函数写在哪层）
+
+| | mount（外层工厂，一次） | render（内层 renderFn，每次） |
+|---|---|---|
+| 职责 | 初始化状态 / 订阅 / 定时器 / **定义依赖稳定引用的回调** | 读最新 props / 派生数据 / **定义依赖它们的回调** / 输出视图 |
+| 可访问 | `initProps`（首次）、`ctx`、mount `let`、稳定 handle | 最新 `props`、mount 闭包、`ctx` |
+| 事件函数 | **只依赖稳定引用**（ctx / mount let / 稳定 handle 如 useChat 的 `chat`）→ mount 定义，天然引用恒等 | 依赖最新 props / 派生状态（如 Table 的 `rowSelection`、Menu 的 `openSet`）→ render 内定义（闭包捕获最新值） |
+
+```tsx
+const AiChat = async (initProps, ctx) => {
+  const chat = initProps.chat           // 稳定 handle（useChat 返回，引用不变）
+  const onSend = () => chat.send()      // ✅ mount 定义：只依赖稳定引用——引用恒等，零重绑
+  return async (props) => {
+    const onSelect = (k: string) => props.onSelect?.(k)   // ✅ render 定义：依赖最新 props——闭包捕获当前值
+    return h('button', { onClick: onSelect }, '选')
+  }
+}
+```
+
+**规则**：回调只依赖 ctx / mount `let` / 稳定 handle → **mount 定义**（天然稳定，不重绑）；依赖最新 props / 派生数据 → **render 内定义**（闭包捕获最新值；引用变化导致事件重绑是**正确性要求**——必须读最新状态，框架不做稳定引用魔法）。
 
 ## 1. 有状态组件
 
 ```tsx
-const Toggle: Component = (_init, ctx) => {
-  const $ = ctx.ui.$()        // 深度 Proxy：赋值自动触发渲染（微任务批量）
-  $.on = false
+const Toggle: Component = async (_init, ctx) => {
+  let on = false        // 普通对象状态（render-only：无 $ Proxy）
 
-  return (props) => h('button', {
+  return async (props) => h('button', {
     class: 'my-toggle',
-    onClick: () => $.on = !$.on,
-  }, $.on ? '开' : '关')
+    onClick: () => { on = !on; ctx.ui.render() },   // 改状态后显式 render()
+  }, on ? '开' : '关')
 }
 ```
 
 | 状态类型 | 存放位置 | 触发渲染 |
 |---------|---------|---------|
-| 自动 UI 状态 | `$.xxx` | 赋值自动（微任务） |
-| 手动 UI 状态 | 闭包 `let` | 需 `ctx.ui.render()` |
+| 组件内部状态 | 闭包 `let` | 改后调 `ctx.ui.render()` |
+| 共享状态 | `createStore` + `ctx.ui.useExternal()` | store 变更自动 |
 | 内部缓存 | 闭包 `let` | 不触发 |
 
 ## 2. 带弹层的组件（最高频的自定义场景）
@@ -45,23 +65,22 @@ const Toggle: Component = (_init, ctx) => {
 用 `ctx.ui.usePopup`——一个组合器收敛 open 状态 + 触发（hover→tap 降级/longpress）+ Escape + 外部点击 + 定位/视口 clamp + portal：
 
 ```tsx
-const MyPopover: Component<{ content: string }> = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.open = false
+const MyPopover: Component<{ content: string }> = async (_init, ctx) => {
+  let open = false
   let wrapEl: HTMLElement | null = null
   const wrapRef = (el: HTMLElement | null) => { wrapEl = el }
 
   const popup = ctx.ui.usePopup({
     trigger: 'hover',          // 触屏自动降级 tap（useHoverCapable 内部判定）
     el: () => wrapEl,          // 锚点
-    isOpen: () => $.open,
-    setOpen: (v) => { $.open = v },   // $ 赋值自动渲染
+    isOpen: () => open,
+    setOpen: (v) => { open = v; ctx.ui.render() },   // 改状态 + render
     width: 320,                // 自动 clamp 视口
     closeOnOutside: true,      // 外部点击关闭（默认）
     closeOnEscape: true,       // Escape 关闭（默认，document 级——portal 焦点也生效）
   })
 
-  return (props) =>
+  return async (props) =>
     h('span', { class: 'anchor', ref: wrapRef, ...popup.wrapProps },
       props.children,
       popup.portal(h('div', { class: 'wf-panel' }, props.content)),
@@ -73,54 +92,62 @@ const MyPopover: Component<{ content: string }> = (_init, ctx) => {
 
 ## 3. 对话框类组件（Modal 系）
 
-全屏对话框（焦点 trap + 滚动锁 + 退场动画）不在 usePopup 范围——用 **`ctx.ui.useDialog`** 组合器（Modal/Drawer 同款：退场状态机 + 滚动锁 + 焦点 trap + animationend 卸载）：
+全屏对话框（焦点 trap + 滚动锁 + 退场动画）是 usePopup 的**会话级模态模式**（`presence/trapFocus/lockScroll/positioning: 'none'`——Modal/Drawer 同款）：
 
 ```tsx
-import { createPortal } from 'weifuwu/ui-dom'
-
-const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx) => {
-  const dialog = ctx.ui.useDialog({ name: 'MyDialog' })   // mount 创建
-
-  return (props) => {
-    const phase = dialog.sync(!!props.open)                // render 同步 open
+const MyDialog: Component<{ open: boolean; onClose: () => void }> = async (_init, ctx) => {
+  let latestOpen = false
+  const popup = ctx.ui.usePopup({
+    presence: true,      // 退场状态机（open → exit → closed + animationend）
+    trapFocus: true,     // 焦点 trap（面板挂载锁定/卸载归还）
+    lockScroll: true,    // 滚动锁（打开锁 / 面板卸载释放）
+    positioning: 'none', // 组件自定义定位（.wf-modal inset:0 居中）
+    closeOnOutside: false, closeOnEscape: false, // 关闭语义组件自控
+    isOpen: () => latestOpen,
+    setOpen: () => {},
+  })                     // mount 创建
+
+  return async (props) => {
+    latestOpen = !!props.open
+    const phase = popup.sync!(latestOpen)                // render 同步 open
     if (phase === 'closed') return null
 
-    return createPortal(h('div', {
+    return popup.portal(h('div', {
       class: 'wf-overlay',
       onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() },
     }, h('div', {
       class: `wf-modal ${phase === 'exit' ? 'wf-modal--exit' : 'wf-modal--enter'}`,
-      ref: dialog.panelRef,                                // 焦点 trap 目标
       onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() },  // Escape 语义组件层
-    }, props.children)), document.body)
+    }, props.children)), 'modal')   // portalKey 语义化（#__wf_portal 容器标记）
   }
 }
 ```
 
-> `dialog.rootRef` 挂到 portal 根（lockScroll + animationend 退场监听）；`panelRef` 挂到面板（trapFocus）。
-> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/ui-dom` 导出（特殊场景组装用）。
+> **ref 接线**：`trapFocus`/`lockScroll`/presence 退场监听全部由 usePopup 内部接线到 portal 面板
+> （`portalPanelRef`——content 的 `ref` prop 会被转发调用）——组件层无需手挂 `rootRef`/`panelRef`。
+> 低层原语 `trapFocus`/`lockScroll` 已收编为 usePopup 内部实现（**不对外导出**——AGENTS.md §5.4）；
+> `animateOut` 仍从 `weifuwu/ui-dom` 导出（非弹窗动画场景用）。
 
 ## 4. AI 组件
 
 会话语义由 `ctx.ui.useChat` 提供（消息/流式/工具/审批/stop/retry 全封装），返回的 handle 与 `$` 同一容器：
 
 ```tsx
-const ChatPanel: Component = (_init, ctx) => {
-  const $ = ctx.ui.useChat({
+const ChatPanel: Component = async (_init, ctx) => {
+  const chat = ctx.ui.useChat({
     url: '/api/chat',
     approveUrl: '/api/approve',   // HITL 审批上行（缺省 approve() 只清卡片）
     body: (messages) => ({ messages, mode: 'agent' }),
   })
 
   return () => h('div', { class: 'chat' },
-    $.messages.map((m) => h('div', { class: `msg-${m.role}` }, m.content)),
-    h('input', { value: $.input, onInput: (e: any) => $.input = e.target.value }),
-    h('button', { onClick: () => $.send() }, $.streaming ? '…' : '发送'),
+    h(AiChat, { chat }),                    // 标准界面：输入/消息/流式/工具卡全内置
+    h('button', { onClick: () => chat.send() }, chat.streaming ? '…' : '发送'),
   )
 }
 ```
 
-**共享 `$` 给子组件**（如 `<AiChat chat={$} />`）：父组件 dirty 不驱动子组件（三态 skip），子组件 mount 期 `initProps.chat.__watch?.(() => ctx.ui.dirty())` 自订阅。
+**共享 handle 给子组件**（如 `<AiChat chat={chat} />`）：会话 handle 带 `subscribe(cb)`——子组件 mount 期 `ctx.ui.useExternal(initProps.chat)` 自订阅（AiChat 已内置），会话状态变化自动重渲染订阅组件。
 
 ## 5. 异步组件（数据声明在工厂层）
 
@@ -129,29 +156,27 @@ const ChatPanel: Component = (_init, ctx) => {
 ```tsx
 const UserCard = async (initProps, ctx) => {
   const user = await ctx.data.get(`/api/user/${initProps.userId}`)  // 三场景：SSR→__DATA__ / hydration 种子 / SPA fetch
-  const $ = ctx.ui.$()
-  $.liked = false
-  return (props) => h('div', {}, user.name, h('button', { onClick: () => $.liked = !$.liked }))
+  let liked = false
+  return async (props) => h('div', {}, user.name, h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }))
 }
 ```
 
-- 渲染器按「返回值是 Promise」判别：客户端未 resolve → 占位（`Placeholder`），resolve 后整树补全；SSR 直接 await（无占位）
+- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；运行时首次挂载的 async 组件在 buildVNode 阶段 await（无占位/补全回调）；SSR 直接 await
 - 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
-- 占位显示：无边界 → null；`<Suspense fallback={...}>` → 占位处显示 fallback（可选）
-- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
+- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `let` + fetch + `render()`
 
 ## 6. 类型纪律（编译期防线）
 
 ```tsx
-const Badge: Component<{ variant: 'primary' | 'muted' }> = () =>
-  (props) => h('span', { class: `badge-${props.variant}` }, props.children)
+const Badge: Component<{ variant: 'primary' | 'muted' }> = async () =>
+  async (props) => h('span', { class: `badge-${props.variant}` }, props.children)
 
 // 负例：variant 传错 → tsc 报错（@ts-expect-error 是类型流测试的写法）
 // @ts-expect-error variant 不允许 'bogus'
 const bad: { variant: 'primary' | 'muted' } = { variant: 'bogus' }
 
 // ctx 注入声明（C 泛型）：声明了才能用，未声明编译期报错
-const Page: Component<{}, { api: ApiInjected['api'] }> = (_init, ctx) => {
+const Page: Component<{}, { api: ApiInjected['api'] }> = async (_init, ctx) => {
   ctx.api.get('/x')
   return () => null
 }
@@ -167,17 +192,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)`
 
@@ -186,8 +217,8 @@ const vnode = renderVNode(Toggle, {}, ctx)
 新受控组件**必须**用 `ctx.ui.useControlled`（受控判定 + 缺回调 warn 一次 + 非受控内部状态跨渲染保持）：
 
 ```tsx
-const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = (_init, ctx) => {
-  return (props) => {
+const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = async (_init, ctx) => {
+  return async (props) => {
     const ctrl = ctx.ui.useControlled<boolean>({ value: props.active, onChange: props.onChange, name: 'CollapseItem' })
     return h('button', {
       onClick: () => ctrl.setValue(!(ctrl.value ?? false)),   // 受控走 onChange；非受控内部状态
@@ -215,10 +246,10 @@ const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => voi
 > SSR 安全（shim 安全默认）+ 测试 mock 单点 + 环境差异隔离。
 
 ```tsx
-const MyComp: Component = (_init, ctx) => {
+const MyComp: Component = async (_init, ctx) => {
   // mount 层取 browser（ctx.browser 优先，测试/无注入环境 fallback jsdom）
   const browser = ctx.browser ?? createClientBrowser()
-  return (props) =>
+  return async (props) =>
     h('button', {
       onClick: () => {
         // 复制/查询/存储/滚动——全部经 browser
@@ -260,9 +291,8 @@ const MyComp: Component = (_init, ctx) => {
 
 ## 已知边界（诚实裁剪）
 
-- `usePopup` 覆盖浮层（Tooltip/Popover/Dropdown/Mentions/Cascader/ContextMenu）；**全屏对话框**（Modal/Drawer）用 useDialog（Escape 语义留组件层）；Command/Img preview 保持独立实现
+- `usePopup` 是**统一弹窗能力层**：锚定浮层（Tooltip/Popover/Dropdown/Select/AutoComplete/Mentions/Cascader/ContextMenu/NavMenu/Popconfirm/TreeSelect）+ 会话级模态（Modal/Drawer/Confirm——presence/trapFocus/lockScroll/positioning 'none'，Escape 语义留组件层）+ mask 模式（Command/Img preview/Tour——mask/maskCentered/自定义 mask VNode）+ focus 触发（DatePicker）+ positioning 'none' 常驻容器（Toast/Notification）——**全部弹窗单一入口**
 - **事件监听纪律**：组件库内部浏览器事件监听**统一走 `ctx.ui.useXXX`**——滚动/观察/弹层/对话框/快捷键/拖拽/DnD 全覆盖：
-  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（ContextMenu 自由定位）、`useDialog`（Modal/Drawer）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
-- 唯一保留：**DatePicker 元素级 `animationend`**（入场动画完成后坐标 settle——与 usePopup panelRef/motion.animateOut 同款框架基础设施，非浏览器全局事件）
-- **Select/DatePicker** 是 inline/absolute 菜单（自适宽），不迁移 usePopup——菜单直接挂在锚点下
+  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（弹窗统一——ContextMenu 自由定位 + Modal/Drawer 模态模式 + mask 遮罩）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
+- **唯一保留 usePopupPosition 独立使用**：Affix / Chart（坐标工具——非弹窗组合器，滚动跟随自动）
 - `createReactiveState` 已导出：组件外建全局 store（`createReactiveState(() => {})` + `$.__watch(cb)` 订阅）

package/docs/examples.md

@@ -5,12 +5,11 @@
 ## 登录表单
 
 ```tsx
-const LoginPage = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.errors = {}
-  $.submitting = false
+const LoginPage = async (_init, ctx) => {
+  let errors: Record<string, string> = {}
+  let submitting = false
 
-  return (props) =>
+  return async (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)' } },
@@ -21,17 +20,19 @@ const LoginPage = (_init, ctx) => {
               password: [{ required: true, minLength: 6, message: '密码至少6位' }],
             },
             onSubmit: async (values) => {
-              $.submitting = true
+              submitting = true
+              ctx.ui.render()
               await ctx.api?.post('/login', values)   // api 客户端由中间件注入 ctx.api
-              $.submitting = false
+              submitting = false
+              ctx.ui.render()
             },
-            onError: (errors) => { $.errors = errors },
+            onError: (errs) => { errors = errs; ctx.ui.render() },
           }, [
-            h(Field, { label: '邮箱', error: $.errors.email },
+            h(Field, { label: '邮箱', error: errors.email },
               h(Input, { name: 'email', type: 'email', placeholder: 'name@example.com' })),
-            h(Field, { label: '密码', error: $.errors.password },
+            h(Field, { label: '密码', error: errors.password },
               h(Input, { name: 'password', type: 'password' })),
-            h(Button, { type: 'submit', loading: $.submitting, block: true }, '登录'),
+            h(Button, { type: 'submit', loading: submitting, block: true }, '登录'),
           ])
         )
       )
@@ -42,20 +43,19 @@ const LoginPage = (_init, ctx) => {
 ## 数据列表 + 搜索
 
 ```tsx
-const UserList = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.keyword = ''
-  $.sortKey = 'name'
-  $.sortOrder = 'asc'
+const UserList = async (_init, ctx) => {
+  let keyword = ''
+  let sortKey = 'name'
+  let 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）
+  return async (props) => {
+    // 派生数据必须在 render 内计算（每次 render 读最新 keyword）
     const filtered = users.filter(u =>
-      !$.keyword || u.name.includes($.keyword) || u.email.includes($.keyword)
+      !keyword || u.name.includes(keyword) || u.email.includes(keyword)
     )
 
     return h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
@@ -85,39 +85,33 @@ const UserList = (_init, ctx) => {
 ## 消息提示
 
 ```tsx
-// 在任意组件中调用
-let toastId = 0
+// 官方推荐：命令式中间件（app.use(toast()) → ctx.toast('消息', 'success')）
+app.use(toast())
+// 任意组件：ctx.toast?.('操作成功', 'success')
 
-function showToast(ctx: WfuiContext, type: ToastType, message: string) {
-  // 通过 ctx 管理 Toast 列表
-  const $ = ctx.ui.$()
-  $.toasts = $.toasts ?? []
-  const id = String(++toastId)
-  $.toasts = [...$.toasts, { id, type, message }]
+// 自管理列表（render-only：let + render()）
+let toasts: { id: string; type: string; message: string }[] = []
+let toastId = 0
 
-  // 自动消失
+function showToast(ctx: WfuiContext, type: string, message: string) {
+  toasts = [...toasts, { id: String(++toastId), type, message }]
+  ctx.ui.render()
   if (type !== 'error') {
-    setTimeout(() => {
-      $.toasts = $.toasts.filter((t: any) => t.id !== id)
-    }, 3000)
+    setTimeout(() => { toasts = toasts.filter((t: any) => t.id !== String(toastId)); ctx.ui.render() }, 3000)
   }
 }
 
 // 页面中使用
-const App = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.toasts = []
-
-  return (props) =>
+const App = async (_init, ctx) => {
+  toasts = []
+  return async (props) =>
     h('div', {}, [
-      h(Button, {
-        onClick: () => showToast(ctx, 'success', '操作成功'),
-      }, '显示提示'),
+      h(Button, { onClick: () => showToast(ctx, 'success', '操作成功') }, '显示提示'),
       h(Toast, {
-        toasts: $.toasts,
+        toasts,
         position: 'top-right',
         max: 3,
-        onRemove: (id) => { $.toasts = $.toasts.filter((t: any) => t.id !== id) },
+        onRemove: (id) => { toasts = toasts.filter((t: any) => t.id !== id); ctx.ui.render() },
       }),
     ])
 }

package/docs/frontend-middleware.md

@@ -24,8 +24,7 @@ uiServe(app, { root: '#root' })     // 客户端落地（hydrate: true 收养 SS
 
 ```tsx
 const DashboardLayout: UIMiddleware = async (_loc, ctx, children) => {
-  const $ = ctx.ui.$()
-  $.open = true
+  let open = true
   return async (loc, c) => {
     const child = await children(loc, c)   // 子路由/嵌套路由内容
     return h('div', { class: 'wf-row' },
@@ -132,8 +131,8 @@ app.use(auth())
 uiServe(app, { root: '#root' })
 
 // 在组件中
-function Profile(_props: {}, ctx: WfuiContext) {
-  return (props) => {
+async function Profile(_props: {}, ctx: WfuiContext) {
+  return async (props) => {
     if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
     return <p>欢迎, {ctx.auth?.user?.name}</p>
   }