weifuwu 0.74.0 → 0.76.0

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

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client 类型定义
+ * weifuwu/ui-dom 类型定义
  */
 import type { UseChatHandle, UseChatOptions } from './use-chat.ts';
 import type { VNode } from './vnode.ts';
@@ -22,12 +22,6 @@ export interface PopupPositionOptions {
     /** 视口边缘安全边距（px，默认 8） */
     margin?: number;
 }
-/** 响应式状态容器（createReactiveState 返回值）——深度 Proxy：任意层级赋值触发 dirty */
-export interface ReactiveState {
-    /** 订阅状态变更（任意层级赋值/删除触发）；返回退订函数 */
-    __watch: (cb: () => void) => () => void;
-    [key: string]: any;
-}
 /** 异步取数工具返回值 — ctx.ui.useAsync()（data/loading/error 响应式，reload 重跑） */
 export interface UseAsyncHandle<T = any> {
     data?: T;
@@ -78,6 +72,16 @@ export interface UsePopupOptions {
     closeOnOutside?: boolean;
     /** Escape 关闭（默认 true） */
     closeOnEscape?: boolean;
+    /** 遮罩（默认 false）：渲染全屏 overlay（--wf-overlay，点击遮罩关闭，
+     *  模态语义阻断页面交互）。false = 无遮罩 document 外部点击（§5.4 默认）。
+     *  遮罩层 z-index = --wf-z-overlay(80) < 面板 --wf-z-popover(120)。
+     *  配合 maskClosable 控制遮罩点击是否关闭。 */
+    mask?: boolean;
+    /** 遮罩点击关闭（默认 true；mask:true 时生效——危险确认 maskClosable=false 防误触） */
+    maskClosable?: boolean;
+    /** 遮罩面板居中（默认 false；mask:true 时生效）：面板覆盖全屏 flex 居中
+     *  （预览图/全屏浮层场景——忽略 trigger 定位，替代 dropdown 的 bottom 定位） */
+    maskCentered?: boolean;
     /** 长按触发时长（ms，仅 trigger='longpress'，默认 500） */
     longPressDuration?: number;
     /** 打开触发回调（longpress 计时到/右键兼容时调用，携带光标坐标——右键菜单定位用） */
@@ -256,11 +260,7 @@ export interface WfuiContext {
     /** UI 框架能力（由 createApp.mount 注入） */
     ui: {
         /** 触发组件重渲染（同步，无参 = 当前组件） */
-        render: (ids?: string[]) => void;
-        /** 异步触发组件重渲染（微任务批处理，无参 = 当前组件） */
-        dirty: (ids?: string[]) => void;
-        /** 创建响应式状态容器：$.x = val 自动触发 dirty() */
-        $: () => Record<string, any>;
+        render: (ids?: string[]) => Promise<void>;
         /**
          * AI 对话会话：$ 超集（会话语义 + 工具调用内嵌 + HITL 审批）
          *
@@ -359,6 +359,23 @@ export interface WfuiContext {
             dropProps: Record<string, any>;
             dragProps: Record<string, any>;
         };
+        /**
+         * 订阅共享状态（render-only 共享原语——design/render-only-plan.md）：
+         * mount 注册订阅（任何变化 → 自身重渲染），unmount 自动退订；返回 store 本身（活引用）。
+         * 参数契约：任何 { subscribe(cb): unsub } 的可订阅对象（createStore 产物 / useChat handle）。
+         *
+         * ```tsx
+         * const store = createStore({ count: 0 })
+         * const Comp = (_init, ctx) => {
+         *   ctx.ui.useExternal(store)
+         *   return () => h('div', {}, store.state.count)
+         * }
+         * ```
+         */
+        useExternal: (store: {
+            subscribe(cb: () => void): () => void;
+            [key: string]: any;
+        }) => any;
         /**
          * 可视视口跟踪（visualViewport）：键盘弹起/缩放时自动更新 + dirty。
          * 无 visualViewport（桌面）降级 innerHeight。fixed 底部栏防键盘遮挡用。
@@ -543,23 +560,23 @@ export interface WfuiContext {
     };
     /** API 客户端（由 api 中间件注入）；options 为 ApiRequestOptions 形状（headers/signal） */
     api?: {
-        get: <T = unknown>(url: string, options?: {
+        get: <T = any>(url: string, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        post: <T = unknown>(url: string, body?: unknown, options?: {
+        post: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        put: <T = unknown>(url: string, body?: unknown, options?: {
+        put: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        patch: <T = unknown>(url: string, body?: unknown, options?: {
+        patch: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        delete: <T = unknown>(url: string, options?: {
+        delete: <T = any>(url: string, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;

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

@@ -1,13 +1,13 @@
 /**
- * weifuwu/client VNode — 虚拟 DOM 节点
+ * weifuwu/ui-dom VNode — 虚拟 DOM 节点
  *
  * VNode 是纯 JS 对象，不依赖 DOM。组件返回 VNode。
  *
  * h/jsx 由 esbuild JSX 编译调用：
- *   --jsxImportSource=weifuwu/client
+ *   --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,53 +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：直接 await（无占位）
- *
- * asyncComponent() 是兼容包装（工厂签名 (ctx)，WeakMap 全局一次——代码分割场景）。
- */
-export type AsyncComponent<C extends object = {}, P = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<Component<P, C> | null>;
-/**
- * 兼容包装：async 工厂（旧签名 (ctx)，WeakMap 全局一次——代码分割/昂贵一次性资源）。
- * 统一为原生 async 组件签名 (initProps, ctx) => Promise<Component>，渲染器原生处理。
  *
- * ```tsx
- * const UserProfile = asyncComponent(async (ctx) => {
- *   const { default: def } = await import('./view.tsx')
- *   return def
- * })
- * ```
+ * 模式 A（design/async-mode-a-plan.md）：主路径 buildVNode await 全部工厂（无占位）；
+ * 动态挂载兑底占位 + 局部补全。渲染器按「返回值是 Promise」原生判别。
  */
-export declare function asyncComponent<C extends object = {}, P = {}>(factory: (ctx: WfuiContext & C) => Promise<Component<P, C>>): AsyncComponent<C, P>;
-/** 判定一个组件类型是否为 async 工厂（asyncComponent 包装过） */
-export declare function isAsyncComponent(type: any): type is AsyncComponent;
+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/dist/user/token.d.ts

@@ -2,7 +2,7 @@
  * 会话令牌（零依赖，node:crypto）
  *
  * access token：HMAC-SHA256 签名的 JWT 形态（base64url），
- *   与 weifuwu/client 的 auth() 兼容（客户端解码 payload 检查 exp）。
+ *   与 weifuwu/ui-dom 的 auth() 兼容（客户端解码 payload 检查 exp）。
  * refresh token：不透明随机串（256-bit），DB 只存 SHA-256 哈希（可撤销）。
  */
 /** 签发 JWT access token（HS256） */

package/docs/compat-three-library.md

@@ -105,7 +105,7 @@
 ### 框架级
 | antd | weifuwu | 状态 | 备注 |
 |------|---------|:----:|------|
-| App | `createApp` | 🔧 | client 框架内置 |
+| App 引导 | `UIRouter + uiServe` | 🔧 | ui-dom 框架内置（weifuwu/client 已并入 ui-dom） |
 | ConfigProvider | `--wf-*` token + ctx 注入 | 🔧 | client 框架内置 |
 
 ---

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
@@ -193,4 +210,4 @@
 | **StatCard ⬆️** | 增强 | antd Statistic.Countdown | countdown 模式：剩余 HH:MM:SS + 结束回调（1s tick + 清理纪律） |
 
 > 三库 208 项（antd 84 / EP 74 / shadcn 50）→ 100% 覆盖（业务组件全对应；
-> 框架级 App/ConfigProvider/Teleport/Overlay 由 createApp/createPortal/--wf-* token 内置）。
+> 框架级 App/ConfigProvider/Teleport/Overlay 由 UIRouter+uiServe/createPortal/--wf-* token 内置）。