weifuwu 0.75.0 → 0.77.0

package/dist/ui-dom/types.d.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;
@@ -44,17 +38,20 @@ export interface PopupPosition {
     refresh: () => void;
 }
 /** 弹层触发方式 — usePopup 的 trigger */
-export type PopupTrigger = 'hover' | 'click' | 'longpress';
+export type PopupTrigger = 'hover' | 'click' | 'longpress' | 'focus' | 'manual';
 /** 弹层组合器配置 — 供 ctx.ui.usePopup 使用 */
 export interface UsePopupOptions {
-    /** 触发方式（支持 getter——动态读最新 props；hover 在触屏环境自动降级为 tap） */
-    trigger: PopupTrigger | (() => PopupTrigger);
+    /** 触发方式（支持 getter——动态读最新 props；hover 在触屏环境自动降级为 tap）。
+     *  可选——缺省 'manual'（无触发 handler——Modal/Drawer 会话级模态场景） */
+    trigger?: PopupTrigger | (() => PopupTrigger);
     /** 弹出方向（支持 getter——动态读最新 props），默认 'bottom' */
     placement?: Placement | (() => Placement);
-    /** 自由定位（支持 getter）：提供则忽略 placement，直接用坐标（如右键菜单光标处） */
+    /** 自由定位（支持 getter）：提供则忽略 placement，直接用坐标（如右键菜单光标处）。
+     *  可返回 width（可选）——portal 内联 style 精确宽度（DatePicker 跟随 trigger 宽） */
     position?: () => {
         x: number;
         y: number;
+        width?: number;
     };
     /** 水平对齐：center=居中于触发元素（默认），start=左对齐（Menubar 面板用） */
     center?: boolean;
@@ -62,8 +59,8 @@ export interface UsePopupOptions {
     gap?: number;
     /** 视口安全边距（px，默认 8） */
     margin?: number;
-    /** 锚定元素 getter（ref 保存的触发元素） */
-    el: () => HTMLElement | null;
+    /** 锚定元素 getter（ref 保存的触发元素）；positioning 'none' 场景可省略 */
+    el?: () => HTMLElement | null;
     /** 是否打开（getter） */
     isOpen: () => boolean;
     /** 非受控：设置打开状态（调用方负责 render/dirty） */
@@ -72,12 +69,24 @@ export interface UsePopupOptions {
     open?: boolean | (() => boolean);
     /** 受控回调（可选） */
     onOpenChange?: (open: boolean) => void;
-    /** 面板宽度（px，可选）：自动 clamp 到视口（≤ 100vw - 32px） */
-    width?: number;
+    /** 面板宽度（px 或 getter，可选）：自动 clamp 到视口（≤ 100vw - 32px）；getter 动态跟随
+     *  （DatePicker date 模式跟随 trigger 宽，range 模式返回 undefined 自适应双面板） */
+    width?: number | (() => number | undefined);
     /** 点外部关闭（默认 true） */
     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 控制遮罩点击是否关闭。
+     *  传 VNode = 自定义遮罩内容（Tour 挖洞高亮遮罩——交互组件自控，不自动 onClick） */
+    mask?: boolean | VNode;
+    /** 遮罩点击关闭（默认 true；mask:true 时生效——危险确认 maskClosable=false 防误触） */
+    maskClosable?: boolean;
+    /** 遮罩面板居中（默认 false；mask:true 时生效）：面板覆盖全屏 flex 居中
+     *  （预览图/全屏浮层场景——忽略 trigger 定位，替代 dropdown 的 bottom 定位） */
+    maskCentered?: boolean;
     /** 长按触发时长（ms，仅 trigger='longpress'，默认 500） */
     longPressDuration?: number;
     /** 打开触发回调（longpress 计时到/右键兼容时调用，携带光标坐标——右键菜单定位用） */
@@ -91,12 +100,26 @@ export interface UsePopupOptions {
     closeDelay?: number | (() => number);
     /** 禁用（getter）：禁用时所有触发不生效且 portal 不渲染 */
     disabled?: () => boolean;
+    /** 定位模式：'anchor'（默认——锚定 el 计算坐标）/ 'none'（不加坐标——组件自定义定位，
+     *  如 Modal 的 .wf-modal inset:0 居中） */
+    positioning?: 'anchor' | 'none';
+    /** 会话级模态能力（Modal/Drawer 用——锚定弹层默认全关，零成本） */
+    /** 退场状态机（open → exit → closed + animationend 卸载）：组件 render 阶段调 sync(open) 驱动 */
+    presence?: boolean;
+    /** 焦点 trap（面板挂载时锁定焦点，卸载归还——会话级模态专用） */
+    trapFocus?: boolean;
+    /** 滚动锁（sync(true) 锁 body 滚动 / 面板卸载释放——会话级模态专用） */
+    lockScroll?: boolean;
 }
 /** 弹层组合器返回值 — usePopup */
 export interface UsePopupHandle {
     /** 当前打开状态（渲染期读取） */
     open: boolean;
     setOpen: (open: boolean) => void;
+    /** 当前阶段（presence 模式：open → exit → closed；非 presence：open/closed 二态） */
+    phase?: 'closed' | 'open' | 'exit';
+    /** 同步打开状态（render 阶段调用——presence 模式驱动退场状态机，返回当前 phase；非 presence 模式返回二态） */
+    sync?: (open: boolean) => 'closed' | 'open' | 'exit';
     /** spread 到触发/包装元素：触发（hover 门控/tap 降级/longpress）+ Escape + focus */
     wrapProps: Record<string, any>;
     /** 包装弹层内容：定位 + 视口/宽度 clamp + portal；关闭时返回 null */
@@ -256,11 +279,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 +378,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 底部栏防键盘遮挡用。
@@ -450,26 +486,6 @@ export interface WfuiContext {
                 onFocus: () => void;
             };
         };
-        /**
-         * 全屏对话框组合器（收敛 Modal/Drawer 的退场状态机 + 滚动锁 + 焦点 trap）：
-         * mount 创建，render 阶段 sync(open) 驱动状态机；组件只管布局。
-         *
-         * ```tsx
-         * const dialog = ctx.ui.useDialog({ name: 'Modal' })
-         * return (props) => {
-         *   const phase = dialog.sync(props.open)
-         *   if (phase === 'closed') return null
-         *   return createPortal(h('div', {
-         *     ref: dialog.rootRef,
-         *     class: `wf-modal ${phase === 'exit' ? 'wf-modal--exit' : 'wf-modal--enter'}`,
-         *     onKeyDown: (e) => { if (e.key === 'Escape') props.onClose?.() },
-         *   }, [overlay, h('div', { class: 'wf-modal-content', ref: dialog.panelRef }, children)]), 'modal')
-         * }
-         * ```
-         * Escape 语义（危险操作差异）留在组件层——诚实裁剪。
-         */
-        /** 通用显隐状态机（非 dialog 浮层/面板）：open → exit → closed（animationend 延迟卸载）。
-         * useDialog 是其对话框特例（+ lockScroll/trapFocus）。mount 创建，render 阶段 sync(open)。 */
         usePresence: (options?: {
             name?: string;
         }) => {
@@ -479,17 +495,6 @@ export interface WfuiContext {
             /** render 阶段同步 open → 返回当前 phase */
             sync: (open: boolean) => 'closed' | 'open' | 'exit';
         };
-        useDialog: (options?: {
-            name?: string;
-        }) => {
-            phase: 'closed' | 'open' | 'exit';
-            /** 挂到 portal 根（lockScroll + animationend 退场监听） */
-            rootRef: (el: HTMLElement | null) => void;
-            /** 挂到焦点 trap 目标（对话框面板） */
-            panelRef: (el: HTMLElement | null) => void;
-            /** render 阶段同步 open → 返回当前 phase */
-            sync: (open: boolean) => 'closed' | 'open' | 'exit';
-        };
         /** 响应式系统偏好（prefers-reduced-motion）：JS 动画（rAF/tween）侧跳过用。
          * CSS 动画已有 _base.css 全局降级（0.01ms）——此原语覆盖 JS 动画路径。 */
         useReducedMotion: () => boolean;

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,41 @@
+/**
+ * vdom/build — async 预构建（阶段 1）
+ *
+ * 核心不变量：
+ * - 组件 vnode 构建后 `_render` 已设（工厂只跑一次）
+ * - 旧树同位置同类型复用 `_render`（工厂不重跑——组件跨渲染保持内部状态）
+ * - 剪枝：已构建 + props 同 + 旧 _child 有值 → 复用旧 _child（renderFn 不重跑）
+ * - 兄弟组件并行（工厂同步执行到第一个 await 后并发等待）
+ * - **纯函数无 DOM**——构建产物只含 vnode 树
+ *
+ * V3-2（同步快路径）：buildVNode 非 async——返回 `VNodeChild | Promise<VNodeChild>`。
+ * **红线（用户确认）：组件两阶段异步定义不可改动**——组件 vnode 分支仍 await 工厂 +
+ * renderFn（renderFn 强制异步契约不变）；仅「无需 await 的路径」（剪枝复用/文本/null/
+ * 已构建 native）同步返回——零微任务。调用方统一 await 吸收（同步值 await 仅 1 微任务）。
+ */
+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']) => Promise<VNode | null>;
+    childCtx: WfuiContext;
+}>;
+/**
+ * 递归展开组件树：await 工厂 → renderFn → 递归子树。**零 DOM**。
+ *
+ * - 组件节点保留在树上（挂 `_render` + `_child`）——$ dirty 精准刷新锚点不丢
+ * - 兄弟组件 Promise.all 并行
+ * - 旧树对照（oldInput）：同位置同类型组件复用旧 `_render`；同 props + 旧 _child 有值
+ *   复用旧 `_child`（renderFn 不重跑——三态 skip 语义前置）
+ * - 原地 mutate vnode（_render/_child）——引用保持
+ * - V3-2：非 async——剪枝/文本/null/已构建 native 同步返回（零微任务）；
+ *   组件路径（工厂 + renderFn await）返回 Promise（异步契约不变）
+ */
+export declare function buildVNode(input: VNodeChild, ctx: WfuiContext, oldInput?: VNodeChild, reg?: Registry, opts?: {
+    force?: boolean;
+}): VNodeChild | Promise<VNodeChild>;

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

@@ -0,0 +1,33 @@
+/**
+ * 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';
+import { normalizeChildren } from '../vnode.ts';
+export { normalizeChildren };
+export interface PatchCtx {
+    browser: any;
+    registry: import('./registry.ts').Registry;
+    /** 当前 ctx 版本号（三态 skip 版本比较：组件 _ctxVersion !== 当前版本 → 不 skip，
+     *  强制重渲染——bumpCtxVersion 递增后所有组件重跑 renderFn，如 i18n 切换语言） */
+    ctxVersion?: number;
+    /** force：跳过三态 skip（mountRoot.rerender 全量重跑用） */
+    force?: boolean;
+}
+/**
+ * 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 { createRenderer, type Renderer } from './mount.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,58 @@
+/**
+ * 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 Registry } from './registry.ts';
+export interface MountOptions {
+    browser: BrowserEnv;
+    root: HTMLElement;
+    registry?: Registry;
+    renderer?: Renderer;
+    onError?: (e: unknown) => void;
+}
+export interface MountHandle {
+    ctx: WfuiContext;
+    registry: Registry;
+    renderer: Renderer;
+    /** 挂载根组件 */
+    mount(comp: Component | VNodeChild): Promise<void>;
+    /** 整树强制重渲染（force——测试辅助/手动刷新：renderFn 重跑 + patch） */
+    rerender(): Promise<void>;
+    /** 卸载（清理 DOM） */
+    unmount(): void;
+}
+export interface VdomContext {
+    ctx: WfuiContext;
+    registry: Registry;
+    renderer: Renderer;
+    rootUi: any;
+    destroyPopupListeners: () => void;
+}
+export interface Renderer {
+    render(ids?: string[]): Promise<void>;
+}
+export interface RendererOptions {
+    registry: Registry;
+    ctx: WfuiContext;
+    rootEl?: HTMLElement;
+    onError?: (e: unknown) => void;
+}
+export declare function createRenderer(opts: RendererOptions): Renderer;
+/** 组装 vdom 渲染上下文（ctx/registry/renderer/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,15 @@
+/**
+ * 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>;
+/** 事件 prop 判定：on + 大写字母（React 约定）——排除 once/only 等 on 开头非事件属性 */
+export declare const EVENT_RE: RegExp;
+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/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 renderer（render() 直接执行——await = DOM 已同步）
+ * - 动态挂载：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>;