weifuwu 0.75.0 → 0.77.0

package/README.md

@@ -1,6 +1,6 @@
 # weifuwu
 
-**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 109 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
+**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 113 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
 
 ```bash
 npm install weifuwu      # 一个依赖，完整应用栈
@@ -24,16 +24,16 @@ npm install weifuwu      # 一个依赖，完整应用栈
 |----|------|------|
 | 后端 | `weifuwu` | Trie 路由 / 中间件链 / serve / 自研 PG+Redis / SSR / GraphQL / WebSocket |
 | 前端 | `weifuwu/ui-dom` | **UIRouter（纯路由 + ctx 注入链）+ uiServe（渲染运行时）+ SSR/hydration**——handler=异步组件 / 中间件两阶段 / ctx.params 对齐后端；**weifuwu/components 直接复用**（VNode 契约唯一来源 ui-dom，见 `docs/frontend-ui-dom.md`） |
-| 组件 | `weifuwu/components` | 109 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
-| 样式 | `weifuwu/layout` | 57 布局原语 + 136 工具类 + 167 主题 Token，零自定义 CSS 文件 |
+| 组件 | `weifuwu/components` | 113 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
+| 样式 | `weifuwu/layout` | 58 布局原语 + 136 工具类 + 167 主题 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`（渲染引擎，26 方法）：
->   - 渲染：`$()`（响应式状态）/ `render()` / `dirty()` / `selfId()`（跨组件刷新）
->   - 状态：`useControlled()`（受控/非受控）/ `useStableRef()`（稳定 ref）
->   - 弹层：`usePopup()`（组合器）/ `useDialog()`（对话框）/ `usePopupPosition()`（定位）
+> - **前端** `ctx.ui`（渲染引擎，20+ hooks）：
+>   - 渲染：`render()`（唯一触发——render-only）/ `selfId()`（跨组件精准刷新）
+>   - 状态：`useControlled()`（受控/非受控）/ `useStableRef()`（稳定 ref）/ `useExternal()`（共享状态订阅）
+>   - 弹层：`usePopup()`（统一能力层——锚定浮层 + 会话级模态）/ `usePopupPosition()`（定位）
 >   - 事件：`useInView()` / `useScrollPosition()` / `useMedia()` / `useBreakpoint()` / `useGlobalKey()` / `useDrag()` / `useDragDrop()` / `useHoverCapable()` / `useLongPress()` / `useVisualViewport()`
 >   - 动画：`useAnimationEnd()`（完成回调）/ `usePresence()`（显隐状态机）/ `useTween()`（数值补间）/ `useReducedMotion()`（偏好感知）
 >   - AI/数据：`useChat()`（AI 会话）/ `useAsync()`（异步取数）
@@ -89,13 +89,13 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 作为运行时依赖随 `npm install weifuwu` 自动安装，`ctx.ui.js()` 开箱即用。
 
-**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
+**两阶段组件模型** — 组件 = `async (initProps, ctx) => (props) => Promise<VNode>`。外层工厂只执行一次（mount，可 await 数据），内层 renderFn 每次状态/props 变化时执行（强制异步）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
 
-**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch；也支持手动 `ctx.ui.render()` 精确控制渲染时机。**组件库手动优先、业务层自动优先**——同一框架内按角色选模式（详见[组件库](docs/components.md)）。
+**render-only 确定性渲染** — 渲染唯一触发 `ctx.ui.render()`（闭包绑定组件），状态是普通对象（`let` + `render()`）；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。行为可静态推导，无隐式触发（详见[组件库](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` 读取。
 
-**async 工厂组件** — `async (ctx) => (initProps, ctx) => (props) => VNode`：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`$`）、render 输出视图。异步只在工厂边界，mount/render 保持同步；数据经闭包注入，写数据像写同步代码。三条纪律见[核心概念 · async 组件](#核心概念)。
+**async 工厂组件** — `async (initProps, ctx) => (props) => Promise<VNode>`（weifuwu **唯一组件形态**——同步组件已不支持）：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`let` + `render()`）、render 输出视图。异步在工厂边界与 renderFn，数据经闭包注入，写数据像写同步代码。三条纪律见[核心概念 · async 组件](#核心概念)。
 
 **SPA/SSR/Hydration 统一透明** — 同一份路由定义（`UIRouter`）一个组件三场景自动适配：后端 `ssrPage(router, { url })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `uiServe(router, { root, hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
 
@@ -109,7 +109,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
-> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（109 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
+> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（113 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
 
 ---
 
@@ -133,7 +133,7 @@ const app = new UIRouter()
 // async 组件（原生）：await 数据 → 返回视图（外层初始化，内层渲染）
 const Home = async (_init, ctx) => {
   const msg = await ctx.data.get('/api/hello')   // 数据管道：一个 API 三场景
-  return (props) => <h1>{msg.msg}</h1>
+  return async (props) => <h1>{msg.msg}</h1>
 }
 
 app.get('/', async () => <Home />)   // handler = 异步组件
@@ -225,7 +225,7 @@ uiServe(app, { root: '#root', hydrate: true })
 ### 30 秒体验（跑现有 demo）
 
 ```bash
-# ① 组件 cheatsheet——102 组件全部可交互预览（零依赖，5 秒起）
+# ① 组件 cheatsheet——113 组件全部可交互预览（零依赖，5 秒起）
 cd apps/components-demo && node server.ts
 # 打开 http://localhost:3000
 
@@ -275,25 +275,24 @@ cd apps/agent-platform && npm run seed && npm run dev
     import { UIRouter, uiServe, h } from 'weifuwu/ui-dom'
     import { Card, Button, Badge } from 'weifuwu/components'
 
-    // 组件 = (initProps, ctx) => (props) => VNode
-    const Counter = (_props, ctx) => {
-      const $ = ctx.ui.$()
-      $.count = 0 // mount 初始化
+    // 组件 = async (initProps, ctx) => (props) => Promise<VNode>（render-only：改状态后 ctx.ui.render()）
+    const Counter = async (_init, ctx) => {
+      let count = 0 // mount 初始化
 
       return () =>
         h(Card, { variant: 'default', padding: 'lg' },
           h('h2', { style: { textAlign: 'center', margin: 0 } }, '⚡ Weifuwu'),
           h('div', { style: { fontSize: '4rem', fontWeight: 600, textAlign: 'center' } },
-            String($.count)),
+            String(count)),
           h('div', { style: { textAlign: 'center', marginTop: '1rem' } },
             h(Badge, {
-              variant: $.count % 2 === 0 ? 'success' : 'warning'
-            }, $.count % 2 === 0 ? '偶数' : '奇数')),
+              variant: count % 2 === 0 ? 'success' : 'warning'
+            }, count % 2 === 0 ? '偶数' : '奇数')),
           h('hr', { style: { margin: '1rem 0', border: 'none', borderTop: '1px solid #eee' } }),
           h('div', { style: { display: 'flex', gap: '0.5rem', justifyContent: 'center' } },
-            h(Button, { variant: 'secondary', onClick: () => $.count-- }, '➖ 减 1'),
-            h(Button, { variant: 'danger', onClick: () => $.count = 0 }, '↺ 重置'),
-            h(Button, { variant: 'primary', onClick: () => $.count++ }, '➕ 加 1'),
+            h(Button, { variant: 'secondary', onClick: () => { count--; ctx.ui.render() } }, '➖ 减 1'),
+            h(Button, { variant: 'danger', onClick: () => { count = 0; ctx.ui.render() } }, '↺ 重置'),
+            h(Button, { variant: 'primary', onClick: () => { count++; ctx.ui.render() } }, '➕ 加 1'),
           ),
         )
     }
@@ -314,8 +313,8 @@ cd apps/agent-platform && npm run seed && npm run dev
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/ui-dom` | `https://unpkg.com/weifuwu@latest/dist/ui-dom/index.js` | 前端运行时（UIRouter, uiServe, h, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 109 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 167 个主题 Token + 57 个布局原语 + 136 个工具类 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 113 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 167 个主题 Token + 58 个布局原语 + 136 个工具类 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -356,9 +355,9 @@ cd apps/agent-platform && npm run seed && npm run dev
 | `weifuwu/ui-dom` | **i18n** | 国际化中间件（运行时切换语言） | — |
 | `weifuwu/ui-dom` | **ssrPage / serializeData** | 服务端渲染：SSR HTML + `__DATA__` 序列化（`ctx.params` 两端同源） | — |
 | `weifuwu/ui-dom` | **useChat / AiChat 原语** | AI 会话（流式/工具调用/HITL） | — |
-| `weifuwu/ui-dom` | **事件原语** | `usePopup` / `useDialog` / `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 [docs/mobile.md](docs/mobile.md)） | — |
-| `weifuwu/components` | **109 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
-| `weifuwu/layout` | **CSS 布局** | 57 个布局原语 + 136 个工具类 + 167 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/ui-dom` | **事件原语** | `usePopup`（统一弹窗能力层）/ `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 [docs/mobile.md](docs/mobile.md)） | — |
+| `weifuwu/components` | **113 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
+| `weifuwu/layout` | **CSS 布局** | 58 个布局原语 + 136 个工具类 + 167 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -380,8 +379,8 @@ cd apps/agent-platform && npm run seed && npm run dev
 | 后台任务/定时 | `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`（109 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
-| 布局/主题/暗色 | `weifuwu/layout`（57 原语 + 136 工具类 + 167 Token） | [docs/layout.md](docs/layout.md) |
+| 前端 UI 组件 | `weifuwu/components`（113 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
+| 布局/主题/暗色 | `weifuwu/layout`（58 原语 + 136 工具类 + 167 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) |
@@ -390,27 +389,25 @@ cd apps/agent-platform && npm run seed && npm run dev
 
 ## 核心概念
 
-### 三层形态（路由 / 同步组件 / async 组件）
+### 三层形态（路由 / 组件 / async 组件工厂）
 
 | 层 | 签名 | 异步 | 生命周期 |
 |----|------|------|---------|
 | **UIHandler**（路由） | `async (location, ctx) => VNode` | ✅ 整体 | 每次路由变化执行 |
-| **Component**（同步组件） | `(initProps, ctx) => (props) => VNode` | ❌ 同步 | mount 一次 + render 每次 |
-| **AsyncComponent**（async 组件） | `async (initProps, ctx) => (props) => VNode` | ✅ 只工厂 | 工厂按实例（diff 传递 `_asyncDef`，补全不重跑） |
+| **Component**（唯一形态） | `async (initProps, ctx) => (props) => Promise<VNode>` | ✅ 工厂 + renderFn | mount 一次 + render 每次；同步组件已不支持（类型强制 Promise） |
 
-异步只出现在两个边界——路由 handler（整页）和 async 组件工厂（数据声明）；**mount/render 永远同步**（SSR/hydration 两端一致性的根基）。async 组件与同步组件**同签名**（唯一差别是 `async` 关键字）——渲染器按「返回值 instanceof Promise」统一判别：未 resolve → `Placeholder` 占位（`<Suspense fallback>` 边界内显示 fallback），resolve 后整树重渲染补全。
+异步只在两个边界——路由 handler（整页）和组件工厂（数据声明）+ renderFn（强制异步）。渲染器按「返回值 instanceof Promise」统一判别：主路径 `buildVNode` async 预构建（await 全部工厂，兄弟并行）→ 原子落地（无占位、无补全回调）；运行时首次挂载的 async 组件同样在 buildVNode 阶段 await；骨架屏 `uiServe({ loading })` + `handle.ready`。
 ### 两阶段组件（新手必读：为什么是两层）
 
-组件 = `(initProps, ctx) => (props) => VNode`——**外层 = 初始化（只执行一次），内层 = 渲染（每次状态/props 变化时执行）**。类比：外层是对象的构造函数，内层是它的 render 方法。
+组件 = `async (initProps, ctx) => (props) => Promise<VNode>`——**外层 = 初始化（只执行一次，可 await 数据），内层 = 渲染（每次状态/props 变化时执行，强制异步）**。类比：外层是对象的构造函数，内层是它的 render 方法。
 
 ```tsx
-const Counter = (_init, ctx) => {
-  // 外层（mount）：只跑一次——初始化状态、订阅、定时器
-  const $ = ctx.ui.$()
-  $.count = 0
-  return (props) =>
-    // 内层（render）：每次变化执行——读状态输出视图
-    <button onClick={() => $.count++}>{$.count}</button>
+const Counter = async (_init, ctx) => {
+  // 外层（mount）：只跑一次——初始化状态、订阅、定时器（可 await 数据）
+  let count = 0
+  return async (props) =>
+    // 内层（render）：每次变化执行（强制异步）——读状态输出视图（render-only：改状态后显式 render()）
+    <button onClick={() => { count++; ctx.ui.render() }}>{count}</button>
 }
 ```
 
@@ -441,7 +438,7 @@ const Counter = (_init, ctx) => {
 |------|------|------|
 | 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
 | 读取 | handler 读取 ctx | 组件读取 ctx |
-| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` / `$.x = val` 触发局部 VDOM patch |
+| 渲染 | 返回 Response | `ctx.ui.render()` 触发局部 VDOM patch（render-only）；共享状态 `createStore` + `useExternal` |
 
 ### async 组件（三条纪律）
 
@@ -450,12 +447,11 @@ async 组件让"拿数据渲染页面"像写同步代码——签名与同步组
 ```tsx
 const UserProfile = async (_init, ctx) => {
   const user = await ctx.data.get(`/api/user/${ctx.params.id}`)   // ① 工厂层：声明数据（三场景自动）
-  const $ = ctx.ui.$()
-  $.liked = false                                                 // ② mount：客户端状态
-  return (props) =>
+  let liked = false                                                // ② mount：客户端状态（render-only）
+  return async (props) =>
     h('div', {},
       h('p', {}, user.name),          // 服务端状态（闭包，SSR 进 HTML）
-      h('button', { onClick: () => $.liked = !$.liked }, $.liked ? '❤️' : '🤍'))
+      h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }, liked ? '❤️' : '🤍'))
 }
 ```
 
@@ -464,14 +460,13 @@ const UserProfile = async (_init, ctx) => {
 | 纪律 | 反例 | 正确 |
 |---|---|---|
 | ① 数据 key 必须含维度 | `ctx.data.get('/api/user')`——`/users/1 → /users/2` 导航命中旧缓存 | `ctx.data.get(\`/api/user/${ctx.params.id}\`)` |
-| ② 会变的数据放 `$` | `const count = data.count`——点击永不更新 | `$.count = data.count`（初始值 seed 自服务端数据） |
-| ③ 初始状态必须确定性 | `$.w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
+| ② 会变的数据放组件状态 | `const count = data.count`——点击永不更新 | `let count = data.count` + 交互后 `ctx.ui.render()`（初始值 seed 自服务端数据） |
+| ③ 初始状态必须确定性 | `let w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
 
 **常见坑**：
 - 工厂按**实例**执行（N 处实例 = N 次工厂调用）——数据必须走 `ctx.data`（自带缓存 + 并发合并，重复执行零成本）；禁止副作用/昂贵操作裸写工厂
 - 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）
-- **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在 `$` + fetch
-- **占位显示**：async 组件未 resolve 时渲染 `Placeholder`——无边界显示 null；`<Suspense fallback={...}>` 边界内占位处显示 fallback（可选，子树内任意深度 async 组件共享）
+- **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在客户端 `let` + fetch + `render()`
 
 ### 渲染策略：SPA 还是 SSR？
 
@@ -514,8 +509,8 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 | [docs/frontend.md](docs/frontend.md) | 前端核心：应用引导（UIRouter+uiServe）/ 组件模型 / 异步组件 / 状态管理 / 条件与列表 / ref / 类型（weifuwu/client 已并入 ui-dom） |
 | [docs/frontend-ui-dom.md](docs/frontend-ui-dom.md) | **ui-dom**：UIRouter 纯路由 + uiServe 渲染运行时 + ctx 注入链 + components 复用 + SSR/hydration（前端唯一运行时——weifuwu/client 已删除） |
 | [docs/frontend-middleware.md](docs/frontend-middleware.md) | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
-| [docs/components.md](docs/components.md) | 组件库（109 个组件 + 使用示例 + 组件列表） |
-| [docs/layout.md](docs/layout.md) | 布局系统：57 个布局原语 + 136 个工具类 + 167 个主题 Token |
+| [docs/components.md](docs/components.md) | 组件库（113 个组件 + 使用示例 + 组件列表） |
+| [docs/layout.md](docs/layout.md) | 布局系统：58 个布局原语 + 136 个工具类 + 167 个主题 Token |
 | [docs/styling.md](docs/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
 
 ### 通用

package/dist/ai/types.d.ts

@@ -22,6 +22,8 @@ export interface WfUsage {
 export interface WfDone {
     content: string;
     usage?: WfUsage;
+    /** thinking 模式的推理过程（reasoning_content），收尾时一次性下发（v1 不进流式） */
+    reasoning?: string;
 }
 export type WfErrorCode = 'auth_failed' | 'rate_limited' | 'context_length' | 'timeout' | 'provider_error' | 'invalid_request' | 'unsupported' | 'aborted';
 export interface WfError {

package/dist/components/AiChat/AiChat.d.ts

@@ -20,7 +20,8 @@
  */
 import type { Component } from '../../ui-dom/vnode.ts';
 import type { UseChatHandle, UiMessage } from '../../ui-dom/use-chat.ts';
-import type { WfError, WfUsage } from '../../ai/types.ts';
+import type { WfError, WfUsage, WfApprovalRequest } from '../../ai/types.ts';
+import type { JsonSchema } from '../JsonSchemaForm/JsonSchemaForm.ts';
 export interface AiChatLabels {
     send: string;
     stop: string;
@@ -43,6 +44,9 @@ export interface AiChatProps {
     renderMessage?: (msg: UiMessage) => any;
     /** 工具参数渲染（透传 ToolCallCard） */
     renderToolArgs?: (args: Record<string, unknown>) => any;
+    /** 审批修改参数：按审批请求返回工具参数 schema（返回 undefined 则审批卡无修改入口；
+     *  提交修改后参数 → chat.approve('modified', …)——后端按 modifiedArgs 执行） */
+    approveSchema?: (request: WfApprovalRequest) => JsonSchema | undefined;
     /** 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） */
     raiseOnKeyboard?: boolean;
 }

package/dist/components/ApprovalCard/ApprovalCard.d.ts

@@ -1,4 +1,5 @@
 import type { Component } from '../../ui-dom/vnode.ts';
+import { type JsonSchema } from '../JsonSchemaForm/JsonSchemaForm.ts';
 import type { WfApprovalRequest } from '../../ai/types.ts';
 /**
  * ApprovalCard — 人工审批卡片（wf: 协议 §4.5 交互原语）
@@ -20,13 +21,15 @@ export interface ApprovalCardProps {
     request: WfApprovalRequest;
     /** 卡片状态（默认 pending） */
     status?: ApprovalStatus;
-    /** 用户点"允许" */
-    onApprove?: () => void;
+    /** 用户点"允许"（modified 决策时带修改后参数——父层据此选 decision） */
+    onApprove?: (modifiedArgs?: Record<string, unknown>) => void;
     /** 用户点"拒绝"，note 为可选备注（进 agent 上下文） */
     onReject?: (note?: string) => void;
     /** 自定义详情渲染（默认显示 name + args） */
     renderDetail?: (request: WfApprovalRequest) => any;
     /** 提交中（按钮禁用 + 文案反馈，防连点） */
     loading?: boolean;
+    /** 工具参数 schema——提供时渲染「修改参数」入口（JsonSchemaForm，预填 request.args），提交带修改后参数 */
+    argsSchema?: JsonSchema;
 }
 export declare const ApprovalCard: Component<ApprovalCardProps>;

package/dist/components/CitationCard/CitationCard.d.ts

@@ -0,0 +1,38 @@
+import type { Component } from '../../ui-dom/vnode.ts';
+import type { WfuiContext } from '../../ui-dom/types.ts';
+/**
+ * CitationCard — RAG 检索引用展示（AI 差异化）
+ *
+ * AI 回复的引用来源列表：折叠「引用 N 条」头部 + 展开条目列表
+ * （序号 + 标题 + 来源 + 片段 + 可选链接）。手动优先（let + render()）。
+ *
+ * ```tsx
+ * <CitationCard
+ *   items={[{ id, title, source, snippet, url? }]}
+ *   maxVisible={3}
+ *   onOpen={(c) => openDoc(c.id)}
+ * />
+ * ```
+ */
+export interface Citation {
+    id: string;
+    title: string;
+    /** 来源元信息（文档路径/域名等） */
+    source?: string;
+    /** 原文片段（裁剪：不做全文展开——片段即展示） */
+    snippet: string;
+    /** 可点击链接（无 onOpen 时新窗口打开） */
+    url?: string;
+}
+export interface CitationCardProps {
+    items: Citation[];
+    /** 折叠头文案（默认「引用来源」） */
+    label?: string;
+    /** 折叠时最多显示条数（默认 3；溢出显示 +N 汇总条目） */
+    maxVisible?: number;
+    /** 初始展开（默认折叠） */
+    defaultExpanded?: boolean;
+    /** 点击条目回调（提供时不渲染链接，由调用方处理跳转/打开） */
+    onOpen?: (citation: Citation) => void;
+}
+export declare const CitationCard: Component<CitationCardProps, WfuiContext>;

package/dist/components/Command/Command.d.ts

@@ -18,5 +18,5 @@ export interface CommandProps {
     /** 全局快捷键，如 'mod+k'（cmd/ctrl + k）；null 关闭全局监听 */
     globalShortcut?: string | null;
 }
-/** 命令面板（对应 shadcn Command）：全屏 overlay + 搜索 + 键盘流（↑↓ Enter Escape）+ Cmd+K 全局快捷键 */
+/** 命令面板（对应 shadcn Command）：usePopup mask 全屏遮罩 + 搜索 + 键盘流（↑↓ Enter Escape）+ Cmd+K 全局快捷键 */
 export declare const Command: Component<CommandProps>;

package/dist/components/DatePicker/DatePicker.d.ts

@@ -2,7 +2,7 @@
  * weifuwu/components — DatePicker
  *
  * 四合一日期选择器，支持 mode: date | datetime | time | range
- * 使用 createPortal + position:fixed 定位弹出层。
+ * 统一 usePopup：focus 触发 + mask 遮罩 + 自由定位（left 对齐 + width 跟随 trigger）。
  *
  * 状态管理：闭包变量 + ctx.ui.render()
  */

package/dist/components/JsonSchemaForm/JsonSchemaForm.d.ts

@@ -0,0 +1,48 @@
+import type { Component } from '../../ui-dom/vnode.ts';
+import type { WfuiContext } from '../../ui-dom/types.ts';
+/**
+ * JsonSchemaForm — JSON Schema（对象子集）→ 参数输入表单（零依赖）
+ *
+ * AI 场景参数输入面：工具调用参数（ToolCallCard 只展示，本组件负责输入）、
+ * 审批 modified 决策的取参来源、Agent 配置页 schema 驱动表单。
+ *
+ * 类型映射：string→Input / number|integer→InputNumber / boolean→Switch /
+ * string+enum→Select / object→嵌套折叠区（递归）/ array→列表 + 添加/删除。
+ *
+ * 值管理：内部 state（非受控），`value` 仅作初始值——输入回流来自内部，
+ * 无受控回流焦点问题（§5.3）；`onChange` 每次编辑通知（不回流控制）。
+ * 校验（submit 时）：required / enum / min-max / minLength-maxLength，
+ * 错误展示在字段 error，不触发 onSubmit。
+ *
+ * ```tsx
+ * <JsonSchemaForm schema={tool.parameters} value={args} onSubmit={run} submitLabel="执行" />
+ * ```
+ */
+export interface JsonSchema {
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    enum?: (string | number)[];
+    items?: JsonSchema;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    /** 不支持的 schema 关键字（$ref 等）——诚实裁剪：告警 + 降级文本输入 */
+    $ref?: string;
+}
+export interface JsonSchemaFormProps {
+    /** 顶层对象 schema（type: 'object' + properties） */
+    schema: JsonSchema;
+    /** 初始值（非受控语义）；内部状态由编辑驱动 */
+    value?: Record<string, any>;
+    /** 每次编辑通知（父层可读最新值；不回流控制） */
+    onChange?: (values: Record<string, any>) => void;
+    /** 提交（校验通过才触发）；不传则不渲染提交按钮 */
+    onSubmit?: (values: Record<string, any>) => void;
+    submitLabel?: string;
+}
+export declare const JsonSchemaForm: Component<JsonSchemaFormProps, WfuiContext>;

package/dist/components/ReasoningBlock/ReasoningBlock.d.ts

@@ -0,0 +1,25 @@
+import type { Component } from '../../ui-dom/vnode.ts';
+import type { WfuiContext } from '../../ui-dom/types.ts';
+/**
+ * ReasoningBlock — CoT 推理过程折叠展示（AI 差异化）
+ *
+ * DeepSeek thinking 模式的 reasoning_content 展示层：折叠「已思考」头部，
+ * 点击展开推理文本。流式（streaming）时头部带脉冲指示。
+ *
+ * 手动优先（组件库纪律）：let expanded + render()，无 $。
+ *
+ * ```tsx
+ * <ReasoningBlock content={m.reasoning} streaming={m.status === 'streaming'} />
+ * ```
+ */
+export interface ReasoningBlockProps {
+    /** 推理文本（reasoning_content） */
+    content: string;
+    /** 初始展开（默认折叠） */
+    defaultExpanded?: boolean;
+    /** 折叠头部文案（默认「已思考」） */
+    label?: string;
+    /** 流式中（头部脉冲指示） */
+    streaming?: boolean;
+}
+export declare const ReasoningBlock: Component<ReasoningBlockProps, WfuiContext>;

package/dist/components/Select/Select.d.ts

@@ -4,10 +4,20 @@ export interface SelectOption {
     label: string;
     disabled?: boolean;
 }
+/** 选项组（optgroup）：label + 组内选项 */
+export interface SelectOptionGroup {
+    label: string;
+    options: SelectOption[];
+}
+/** 选项列表：平铺项与分组可混用 */
+export type SelectOptions = (SelectOption | SelectOptionGroup)[];
+export declare function isOptionGroup(o: SelectOption | SelectOptionGroup): o is SelectOptionGroup;
+/** 展平（键盘索引 / 选中查找用）；保持顺序 */
+export declare function flattenOptions(opts: SelectOptions | undefined): SelectOption[];
 export interface SelectProps {
     label?: string;
     value?: string | string[];
-    options?: SelectOption[];
+    options?: SelectOptions;
     placeholder?: string;
     required?: boolean;
     disabled?: boolean;

package/dist/components/SessionList/SessionList.d.ts

@@ -0,0 +1,42 @@
+import type { Component } from '../../ui-dom/vnode.ts';
+import type { WfuiContext } from '../../ui-dom/types.ts';
+/**
+ * SessionList — 侧栏会话管理列表（AI 差异化）
+ *
+ * 会话分组（今天/昨天/更早）+ 选中高亮 + 搜索过滤 + 重命名/删除/新建。
+ * 手动优先（let + render()）：
+ *   - 重命名：行内编辑按钮 → 输入框（预填原标题）→ Enter 确认 / Escape 取消
+ *   - 删除：悬停行内删除按钮（裁剪：不做右键菜单）
+ *   - 键盘：方向键移动焦点 + Enter 激活（列表容器 onKeyDown）
+ *
+ * ```tsx
+ * <SessionList sessions={sessions} activeId={cur} onSelect={setCur}
+ *   onNew={createSession} onRename={renameSession} onDelete={deleteSession} searchable />
+ * ```
+ */
+export interface Session {
+    id: string;
+    title: string;
+    /** 更新时间戳（ms）——分组（今天/昨天/更早）；缺省进「更早」 */
+    updatedAt?: number;
+}
+export interface SessionListProps {
+    sessions: Session[];
+    /** 当前选中会话 id（高亮 + aria-selected） */
+    activeId?: string;
+    /** 点击会话（键盘 Enter 同） */
+    onSelect?: (id: string) => void;
+    /** 新建按钮（渲染条件：onNew 提供） */
+    onNew?: () => void;
+    /** 重命名（行内编辑 Enter 确认） */
+    onRename?: (id: string, title: string) => void;
+    /** 删除（行内悬停按钮） */
+    onDelete?: (id: string) => void;
+    /** 顶部搜索框（按标题过滤） */
+    searchable?: boolean;
+    /** 新建按钮文案（默认「新建会话」） */
+    newLabel?: string;
+}
+/** 分组标签：今天 / 昨天 / 更早（确定性：now 可注入） */
+export declare function groupKey(t: number, now?: number): 'today' | 'yesterday' | 'earlier';
+export declare const SessionList: Component<SessionListProps, WfuiContext>;

package/dist/components/Tour/Tour.d.ts

@@ -25,7 +25,7 @@ export interface TourProps {
 }
 /**
  * Tour — 新手引导（步骤式）。
- * 目标 rect 定位（usePopupPosition 跟随 scroll/resize）+ Portal 遮罩 + 步骤气泡。
+ * 统一 usePopup：mask 遮罩 + portal 出口；position 回调更新目标 rect（scroll 跟随）。
  *
  * 状态纪律：
  * - 步骤索引闭包 let + render()（手动模式——避免 $ 内置类型问题）

package/dist/components/TreeSelect/TreeSelect.d.ts

@@ -16,8 +16,9 @@ export interface TreeSelectProps {
 export declare function findLabel(nodes: TreeNode[], key: string): string | undefined;
 /**
  * TreeSelect — 树形选择（Tree + 下拉组合）。
- * 下拉经 createPortal + position:fixed（usePopupPosition 定位/跟随/夹紧）——
- * 与 DatePicker 同模式：父容器 overflow/transform 不影响弹出层。
+ * 弹层经 ctx.ui.usePopup（§5.4 弹窗纪律统一组合器）：portal 到 #__wf_portal +
+ * fixed 定位/视口夹紧 + 外部点击关闭 + Escape 关闭 + ref 稳定——不再手写
+ * usePopupPosition/createPortal/panelRef（此前缺外部点击关闭的真实 bug）。
  * 单选 selectedKeys / 多选 checkable checkedKeys（父子联动）。
  * 受控纪律：value 受控无 onChange → warn。
  */

package/dist/components/index.d.ts

@@ -13,8 +13,8 @@ export { Input } from './Input/Input.ts';
 export type { InputProps } from './Input/Input.ts';
 export { Textarea } from './Textarea/Textarea.ts';
 export type { TextareaProps } from './Textarea/Textarea.ts';
-export { Select } from './Select/Select.ts';
-export type { SelectProps, SelectOption } from './Select/Select.ts';
+export { Select, flattenOptions } from './Select/Select.ts';
+export type { SelectProps, SelectOption, SelectOptionGroup, SelectOptions } from './Select/Select.ts';
 export { Checkbox } from './Checkbox/Checkbox.ts';
 export type { CheckboxProps } from './Checkbox/Checkbox.ts';
 export { Switch } from './Switch/Switch.ts';
@@ -223,3 +223,11 @@ export { Scrollbar } from './Scrollbar/Scrollbar.ts';
 export type { ScrollbarProps } from './Scrollbar/Scrollbar.ts';
 export { AlertGroup } from './AlertGroup/AlertGroup.ts';
 export type { AlertGroupProps, AlertGroupItem } from './AlertGroup/AlertGroup.ts';
+export { JsonSchemaForm } from './JsonSchemaForm/JsonSchemaForm.ts';
+export type { JsonSchemaFormProps, JsonSchema } from './JsonSchemaForm/JsonSchemaForm.ts';
+export { ReasoningBlock } from './ReasoningBlock/ReasoningBlock.ts';
+export type { ReasoningBlockProps } from './ReasoningBlock/ReasoningBlock.ts';
+export { CitationCard } from './CitationCard/CitationCard.ts';
+export type { CitationCardProps, Citation } from './CitationCard/CitationCard.ts';
+export { SessionList, groupKey } from './SessionList/SessionList.ts';
+export type { SessionListProps, Session } from './SessionList/SessionList.ts';