weifuwu 0.75.0 → 0.76.0

package/dist/ui-dom/use-chat.d.ts

@@ -5,13 +5,15 @@
  * 消息累积、工具调用内嵌、HITL 审批、错误恢复、stop/retry/clear。
  *
  * - 协议透明：消费 wf: 事件（design/ai-contract.md），页面不需要知道事件名
- * - 状态即 $：useChat 返回组件同一个响应式 Proxy，赋值自动渲染
- * - 就地累积：token 经 state.messages[idx] 代理就地 append（O(1)/token，
+ * - 状态即共享 store（render-only 方案——design/render-only-plan.md）：
+ *   state 是**普通对象**（非 Proxy），变化 → notify() → 订阅者（useExternal）重渲染；
+ *   handle 带 subscribe——可被 useExternal 订阅（AiChat 等共享会话的子组件）
+ * - 就地累积：token 经 state.messages[idx] 就地 append（O(1)/token，
  *   不重建数组；配合 key 稳定引用 → VDOM 只 patch 文本节点）
  * - 工具内嵌：wf:tool_call/progress/result 按 toolCallId/id 聚合到
  *   消息的 toolCalls[]，ToolCallCard 直接消费（call/progress/result）
  * - 审批：approval 挂消息，approve() POST approveUrl（协议 §4.5）
- * - 生命周期：dispose() 中止流（组件 ref cleanup 调用；卸载防泄漏）
+ * - 生命周期：dispose() 中止流（组件卸载时调用；卸载防泄漏）
  *
  * 核心与框架无关：transport 注入（默认 aiStream），node 直接测。
  */
@@ -29,13 +31,15 @@ export interface UiMessage {
     id: string;
     role: 'user' | 'assistant';
     content: string;
+    /** thinking 模式推理过程（wf:done 下发后挂上，ReasoningBlock 展示） */
+    reasoning?: string;
     status: 'streaming' | 'done' | 'error';
     usage?: WfUsage;
     toolCalls?: UiToolCall[];
     approval?: WfApprovalRequest;
     error?: WfError;
 }
-/** useChat 会话状态（挂在 $ 上，赋值自动渲染） */
+/** useChat 会话状态（普通对象 + 订阅——不再挂组件 $） */
 export interface UseChatState {
     messages: UiMessage[];
     input: string;
@@ -44,10 +48,10 @@ export interface UseChatState {
     usage: WfUsage | null;
     /** 最近 wf:step（思考/工具指示），done/error 时清空 */
     step: WfStep | null;
-    /** 页面自有状态与 chat 状态共处一个 $（与 ctx.ui.$() 一致） */
+    /** 页面自有状态与 chat 状态共处一个 store（订阅者共享） */
     [key: string]: any;
 }
-/** useChat 操作（挂到 $ 上的方法；调用不触发渲染，内部 set 触发） */
+/** useChat 操作（挂到 state 上的方法；调用不触发渲染，内部 notify 触发） */
 export interface ChatApi {
     /** 发送当前输入：追加 user + assistant 占位 → POST url */
     send: () => void;
@@ -57,15 +61,16 @@ export interface ChatApi {
     retry: () => void;
     /** 清空会话并中止 */
     clear: () => void;
-    /** 响应 HITL 审批（协议 §4.5）：清卡片 + POST approveUrl */
-    approve: (decision: WfApprovalDecision, note?: string) => Promise<void>;
+    /** 响应 HITL 审批（协议 §4.5）：清卡片 + POST approveUrl；modified 决策带修改后参数 */
+    approve: (decision: WfApprovalDecision, note?: string, modifiedArgs?: Record<string, unknown>) => Promise<void>;
     /** 中止流并释放（组件卸载时调用） */
     dispose: () => void;
-    /** 内部：订阅会话状态变更（AiChat 等共享 $ 的子组件用；返回退订）。
-     *  父组件 dirty 只驱动自身重渲染，共享 handle 的子组件需自行订阅。 */
-    __watch?: (cb: () => void) => () => void;
 }
-export type UseChatHandle = UseChatState & ChatApi;
+/** useChat 返回句柄：状态 + 方法 + subscribe（可被 useExternal 订阅——AiChat 等共享子组件） */
+export type UseChatHandle = UseChatState & ChatApi & {
+    /** 订阅会话状态变更（任何变化 → cb）；返回退订 */
+    subscribe: (cb: () => void) => () => void;
+};
 export interface UseChatOptions {
     /** POST 端点（返回 wf: SSE 流） */
     url: string;
@@ -85,6 +90,6 @@ export type ChatTransport = (url: string, body: unknown, callbacks: AiStreamCall
     signal?: AbortSignal;
     headers?: Record<string, string>;
 }) => AiStreamHandle;
-/** UiMessage[] → provider ChatMessage[]（剥离 UI 字段） */
+/** UiMessage[] → provider ChatMessage[]（剥离 UI 字段；reasoning 回传——thinking 模式闭环） */
 export declare function toChatMessages(msgs: UiMessage[]): ChatMessage[];
-export declare function createChatSession(state: UseChatState, transport: ChatTransport, options: UseChatOptions): ChatApi;
+export declare function createChatSession(state: UseChatState, transport: ChatTransport, options: UseChatOptions, notify?: () => void): ChatApi;

package/dist/ui-dom/vdom/build.d.ts

@@ -0,0 +1,34 @@
+/**
+ * vdom/build — async 预构建（阶段 1）
+ *
+ * 核心不变量：
+ * - 组件 vnode 构建后 `_render` 已设（工厂只跑一次）
+ * - 旧树同位置同类型复用 `_render`（工厂不重跑——组件跨渲染保持内部状态）
+ * - 剪枝：已构建 + props 同 + 旧 _child 有值 → 复用旧 _child（renderFn 不重跑）
+ * - 兄弟组件并行（工厂同步执行到第一个 await 后并发等待）
+ * - **纯函数无 DOM**——构建产物只含 vnode 树
+ */
+import type { VNode, VNodeChild } from '../vnode.ts';
+import type { WfuiContext } from '../types.ts';
+import { type Registry } from './registry.ts';
+/** 组件 props 浅比较（三态 skip 判定） */
+export declare function componentPropsEqual(a: Record<string, any>, b: Record<string, any>): boolean;
+/** 挂载 async 组件：await 工厂（两阶段：外层 mount 一次）→ 设 _render + 分配 id + childCtx */
+export declare function mountAsyncComponent(vnode: VNode, ctx: WfuiContext, reg: Registry, opts?: {
+    reuse?: VNode;
+}): Promise<{
+    renderFn: (props: VNode['props']) => VNode | null;
+    childCtx: WfuiContext;
+}>;
+/**
+ * 递归展开组件树（async）：await 工厂 → renderFn → 递归子树。**零 DOM**。
+ *
+ * - 组件节点保留在树上（挂 `_render` + `_child`）——$ dirty 精准刷新锚点不丢
+ * - 兄弟组件 Promise.all 并行
+ * - 旧树对照（oldInput）：同位置同类型组件复用旧 `_render`；同 props + 旧 _child 有值
+ *   复用旧 `_child`（renderFn 不重跑——三态 skip 语义前置）
+ * - 原地 mutate vnode（_render/_child）——引用保持
+ */
+export declare function buildVNode(input: VNodeChild, ctx: WfuiContext, oldInput?: VNodeChild, reg?: Registry, opts?: {
+    force?: boolean;
+}): Promise<VNodeChild>;

package/dist/ui-dom/vdom/diff.d.ts

@@ -0,0 +1,34 @@
+/**
+ * vdom/diff — 同步 patch（阶段 2）
+ *
+ * **不变量：diff 只处理已构建树**——组件 vnode 必已 `_render`/`_child`（buildVNode 预构建）。
+ * 遇未构建组件 → throw（开发期暴露；生产路径 renderByIds/导航都先 buildVNode await）。
+ * 这是第 1 代死循环的根治：diff 永不调用组件工厂、无 resolve 回调、无补全循环。
+ *
+ * 三态 skip：props 同 + 无 dirty + ctx 版本同 → 复用旧 _child（renderFn 不重跑）。
+ */
+import type { VNodeChild } from '../vnode.ts';
+/** 递归文本/数组归一化（children 数组展开——嵌套数组扁平化，DOM 范围对齐） */
+export declare function normalizeChildren(c: VNodeChild | undefined | null): VNodeChild[];
+export interface PatchCtx {
+    browser: any;
+    registry: import('./registry.ts').Registry;
+    /** 三态 skip 的 dirty 集合（组件 id → true） */
+    /** 已渲染组件（skip 判定——记录到 ctx，供 scheduler 清 dirty） */
+    rendered?: Set<string>;
+    /** 当前 ctx 版本号 */
+    ctxVersion?: number;
+    getCtxVersion?: (id: string) => number;
+}
+/**
+ * patchValue — 同步 diff 单一节点。
+ * @returns newInput 的实际 DOM（null = 无 DOM）
+ */
+export declare function patchValue(parent: Node, oldNode: Node | null, oldInput: VNodeChild, newInput: VNodeChild, ctx: PatchCtx): Node | null;
+/** 属性 patch（只设不删语义保持简单；差异删除由 diff 上层处理） */
+export declare function patchProps(el: Element, oldProps: Record<string, any>, newProps: Record<string, any>): void;
+/**
+ * patchChildren — 数组 diff。
+ * @returns 每个新子项的 DOM 范围（Fragment 展开对齐）
+ */
+export declare function patchChildren(parent: Node, oldInput: VNodeChild | null | undefined, newInput: VNodeChild | null | undefined, ctx: PatchCtx, oldRange?: Node[]): (Node | null)[];

package/dist/ui-dom/vdom/hydration.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vdom/hydration — 游标收养（SSR HTML → 客户端，不重建 DOM）
+ *
+ * 与第 1 代 hydration 的区别：**先 buildVNode 预构建**（await 工厂——组件已 resolve、
+ * _child 已展开）→ 再游标收养（只接线属性/事件/ref——不重跑 renderFn/工厂）。
+ *
+ * 游标不变量：元素/文本 VNode 恰好消耗一个游标节点；组件/Fragment/数组透明；
+ * null 消耗零；创建时 insertBefore(游标) 且游标不动；收养/替换时游标前进。
+ */
+import type { VNode } from '../vnode.ts';
+import type { WfuiContext } from '../types.ts';
+import { mountAsyncComponent } from './build.ts';
+/** Hydration 入口：buildVNode 预构建（await 工厂）→ 游标收养 */
+export declare function hydrateVNode(container: Element, vnode: VNode, ctx: WfuiContext): Promise<void>;
+/** 给组件 vnode 分配 id（hydration 需要——注册表定位） */
+export declare function ensureHydrationId(vnode: VNode, ctx: WfuiContext): void;
+export { mountAsyncComponent };

package/dist/ui-dom/vdom/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * vdom — 全新虚拟 DOM 引擎（第 2 代）
+ *
+ * 设计初衷（修复第 1 代死循环/动态挂载问题）：
+ * - 组件 vnode 进入 diff 前**必须已构建**（`_render` 已设）——diff 永不调用组件工厂
+ * - 构建（buildVNode）是 async 的，统一在渲染入口完成（首帧 / renderByIds / 导航）
+ * - 动态挂载组件在 buildVNode 阶段被 await（构建完成）→ diff 同步渲染——
+ *   无占位、无注释、无「resolve 回调触发补全」（第 1 代死循环根因）
+ * - 工厂只跑一次（vnode 级缓存 + 旧树同位置同类型复用）——无无限挂载
+ *
+ * 两阶段异步组件（唯一签名）：
+ *   async (initProps, ctx) => Promise<(props) => VNode | null>
+ */
+export { buildVNode } from './build.ts';
+export { renderValue } from './render.ts';
+export { patchValue } from './diff.ts';
+export { createScheduler, type Scheduler } from './scheduler.ts';
+export { createRegistry, type Registry } from './registry.ts';
+export { createStore, type ExternalStore } from '../store.ts';
+export { mountRoot, createVdomContext, mountCommand, unmountCommand, createCommandContainer } from './mount.ts';
+export { hydrateVNode } from './hydration.ts';
+export { renderSsr, ssrPage, ssrToString, serializeData, createSsrContext } from './ssr.ts';
+export { uiServe, type UIServeOptions, type UIServeHandle } from './serve.ts';

package/dist/ui-dom/vdom/mount.d.ts

@@ -0,0 +1,49 @@
+/**
+ * vdom/mount — 挂载入口（首帧 + ctx/ui 组装）
+ *
+ * 渲染管线：buildVNode（async 预构建）→ renderValue（同步落地）。
+ * ctx.ui：render/setMounting/endMounting——render-only（design/render-only-plan.md）。
+ */
+import type { VNode, VNodeChild, Component } from '../vnode.ts';
+import type { WfuiContext } from '../types.ts';
+import type { BrowserEnv } from '../types.ts';
+import { type Scheduler } from './scheduler.ts';
+import { type Registry } from './registry.ts';
+export interface MountOptions {
+    browser: BrowserEnv;
+    root: HTMLElement;
+    registry?: Registry;
+    scheduler?: Scheduler;
+    onError?: (e: unknown) => void;
+}
+export interface MountHandle {
+    ctx: WfuiContext;
+    registry: Registry;
+    scheduler: Scheduler;
+    /** 挂载根组件 */
+    mount(comp: Component | VNodeChild): Promise<void>;
+    /** 整树强制重渲染（force——测试辅助/手动刷新：renderFn 重跑 + patch） */
+    rerender(): Promise<void>;
+    /** 卸载（清理 DOM） */
+    unmount(): void;
+}
+export interface VdomContext {
+    ctx: WfuiContext;
+    registry: Registry;
+    scheduler: Scheduler;
+    rootUi: any;
+    destroyPopupListeners: () => void;
+}
+/** 组装 vdom 渲染上下文（ctx/registry/scheduler/rootUi——含完整 hooks 转发） */
+export declare function createVdomContext(opts: MountOptions): VdomContext;
+export declare function mountRoot(opts: MountOptions): MountHandle;
+/** vdom 命令式挂载：buildVNode（await 工厂）→ renderValue → append + _parentNode */
+export declare function mountCommand(container: HTMLElement, vnode: VNode, ctx: WfuiContext, opts?: {
+    onMounted?: () => void;
+}): {
+    id: string;
+};
+/** vdom 命令式卸载：ref 清理 + 卸载钩子 + 容器移除 */
+export declare function unmountCommand(container: HTMLElement, vnode: VNode | null, ctx: WfuiContext): void;
+/** 创建命令式挂载容器（body 下独立 div） */
+export declare function createCommandContainer(): HTMLDivElement | null;

package/dist/ui-dom/vdom/registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * vdom/registry — 组件实例注册表（id → vnode）+ 卸载钩子
+ *
+ * 组件 id：`_wf_0` 自动分配（精准刷新锚点）+ `_customId`（ctx.ui.selfId 注册）。
+ * 卸载钩子：hooks（usePopup/useMedia 等）注册清理回调，组件卸载时执行。
+ */
+import type { VNode } from '../vnode.ts';
+export interface Registry {
+    idRegistry: Map<string, VNode>;
+    /** 卸载钩子（按组件 id 匹配——组件卸载时执行对应清理） */
+    unmountHooks: Array<(id: string) => void>;
+    nextId(): string;
+}
+export declare function createRegistry(): Registry;
+/** 给组件 vnode 分配 id（注册表写入） */
+export declare function ensureId(reg: Registry, vnode: VNode): string;
+/** 组件卸载回调注册（hooks 清理）——返回退订函数 */
+export declare function onComponentUnmountFor(reg: Registry, hook: (id: string) => void): () => void;
+/** 组件卸载：执行匹配的清理钩子 + 移除注册（vdom 渲染器卸载组件时调用） */
+export declare function cleanupComponent(reg: Registry, id: string): void;
+/** ref 调用错误隔离（用户 ref 抛错不中断渲染/清理管线） */
+export declare function safeCallRef(ref: Function, arg: any, phase: 'mount' | 'cleanup', name?: string): void;
+/**
+ * 递归 ref 清理 + 组件卸载（组件 vnode 从树中移除时调用）：
+ * idRegistry 注销 + 卸载钩子 + _child/props.children 递归 + ref(null) + Portal 容器移除
+ */
+export declare function callRefCleanupFor(input: any, reg: Registry): void;

package/dist/ui-dom/vdom/render.d.ts

@@ -0,0 +1,13 @@
+/**
+ * vdom/render — DOM 落地（阶段 2 同步）
+ *
+ * **只处理已构建的组件**（`_render` 已设——buildVNode 已 await 工厂）。
+ * 遇未构建组件 → 抛错（开发期暴露 bug；生产路径 renderByIds 先 build 后 patch，
+ * 不会出现未构建组件）。
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { BrowserEnv } from '../types.ts';
+export declare const SVG_TAGS: Set<string>;
+export declare function setProp(el: Element, key: string, value: any): void;
+/** 递归渲染（同步——组件必须已构建） */
+export declare function renderValue(v: VNodeChild, ctx: any, browser?: BrowserEnv): Node | null;

package/dist/ui-dom/vdom/scheduler.d.ts

@@ -0,0 +1,13 @@
+import type { WfuiContext } from '../types.ts';
+import type { Registry } from './registry.ts';
+export interface Scheduler {
+    render(ids?: string[]): Promise<void>;
+}
+export interface SchedulerOptions {
+    registry: Registry;
+    ctx: WfuiContext;
+    rootEl?: HTMLElement;
+    getCtxVersion?: (id: string) => number;
+    onError?: (e: unknown) => void;
+}
+export declare function createScheduler(opts: SchedulerOptions): Scheduler;

package/dist/ui-dom/vdom/serve.d.ts

@@ -0,0 +1,30 @@
+/**
+ * vdom/serve — 第 2 代 uiServe（UIRouter + vdom 引擎）
+ *
+ * 与第 1 代 serve.ts 的区别（AGENTS.md §4.0 无自动渲染原则）：
+ * - 渲染管线：buildVNode（async 预构建 await 全部）→ renderValue/patchValue（同步落地）
+ * - 调度：vdom scheduler（无 flush 批处理——$ 赋值直接 fire-and-forget 渲染）
+ * - 动态挂载：buildVNode 阶段 await（无占位/注释/补全回调）
+ *
+ * 保留公开 API（uiServe/UIServeOptions/UIServeHandle）——迁移无缝。
+ */
+import type { UIRouter } from '../router.ts';
+import type { WfuiContext } from '../types.ts';
+/** uiServe 选项 */
+export interface UIServeOptions {
+    root: string | Element;
+    hydrate?: boolean;
+    /** loading 模式：不清空 root（信任调用方预置骨架屏 HTML）——首帧原子替换 */
+    loading?: boolean;
+}
+/** serve 句柄 */
+export interface UIServeHandle<C extends object = {}> {
+    /** 释放全部资源（监听/渲染状态/注册表） */
+    close(): void;
+    /** 首帧完成 Promise：await 全部工厂 + DOM 落地后 resolve */
+    ready: Promise<void>;
+    /** 当前 ctx（调试/测试用）——含 UIRouter ctx 注入的类型扩展 */
+    ctx: WfuiContext & C;
+}
+/** uiServe — 绑定唯一根节点 + URL 驱动渲染（vdom 引擎） */
+export declare function uiServe<RC extends object = {}>(router: UIRouter<RC>, options: UIServeOptions): UIServeHandle<RC>;

package/dist/ui-dom/vdom/ssr.d.ts

@@ -0,0 +1,44 @@
+/**
+ * vdom/ssr — 服务端渲染（无 DOM，纯字符串）
+ *
+ * SSR 与引擎无关（vnode → HTML 字符串）——vdom 独立实现：
+ * - renderSsr：await 工厂 → renderFn → 递归（组件签名两阶段 async）
+ * - createSsrContext：SSR ctx shim（hooks no-op、$ 普通对象、ctx.data 预取）
+ * - ssrPage：router.execute → renderSsr → 完整 HTML（__DATA__ 种子）
+ *
+ * 渲染期非确定性（Date/Math.random/locale）导致 SSR/hydration mismatch——
+ * dev 检测，文档红线（AGENTS.md §3.5 诚实裁剪）。
+ */
+import type { VNodeChild, Component } from '../vnode.ts';
+import type { WfuiContext } from '../types.ts';
+import type { UIRouter } from '../router.ts';
+/** HTML 转义（文本/属性值） */
+export declare function escape(s: string): string;
+/** 渲染 vnode → HTML 字符串（服务端） */
+export declare function renderSsr(input: VNodeChild, ctx: WfuiContext): Promise<string>;
+/** 创建 SSR ctx（serverCtx 注入 + dataStore 预取 + hooks shim） */
+export declare function createSsrContext(serverCtx: any, dataStore: Map<string, unknown>): WfuiContext;
+/** 序列化数据存储 → window.__DATA__ 脚本（防 XSS：转义 <） */
+export declare function serializeData(data: Map<string, unknown>): string;
+export interface SsrPageResult {
+    html: string;
+    /** __DATA__ 脚本（hydration 种子） */
+    dataScript: string;
+    /** 完整 HTML（含 dataScript） */
+    page: string;
+}
+/**
+ * SSR 渲染路由页面 → 完整 HTML（Node 无 DOM）。
+ * 客户端 uiServe(router, { root, hydrate: true }) 收养。
+ */
+export declare function ssrPage(router: UIRouter, opts: {
+    url: string;
+    title?: string;
+    lang?: string;
+    rootId?: string;
+    styles?: string[];
+}): Promise<SsrPageResult>;
+/** SSR 渲染组件 → HTML 片段 */
+export declare function ssrToString(Comp: Component, props: Record<string, any>, serverCtx: any, opts?: {
+    data?: Map<string, unknown>;
+}): Promise<string>;

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 任意组合。
@@ -32,6 +32,8 @@ export interface VNode {
     _customId?: string;
     /** 组件输出的 DOM 父节点 */
     _parentNode?: Node;
+    /** 父 vnode 引用（动态挂载补全向上找持有组件） */
+    _parentVNode?: VNode;
     /** 组件输出的第一个 DOM 节点 */
     _refNode?: Node | null;
     /** 原生 async 组件缓存（vnode 级按实例）：in-flight Promise → resolved renderFn（diff 传递继承） */
@@ -42,37 +44,18 @@ export interface VNode {
     _ctxVersion?: number;
 }
 /**
- * 两阶段组件：外层 = mount（一次），内层 = render（每次 dirty/props 变化）。
+ * 两阶段异步组件（统一签名——weifuwu 只支持这一种形态）：
+ *   async (initProps, ctx) => Promise<renderFn>
+ * 外层 = mount（一次，可 await 数据），内层 = render（每次 dirty/props 变化，同步）。
  * 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（无占位）
+ * 模式 A（design/async-mode-a-plan.md）：主路径 buildVNode await 全部工厂（无占位）；
+ * 动态挂载兑底占位 + 局部补全。渲染器按「返回值是 Promise」原生判别。
  */
-export type AsyncComponent<C extends object = {}, P = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<((props: P) => VNode | null) | null>;
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<((props: P) => VNode | null) | 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;

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 原语组件。每个是 `(_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

@@ -135,9 +135,9 @@ const UserCard = async (initProps, ctx) => {
 }
 ```
 
-- 渲染器按「返回值是 Promise」判别：客户端未 resolve → 占位（`Placeholder`），resolve 后整树补全；SSR 直接 await（无占位）
+- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；动态挂载兑底占位 + 局部补全；SSR 直接 await
 - 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
-- 占位显示：无边界 → null；`<Suspense fallback={...}>` → 占位处显示 fallback（可选）
+- 占位显示：动态挂载的 async 组件占位 = 注释节点，resolve 后局部补全（Suspense 边界已裁剪）
 - **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
 
 ## 6. 类型纪律（编译期防线）
@@ -167,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/frontend.md

@@ -768,9 +768,9 @@ const UserProfile = async (initProps, ctx) => {
 }
 ```
 
-- **客户端**：首次渲染占位（`Placeholder`）→ 工厂 resolve 后整树重渲染补全；`_asyncDef` 按实例缓存（diff 传递继承，补全不重跑工厂）——N 处实例 = N 次工厂调用，数据走 `ctx.data` 则零成本（缓存 + 并发合并）
+- **客户端**：主路径 `buildVNode` async 预构建（await 全部工厂；兄弟并行）→ 落地零占位；动态挂载兑底占位 → 局部补全——N 处实例 = N 次工厂调用，数据走 `ctx.data` 则零成本（缓存 + 并发合并）
 - **服务端**：`ctx.ui.ssr()` 直接 await 工厂 → 数据进 HTML（无占位）
-- **占位显示**：无边界 → null；`<Suspense fallback={...}>` 边界 → 子树内占位处显示 fallback（可选）
+- **占位显示**：动态挂载的 async 组件占位 = 注释节点，resolve 后局部补全（Suspense 边界已裁剪）
 - 会变的数据：初始值 seed 自服务端数据（`$.count = data.count`），交互改 `$`；初始状态必须确定性（禁止 `window.innerWidth` 直接初始化 → SSR/hydration mismatch）
 
 ---

package/docs/layout.md

@@ -2,7 +2,7 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-纯 CSS 57 个布局原语 + 136 个工具类 + 167 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 58 个布局原语 + 136 个工具类 + 167 个主题 Token。不绑定任何 JS 框架。
 
 > **学习路径与命名规范**：见 [`design/style-guide.md`](../design/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
 
@@ -25,7 +25,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 
 也支持相对路径：`ctx.ui.css('./src/style.css')`。
 
-## 57 个布局原语
+## 58 个布局原语
 
 | 类别 | 原语 | 效果 |
 |------|------|------|

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {
@@ -16,6 +16,10 @@
       "types": "./dist/ui-dom/index.d.ts",
       "default": "./dist/ui-dom/jsx-runtime.js"
     },
+    "./ui-dom/testing": {
+      "types": "./dist/ui-dom/testing.d.ts",
+      "default": "./dist/ui-dom/testing.js"
+    },
     "./layout": "./dist/layout/weifuwu-layout.css",
     "./layout/style.css": "./dist/layout/weifuwu-layout.css",
     "./components": {