weifuwu 0.74.0 → 0.76.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,8 +24,8 @@ 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`，但用途完全不同**
@@ -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）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
 
 ---
 
@@ -191,7 +191,7 @@ router.use(ui())
 // → 完整 HTML + __DATA__ + bundle/styles 引用（无需手写页面 handler）
 router.get('*', async (req, ctx) => {
   const { page } = await ssrPage(app, { url: req.url ?? '/' })
-  return ctx.ui.html(page)
+  return ctx.ui.html.unsafe(page)   // page 是完整 HTML（ssrPage 已序列化 __DATA__）——unsafe 防二次转义
 })
 
 router.get('/static/app.js', (req, ctx) => ctx.ui.js('./src/client.ts'))
@@ -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
 
@@ -314,8 +314,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` | 102 个 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 |
 
 
@@ -358,7 +358,7 @@ cd apps/agent-platform && npm run seed && npm run dev
 | `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` | **113 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
-| `weifuwu/layout` | **CSS 布局** | 57 个布局原语 + 136 个工具类 + 167 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/layout` | **CSS 布局** | 58 个布局原语 + 136 个工具类 + 167 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -380,7 +380,7 @@ 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`（102 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
+| 前端 UI 组件 | `weifuwu/components`（113 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
 | 布局/主题/暗色 | `weifuwu/layout`（57 原语 + 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) |
@@ -390,16 +390,15 @@ cd apps/agent-platform && npm run seed && npm run dev
 
 ## 核心概念
 
-### 三层形态（路由 / 组件 / 异步工厂）
+### 三层形态（路由 / 同步组件 / async 组件）
 
 | 层 | 签名 | 异步 | 生命周期 |
 |----|------|------|---------|
 | **UIHandler**（路由） | `async (location, ctx) => VNode` | ✅ 整体 | 每次路由变化执行 |
-| **Component**（组件） | `(initProps, ctx) => (props) => VNode` | ❌ 同步 | mount 一次 + render 每次 |
-| **AsyncFactory**（异步组件） | `async (ctx) => (initProps, ctx) => (props) => VNode` | ✅ 只工厂 | 工厂一次（WeakMap 缓存） |
-
-异步只出现在两个边界——路由 handler（整页）和组件工厂（数据声明）；**mount/render 永远同步**（SSR/hydration 两端一致性的根基）。`async (initProps, ctx) => ...` 是混合错形——渲染器不 await 同步组件，Promise 会被当 render 函数调用。
+| **Component**（同步组件） | `(initProps, ctx) => (props) => VNode` | ❌ 同步 | mount 一次 + render 每次 |
+| **AsyncComponent**（async 组件） | `async (initProps, ctx) => (props) => VNode` | ✅ 只工厂 | 工厂按实例（diff 传递 `_asyncDef`，补全不重跑） |
 
+异步只出现在两个边界——路由 handler（整页）和 async 组件工厂（数据声明）；async 组件与同步组件**同签名**（唯一差别是 `async` 关键字）。渲染器按「返回值 instanceof Promise」统一判别：主路径 `buildVNode` async 预构建（await 全部工厂，兄弟并行）→ 落地零占位；动态挂载兑底占位 + 局部补全；骨架屏 `uiServe({ loading })` + `handle.ready`。
 ### 两阶段组件（新手必读：为什么是两层）
 
 组件 = `(initProps, ctx) => (props) => VNode`——**外层 = 初始化（只执行一次），内层 = 渲染（每次状态/props 变化时执行）**。类比：外层是对象的构造函数，内层是它的 render 方法。
@@ -446,7 +445,7 @@ const Counter = (_init, ctx) => {
 
 ### async 组件（三条纪律）
 
-async 组件让"拿数据渲染页面"像写同步代码——签名与同步组件一致，唯一差别是 `async` 关键字（**无需 asyncComponent 包装**）：`async (initProps, ctx) => renderFn`。异步只在工厂边界：
+async 组件让"拿数据渲染页面"像写同步代码——签名与同步组件一致，唯一差别是 `async` 关键字：`async (initProps, ctx) => renderFn`。异步只在工厂边界：
 
 ```tsx
 const UserProfile = async (_init, ctx) => {
@@ -469,9 +468,10 @@ const UserProfile = async (_init, ctx) => {
 | ③ 初始状态必须确定性 | `$.w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
 
 **常见坑**：
-- 工厂**拿不到 props**——数据维度从 `ctx.params` / `ctx.data` 取
-- 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）；工厂缓存绑定页面上下文，路由导航/登录登出时自动失效
+- 工厂按**实例**执行（N 处实例 = N 次工厂调用）——数据必须走 `ctx.data`（自带缓存 + 并发合并，重复执行零成本）；禁止副作用/昂贵操作裸写工厂
+- 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）
 - **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在 `$` + fetch
+- **占位显示**：async 组件未 resolve 时渲染 `Placeholder`——无边界显示 null；`<Suspense fallback={...}>` 边界内占位处显示 fallback（可选，子树内任意深度 async 组件共享）
 
 ### 渲染策略：SPA 还是 SSR？
 
@@ -511,11 +511,11 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 
 | 文档 | 内容 |
 |------|------|
-| [docs/frontend.md](docs/frontend.md) | 前端核心：UIRouter / 组件模型 / 状态管理 / 条件与列表 / ref / 类型（历史 client 版见 docs/frontend.md） |
+| [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) | 组件库（113 个组件 + 使用示例 + 组件列表） |
-| [docs/layout.md](docs/layout.md) | 布局系统：57 个布局原语 + 136 个工具类 + 167 个主题 Token |
+| [docs/layout.md](docs/layout.md) | 布局系统：58 个布局原语 + 136 个工具类 + 167 个主题 Token |
 | [docs/styling.md](docs/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
 
 ### 通用

package/dist/ai/types.d.ts

@@ -3,7 +3,7 @@
  *
  * 纯类型，零运行时成本。两端同源：
  *   - 后端：从 weifuwu 主包导入（src/index.ts re-export）
- *   - 前端：从 weifuwu/client 导入（src/client/index.ts re-export）
+ *   - 前端：从 weifuwu/ui-dom 导入（src/ui-dom/index.ts re-export）
  *
  * 修改本文件 = 修改协议，需同步更新 design/ai-contract.md。
  */
@@ -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/Button/Button.d.ts

@@ -7,6 +7,8 @@ export interface ButtonProps {
     disabled?: boolean;
     type?: 'button' | 'submit';
     title?: string;
+    /** 透传 DOM id（测试定位/锚点） */
+    id?: string;
     /** 透传原生 class（覆盖默认 wf-btn 组合） */
     class?: string;
     onClick?: (e: MouseEvent) => void;

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/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/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';