weifuwu 0.74.0 → 0.76.0

package/dist/ui/index.d.ts

@@ -26,13 +26,13 @@
  * ```
  */
 import type { Middleware } from '../types.ts';
-import type { Component, AsyncComponent } from '../ui-dom/vnode.ts';
+import type { Component } from '../ui-dom/vnode.ts';
 declare module '../types.ts' {
     interface Context {
         ui: {
             /** Tagged template → HTML Response */
             html: UiHtmlTag;
-            /** 编译 TSX → JS bundle Response（支持包名 weifuwu/client 或文件路径） */
+            /** 编译 TSX → JS bundle Response（支持包名 weifuwu/ui-dom 或文件路径） */
             js: (entryPath: string) => Promise<Response>;
             /** 读取 CSS → CSS Response（支持包名 weifuwu/layout、weifuwu/components/style.css 或文件路径） */
             css: (entryPath: string) => Promise<Response>;
@@ -41,7 +41,7 @@ declare module '../types.ts' {
              * 支持 async 工厂组件：await 工厂 → 数据进 HTML。
              * opts.data（Map）收集 ctx.data 预取结果，用 ctx.ui.ssrData(data) 序列化进 __DATA__。
              */
-            ssr: (Comp: Component | AsyncComponent, props?: Record<string, any>, opts?: {
+            ssr: (Comp: Component, props?: Record<string, any>, opts?: {
                 data?: Map<string, unknown>;
             }) => Promise<string>;
             /** 序列化 SSR 数据存储 → <script>window.__DATA__=...</script>（HtmlSafe） */

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

@@ -1,44 +1,8 @@
 /**
- * weifuwu/components — Confirm 确认对话框
+ * weifuwu/ui-dom — Confirm（命令式中间件）
  *
- * 声明式：基于 Modal 封装，footer 自带「取消 / 确定」按钮。
- * 命令式：confirm() 中间件注入 ctx.confirm()，返回 Promise<boolean>。
+ * v1 退役（design/render-only-plan.md）：实现已收敛到 components/Confirm（vdom 引擎，
+ * mountCommand + render-only）。本文件保留为公开 API 兼容入口。
  */
-import type { Component } from './vnode.ts';
-import type { AppMiddleware } from './types.ts';
-export interface ConfirmProps {
-    open?: boolean;
-    title?: string;
-    /** 提示内容（文本或任意 VNode） */
-    message?: any;
-    confirmText?: string;
-    cancelText?: string;
-    variant?: 'primary' | 'danger';
-    /** 对话框宽度，如 '500px'、'80%'，默认 Modal 的 400px */
-    width?: string;
-    /** 遮罩点击是否取消（默认 false：危险操作防误触；显式传 true 可恢复） */
-    maskClosable?: boolean;
-    onConfirm?: () => void;
-    onCancel?: () => void;
-}
-/** 命令式 ctx.confirm 的选项（ConfirmProps 的子集） */
-export interface ConfirmOptions {
-    title?: string;
-    confirmText?: string;
-    cancelText?: string;
-    variant?: 'primary' | 'danger';
-    width?: string;
-    maskClosable?: boolean;
-}
-/** 命令式 ctx.confirm 的注入类型（AppMiddleware<{}, ConfirmInjected>） */
-export interface ConfirmInjected {
-    confirm: (message: string, options?: ConfirmOptions) => Promise<boolean>;
-}
-/**
- * 命令式中间件：注入 ctx.confirm()
- *
- * 每次调用挂载 Confirm 组件到独立容器（mountVNode），
- * resolve 后 callRefCleanup 清理（含 Modal 的 portal DOM）+ 移除容器。
- */
-export declare function confirm(): AppMiddleware<{}, ConfirmInjected>;
-export declare const Confirm: Component<ConfirmProps>;
+export { Confirm, confirm } from '../components/Confirm/Confirm.ts';
+export type { ConfirmProps, ConfirmOptions, ConfirmInjected } from '../components/Confirm/Confirm.ts';

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

@@ -1,70 +1,8 @@
-import type { Component } from './vnode.ts';
-import type { AppMiddleware } from './types.ts';
-export type NotificationType = 'success' | 'error' | 'info' | 'warning';
-export type NotificationPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
-export interface NotificationItem {
-    id: string;
-    type: NotificationType;
-    title: string;
-    description?: string;
-    /** 自动关闭时间（ms），0 = 不自动关闭，默认 4500 */
-    duration?: number;
-    action?: {
-        label: string;
-        onClick: () => void;
-    };
-}
-export interface NotificationProps {
-    items?: NotificationItem[];
-    onRemove?: (id: string) => void;
-    position?: NotificationPosition;
-    /** 全局默认自动关闭时间（ms），默认 4500 */
-    duration?: number;
-    /** 最大显示条数，超出移除最早，默认 0 = 不限制 */
-    max?: number;
-}
-export interface NotificationOptions {
-    position?: NotificationPosition;
-    duration?: number;
-    max?: number;
-}
-/** 通知（对应 antd/EP Notification 队列式）：title + description + icon + 操作，聚合角落 */
-export declare const Notification: Component<NotificationProps>;
-export interface NotificationInjected {
-    notification: {
-        (title: string, opts?: {
-            type?: NotificationType;
-            description?: string;
-            duration?: number;
-            action?: NotificationItem['action'];
-        }): void;
-        open: (opts: {
-            type?: NotificationType;
-            title: string;
-            description?: string;
-            duration?: number;
-            action?: NotificationItem['action'];
-        }) => void;
-        success: (opts: {
-            title: string;
-            description?: string;
-            duration?: number;
-        }) => void;
-        error: (opts: {
-            title: string;
-            description?: string;
-            duration?: number;
-        }) => void;
-        info: (opts: {
-            title: string;
-            description?: string;
-            duration?: number;
-        }) => void;
-        warning: (opts: {
-            title: string;
-            description?: string;
-            duration?: number;
-        }) => void;
-    };
-}
-export declare function notification(opts?: NotificationOptions): AppMiddleware<{}, NotificationInjected>;
+/**
+ * weifuwu/ui-dom — Notification（命令式中间件）
+ *
+ * v1 退役（design/render-only-plan.md）：实现已收敛到 components/Notification（vdom 引擎，
+ * mountCommand + render-only）。本文件保留为公开 API 兼容入口。
+ */
+export { Notification, notification } from '../components/Notification/Notification.ts';
+export type { NotificationType, NotificationPosition, NotificationItem, NotificationProps, NotificationOptions, NotificationInjected, } from '../components/Notification/Notification.ts';

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

@@ -1,43 +1,8 @@
-import type { Component } from './vnode.ts';
-import type { AppMiddleware } from './types.ts';
-export type ToastType = 'success' | 'error' | 'info' | 'warning';
-export type ToastPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center';
-export interface ToastItem {
-    id: string;
-    type: ToastType;
-    message: string;
-    /** 此条目的自动消失时间（ms），覆盖 Toast 的默认 duration */
-    duration?: number;
-    /** 操作按钮（如"撤销"）：点击不自动关闭，由回调自行移除 */
-    action?: {
-        label: string;
-        onClick: () => void;
-    };
-}
-export interface ToastProps {
-    toasts?: ToastItem[];
-    onRemove?: (id: string) => void;
-    /** 容器位置，默认 top-right */
-    position?: ToastPosition;
-    /** 全局默认自动消失时间（ms），0 = 不自动消失，默认 0 */
-    duration?: number;
-    /** 最大显示条数，超出时移除最早条目，默认 0 = 不限制 */
-    max?: number;
-}
-/** 命令式 ctx.toast 的全局配置 */
-export interface ToastOptions {
-    position?: ToastPosition;
-    /** 默认自动消失时间（ms），0 = 不消失，默认 3000 */
-    duration?: number;
-    /** 最大显示条数，超出移除最早，默认 3 */
-    max?: number;
-}
-export declare const Toast: Component<ToastProps>;
-/** 命令式 ctx.toast 的注入类型（AppMiddleware<{}, ToastInjected>） */
-export interface ToastInjected {
-    toast: (message: string, type?: ToastType, duration?: number, action?: {
-        label: string;
-        onClick: () => void;
-    }) => void;
-}
-export declare function toast(opts?: ToastOptions): AppMiddleware<{}, ToastInjected>;
+/**
+ * weifuwu/ui-dom — Toast（命令式中间件）
+ *
+ * v1 退役（design/render-only-plan.md）：实现已收敛到 components/Toast（vdom 引擎，
+ * mountCommand + render-only）。本文件保留为公开 API 兼容入口。
+ */
+export { Toast, toast } from '../components/Toast/Toast.ts';
+export type { ToastType, ToastPosition, ToastItem, ToastProps, ToastOptions, ToastInjected, } from '../components/Toast/Toast.ts';

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

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client AI 解码器 — 消费 wf: 协议（design/ai-contract.md）
+ * weifuwu/ui-dom AI 解码器 — 消费 wf: 协议（design/ai-contract.md）
  *
  * 协议的前端参考实现：POST → 解析 SSE → 按事件名分发回调。
  *

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

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client — 浏览器环境抽象（ctx.browser 的客户端实现）
+ * weifuwu/ui-dom — 浏览器环境抽象（ctx.browser 的客户端实现）
  *
  * 组件不直接引用 window/document——统一经 ctx.browser：
  * ① SSR 安全（createSsrContext 注入安全默认）② 测试可 mock

package/dist/ui-dom/focus-trap.d.ts

@@ -1,4 +1,4 @@
 /**
- * weifuwu/client — FocusTrap
+ * weifuwu/ui-dom — FocusTrap
  */
 export declare function trapFocus(container: HTMLElement): () => void;

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

@@ -0,0 +1,11 @@
+/**
+ * hooks/chat — AI 对话会话（useChat）
+ *
+ * 会话语义 + 工具调用内嵌 + HITL 审批。render-only 方案（design/render-only-plan.md）：
+ * state 是**普通对象**（不再挂组件 $），变化 → notify → 订阅者重渲染；
+ * handle 带 subscribe——共享会话的子组件用 ctx.ui.useExternal(handle) 订阅。
+ */
+import type { HookEnv } from './types.ts';
+import type { UseChatHandle, UseChatOptions } from '../use-chat.ts';
+/** AI 对话会话（会话语义 + 工具调用内嵌 + HITL 审批） */
+export declare function useChat(env: HookEnv, options: UseChatOptions): UseChatHandle;

package/dist/ui-dom/hooks/events.d.ts

@@ -0,0 +1,30 @@
+/**
+ * hooks/events — 事件/键盘/拖拽 hooks
+ *
+ * useGlobalKey / useDrag / useDragDrop
+ */
+import type { HookEnv } from './types.ts';
+/** 全局键盘监听：window keydown，mount 注册 + 卸载清理。返回退订函数。 */
+export declare function useGlobalKey(env: HookEnv, handler: (e: KeyboardEvent) => void): () => void;
+/** 指针拖拽：pointerdown 捕获 → window pointermove（delta）/pointerup（释放）。 */
+export declare function useDrag(env: HookEnv, options: {
+    onStart?: (e: PointerEvent) => void;
+    onMove: (e: PointerEvent, delta: {
+        x: number;
+        y: number;
+    }) => void;
+    onEnd?: (e: PointerEvent) => void;
+}): {
+    onPointerDown: (e: PointerEvent) => void;
+};
+/** 原生 DnD：drop/dragover/dragleave（dragover 自动 preventDefault）。 */
+export declare function useDragDrop(env: HookEnv, options: {
+    onDrop?: (e: DragEvent) => void;
+    onDragOver?: (e: DragEvent) => void;
+    onDragLeave?: (e: DragEvent) => void;
+    onDragStart?: (e: DragEvent) => void;
+    onDragEnd?: (e: DragEvent) => void;
+}): {
+    dropProps: Record<string, any>;
+    dragProps: Record<string, any>;
+};

package/dist/ui-dom/hooks/external.d.ts

@@ -0,0 +1,20 @@
+/**
+ * useExternal — 订阅共享状态（render-only 共享原语，见 design/render-only-plan.md）
+ *
+ * 与 useInView/useScrollPosition 同构（mount 阶段注册，生命周期框架管）：
+ * - mount 注册：订阅 store（任何变化 → 自身重渲染）
+ * - unmount 自动退订（onComponentUnmountFor——无手动退订纪律，无 §4.6 __watch 泄漏）
+ * - 返回 store 本身（活引用）——渲染函数里读最新值：
+ *     createStore 产物 → store.state.xxx
+ *     useChat handle  → handle.messages（handle 就是活 state）
+ *
+ * 参数契约：任何「可订阅状态」——{ subscribe(cb): unsub } 即可（结构化类型）。
+ * SSR 无害：createSsrUi 的 useExternal shim 只返回 store 不订阅。
+ */
+import type { HookEnv } from './types.ts';
+/** 可订阅状态（useExternal 入参——结构化类型，不要求专用 store） */
+export interface Subscribable {
+    subscribe(cb: () => void): () => void;
+    [key: string]: any;
+}
+export declare function useExternal(env: HookEnv, store: Subscribable): Subscribable;

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

@@ -0,0 +1,31 @@
+/**
+ * hooks — 汇总导出
+ *
+ * hooks 重构：所有 ctx.ui.useXXX 的实现从 createUi 拆出为独立 hooks 函数，
+ * 签名统一 `useXXX(env, ...args)`。ui.ts 组装 HookEnv + 薄转发。
+ */
+export type { HookEnv, MediaRegistryItem, PopupTracker, ScrollTracker } from './types.ts';
+export { useStableRef } from './stable.ts';
+export { useHoverCapable } from './stable.ts';
+export { useReducedMotion } from './stable.ts';
+export { useAnimationEnd } from './stable.ts';
+export { useLongPress } from './stable.ts';
+export { usePresence } from './stable.ts';
+export { useTween } from './stable.ts';
+export { useMedia } from './media.ts';
+export { useBreakpoint } from './media.ts';
+export { useVisualViewport } from './media.ts';
+export { useInView } from './media.ts';
+export { useScrollPosition } from './media.ts';
+export { useControlled } from './input.ts';
+export { useControlledInput } from './input.ts';
+export { useAsync } from './input.ts';
+export { useGlobalKey } from './events.ts';
+export { useDrag } from './events.ts';
+export { useDragDrop } from './events.ts';
+export { usePopupPosition } from './popup.ts';
+export { usePopup } from './popup.ts';
+export { useOpen } from './popup.ts';
+export { useDialog } from './popup.ts';
+export { useChat } from './chat.ts';
+export { useExternal } from './external.ts';

package/dist/ui-dom/hooks/input.d.ts

@@ -0,0 +1,33 @@
+/**
+ * hooks/input — 受控/输入/异步取数 hooks
+ *
+ * useControlled / useControlledInput / useAsync
+ */
+import type { HookEnv } from './types.ts';
+import type { UseAsyncHandle } from '../types.ts';
+/** 受控/非受控状态统一：value !== undefined → 受控（setValue 只走 onChange） */
+export declare function useControlled<T>(env: HookEnv, options: {
+    value?: T;
+    onChange?: (v: T) => void;
+    name?: string;
+}): {
+    value: T | undefined;
+    setValue: (v: T) => void;
+    controlled: boolean;
+};
+/** 受控输入原语（C3）：useControlled + 内部输入态/选中态（输入焦点保持） */
+export declare function useControlledInput(env: HookEnv, options: {
+    value?: string;
+    onChange?: (v: string) => void;
+    name?: string;
+}): {
+    keyword: string;
+    setKeyword(v: string): void;
+    selectedLabel: string;
+    setSelectedLabel(v: string): void;
+    value: string | undefined;
+    setValue: (v: string) => void;
+    controlled: boolean;
+};
+/** 异步取数工具（mount 阶段调用）：loading/error 自动管理 + 数据就绪自动渲染 */
+export declare function useAsync<T>(env: HookEnv, fetcher: () => Promise<T>): UseAsyncHandle<T>;

package/dist/ui-dom/hooks/media.d.ts

@@ -0,0 +1,17 @@
+/**
+ * hooks/media — 响应式媒体/视口 hooks
+ *
+ * useMedia / useBreakpoint / useVisualViewport / useInView / useScrollPosition
+ */
+import type { HookEnv } from './types.ts';
+import type { UseInViewOptions, UseInViewHandle, UseScrollPositionOptions, UseScrollPositionHandle, VisualViewportHandle } from '../types.ts';
+/** 响应式媒体查询：注册监听，值变化时自动 dirty。callback 立即执行一次当前值。 */
+export declare function useMedia(env: HookEnv, query: string, callback: (matches: boolean) => void): void;
+/** 响应式断点：注册命名断点监听，值变化时自动 dirty */
+export declare function useBreakpoint(env: HookEnv, bpsOrCallback: Record<string, string> | ((vp: string) => void), callback?: (vp: string) => void): void;
+/** 可视视口跟踪（visualViewport）：键盘弹起/缩放时自动更新 + dirty */
+export declare function useVisualViewport(env: HookEnv): VisualViewportHandle;
+/** 可见性观察（IntersectionObserver 封装）：isIn 响应式——变化自动 dirty 当前组件 */
+export declare function useInView(env: HookEnv, options: UseInViewOptions): UseInViewHandle;
+/** 滚动位置跟踪（全局 scroll 监听 + rAF 节流）：返回响应式 y，变化自动 dirty */
+export declare function useScrollPosition(env: HookEnv, options: UseScrollPositionOptions): UseScrollPositionHandle;

package/dist/ui-dom/hooks/popup.d.ts

@@ -0,0 +1,37 @@
+/**
+ * hooks/popup — 弹层 hooks
+ *
+ * usePopupPosition / usePopup / useOpen / useDialog
+ */
+import type { HookEnv } from './types.ts';
+import type { PopupPositionOptions, PopupPosition, UsePopupOptions, UsePopupHandle } from '../types.ts';
+/** 弹层位置跟踪：滚动/resize 时自动重算 fixed 坐标（0 rect 防护） */
+export declare function usePopupPosition(env: HookEnv, options: PopupPositionOptions): PopupPosition;
+/**
+ * 弹层组合器：收敛 open 状态 + 触发（hover/tap 降级/longpress）+ Escape +
+ * 外部点击 + 定位/视口 clamp + portal。
+ */
+export declare function usePopup(env: HookEnv, options: UsePopupOptions): UsePopupHandle;
+/** 显隐打开状态机（C4）：trigger/focus/blur 协调。默认只开不关 */
+export declare function useOpen(env: HookEnv, options: {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    openOnFocus?: boolean;
+    name?: string;
+}): {
+    readonly open: boolean;
+    setOpen: (v: boolean) => void;
+    triggerProps: {
+        onClick: () => void;
+        onFocus: () => void;
+    };
+};
+/** 全屏对话框组合器：退场状态机 + 滚动锁 + 焦点 trap（基于 usePresence） */
+export declare function useDialog(env: HookEnv, options?: {
+    name?: string;
+}): {
+    readonly phase: "closed" | "open" | "exit";
+    rootRef: (el: HTMLElement | null) => void;
+    panelRef: (el: HTMLElement | null) => void;
+    sync: (open: boolean) => "closed" | "open" | "exit";
+};

package/dist/ui-dom/hooks/stable.d.ts

@@ -0,0 +1,39 @@
+/**
+ * hooks/stable — 基础/稳定 hooks（无共享全局状态依赖）
+ *
+ * useStableRef / useHoverCapable / useReducedMotion / useAnimationEnd /
+ * useLongPress / usePresence / useTween
+ */
+import type { HookEnv } from './types.ts';
+import type { UseLongPressOptions, UseLongPressHandle } from '../types.ts';
+/** 稳定 ref 引用：mount 作用域持有，跨渲染引用恒等（内联 ref 陷阱根治） */
+export declare function useStableRef(_env: HookEnv, init: (el: HTMLElement | null) => void, cleanup?: () => void): (el: HTMLElement | null) => void;
+/** 当前设备是否支持 hover（matchMedia '(hover: hover)'，mount 期一次判定） */
+export declare function useHoverCapable(env: HookEnv): boolean;
+/** 响应式系统偏好（prefers-reduced-motion）。mount 期一次判定 */
+export declare function useReducedMotion(_env: HookEnv): boolean;
+/** 元素动画完成回调（animationend）：stableRef——ref 挂载绑定、卸载清理、引用恒定 */
+export declare function useAnimationEnd(env: HookEnv, cb: () => void, opts?: {
+    once?: boolean;
+}): (node: HTMLElement | null) => void;
+/** 长按手势：pointerdown 按住 duration 触发，提前松开/位移取消，桌面右键兼容 */
+export declare function useLongPress(env: HookEnv, options: UseLongPressOptions): UseLongPressHandle;
+/**
+ * 通用显隐状态机：open → exit → closed（animationend 延迟卸载）。
+ * useDialog 基于它——状态机单点实现。
+ */
+export declare function usePresence(env: HookEnv, options?: {
+    name?: string;
+}): {
+    readonly phase: "closed" | "open" | "exit";
+    ref: (el: HTMLElement | null) => void;
+    sync: (open: boolean) => "closed" | "open" | "exit";
+};
+/** 数值补间：rAF + ease + reduced-motion 直落终值。目标变化自动补间。 */
+export declare function useTween(env: HookEnv, target: number, opts?: {
+    duration?: number;
+    ease?: 'linear' | 'easeOutCubic';
+}): {
+    value: number;
+    reset: (to: number) => void;
+};

package/dist/ui-dom/hooks/test/hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,78 @@
+/**
+ * hooks/types — Hook 运行时上下文（HookEnv）
+ *
+ * hooks 重构：所有 `ctx.ui.useXXX` 的实现从 createUi 移到 src/ui-dom/hooks/，
+ * 签名统一为 `useXXX(env, ...args)`——显式接收 HookEnv（封装 ui 内部能力），
+ * 不再依赖 `this`（ui 对象）与 createUi 闭包。
+ *
+ * ui.ts 的 createUi 组装 env + 薄转发（ctx.ui.useXXX 兼容组件库，实现已在 hooks/）。
+ */
+import type { BrowserEnv } from '../types.ts';
+/** 媒体查询注册表项（跨组件共享——useMedia/useBreakpoint 按 key 去重注册） */
+export interface MediaRegistryItem {
+    mql?: MediaQueryList;
+    handler?: (e: MediaQueryListEvent) => void;
+    mqls?: Array<{
+        mql: MediaQueryList;
+        handler: () => void;
+    }>;
+}
+/** popup 定位 tracker（跨组件共享——全局 scroll/resize 监听重算） */
+export interface PopupTracker {
+    pos: {
+        top: number;
+        left: number;
+    };
+    getEl: () => HTMLElement | null;
+    isOpen: () => boolean;
+    compute: (rect: DOMRect) => {
+        top: number;
+        left: number;
+        width?: number;
+    };
+    panel?: () => HTMLElement | null;
+    margin?: number;
+}
+/** scroll tracker（跨组件共享——useScrollPosition） */
+export interface ScrollTracker {
+    handle: {
+        y: number;
+    };
+    getScroller: () => HTMLElement | Window;
+}
+export interface HookEnv {
+    /** 当前组件 id（ui._selfId / _selfVNode._id 解析） */
+    selfId(): string | undefined;
+    /** 触发渲染（render-only 唯一触发） */
+    render(ids?: string[]): void;
+    /** 浏览器环境（ctx.browser） */
+    browser: BrowserEnv;
+    /** 组件卸载回调注册（hooks 清理用——onComponentUnmountFor）——返回退订函数 */
+    onUnmount(fn: (id: string) => void): () => void;
+    /** 注册表实例（selfId 注册/查询）——结构兼容（第 1 代/vdom 均含 idRegistry） */
+    registry: {
+        idRegistry: Map<string, any>;
+    };
+    /** 跨组件共享：媒体查询注册表 */
+    mediaRegistry: Map<string, MediaRegistryItem>;
+    /** 跨组件共享：popup 定位 tracker */
+    popupTrackers: Map<string, PopupTracker>;
+    /** 跨组件共享：scroll tracker */
+    scrollTrackers: Map<string, ScrollTracker>;
+    /** 渲染保护期（渲染请求被跳过） */
+    isMounting(): boolean;
+    isRendering(): boolean;
+    /** 受控缺回调 warn 去重（跨组件按 name 幂等） */
+    warned: Set<string>;
+    /** useControlled 非受控内部值（按 selfId） */
+    uncontrolledValues: Map<string, any>;
+    /** useControlledInput 内部输入态（按 selfId） */
+    inputStates: Map<string, {
+        keyword: string;
+        selectedLabel: string;
+    }>;
+    /** useOpen 非受控内部打开态（按 selfId） */
+    openStates: Map<string, boolean>;
+    /** 惰性挂载全局 scroll/resize 监听（幂等） */
+    ensurePopupListeners(): void;
+}

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

@@ -1,33 +1,35 @@
 /**
- * weifuwu/ui-dom — 前端路由（UIRouter 纯路由 + uiServe 渲染运行时）
+ * weifuwu/ui-dom — 前端路由 + 渲染运行时（v2 vdom 引擎，render-only）
  *
- * 定稿架构（design/ui-architecture.md + ui-dom-client-align.md）：
- *   req = window.location，res = VNode，uiServe = VDOM（落地）
- *   handler = 异步组件：async (location, ctx) => vnode（$ 有效）
- *   middleware = 两阶段 async（layout 与 SSR 都是中间件）
+ * 渲染运行时 = vdom（第 2 代引擎，design/render-only-plan.md）：
+ * - 渲染触发唯一原语 ctx.ui.render()（无 $ / dirty——无自动渲染）
+ * - 共享状态：createStore + ctx.ui.useExternal
+ * - 命令式挂载：mountCommand/unmountCommand（弹窗中间件在 components 各组件内部）
  *
- * 渲染运行时复制自 client（registry/createUi/render/diff/popup-tracker 局部实例），
- * VNode 契约共享（components 直接复用）。
+ * 定稿架构（design/ui-architecture.md）：req = window.location，res = VNode，
+ * uiServe = VDOM（落地）；handler = 异步组件；middleware = 两阶段 async。
  */
 export { UIRouter } from './router.ts';
 export type { UIRouterOptions, RouteMatch } from './router.ts';
-export { uiServe } from './serve.ts';
-export type { UIServeOptions, UIServeHandle } from './serve.ts';
-export { h, jsx, jsxs, jsxDEV, Fragment, Portal, createPortal, Placeholder, Suspense } from './vnode.ts';
+export { h, jsx, jsxs, jsxDEV, Fragment, Portal, createPortal } from './vnode.ts';
 export type { VNode, VNodeChild, VNodeType, Component } from './vnode.ts';
-export { createReactiveState } from './reactive.ts';
 export { createClientBrowser } from './browser.ts';
-export { mountVNode } from './render.ts';
-export { callRefCleanup } from './render.ts';
 export { animateOut } from './motion.ts';
-export { patchValue } from './diff.ts';
-export { hydrateVNode } from './hydration.ts';
-export { isAsyncComponent, asyncComponent } from './vnode.ts';
 export { api } from './middleware/api.ts';
 export type { ApiClient, ApiOptions, ApiRequestOptions, ApiInjected } from './middleware/api.ts';
 export { auth } from './middleware/auth.ts';
 export type { AuthClient, AuthInjected } from './middleware/auth.ts';
 export { ws } from './middleware/ws.ts';
 export type { WsClient, WsInjected } from './middleware/ws.ts';
-export { ssrPage, serializeData, ssrToString } from './ssr.ts';
 export type { UIRequest, UIResponse, UIHandler, UIMiddleware, UIRouteDef, WfuiContext, } from './types.ts';
+export { uiServe } from './vdom/serve.ts';
+export type { UIServeOptions, UIServeHandle } from './vdom/serve.ts';
+export { patchValue } from './vdom/diff.ts';
+export { hydrateVNode } from './vdom/hydration.ts';
+export { ssrPage, ssrToString, serializeData } from './vdom/ssr.ts';
+export { mountRoot, createVdomContext, mountCommand, unmountCommand, createCommandContainer } from './vdom/mount.ts';
+export { buildVNode } from './vdom/build.ts';
+export { renderValue } from './vdom/render.ts';
+export { createScheduler, type Scheduler } from './vdom/scheduler.ts';
+export { createStore } from './store.ts';
+export type { ExternalStore } from './store.ts';