weifuwu 0.76.0 → 0.77.0

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

@@ -38,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;
@@ -56,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） */
@@ -66,8 +69,9 @@ 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） */
@@ -75,8 +79,9 @@ export interface UsePopupOptions {
     /** 遮罩（默认 false）：渲染全屏 overlay（--wf-overlay，点击遮罩关闭，
      *  模态语义阻断页面交互）。false = 无遮罩 document 外部点击（§5.4 默认）。
      *  遮罩层 z-index = --wf-z-overlay(80) < 面板 --wf-z-popover(120)。
-     *  配合 maskClosable 控制遮罩点击是否关闭。 */
-    mask?: boolean;
+     *  配合 maskClosable 控制遮罩点击是否关闭。
+     *  传 VNode = 自定义遮罩内容（Tour 挖洞高亮遮罩——交互组件自控，不自动 onClick） */
+    mask?: boolean | VNode;
     /** 遮罩点击关闭（默认 true；mask:true 时生效——危险确认 maskClosable=false 防误触） */
     maskClosable?: boolean;
     /** 遮罩面板居中（默认 false；mask:true 时生效）：面板覆盖全屏 flex 居中
@@ -95,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 */
@@ -467,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;
         }) => {
@@ -496,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/vdom/build.d.ts

@@ -7,6 +7,11 @@
  * - 剪枝：已构建 + 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';
@@ -17,18 +22,20 @@ export declare function componentPropsEqual(a: Record<string, any>, b: Record<st
 export declare function mountAsyncComponent(vnode: VNode, ctx: WfuiContext, reg: Registry, opts?: {
     reuse?: VNode;
 }): Promise<{
-    renderFn: (props: VNode['props']) => VNode | null;
+    renderFn: (props: VNode['props']) => Promise<VNode | null>;
     childCtx: WfuiContext;
 }>;
 /**
- * 递归展开组件树（async）：await 工厂 → renderFn → 递归子树。**零 DOM**。
+ * 递归展开组件树：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;
-}): Promise<VNodeChild>;
+}): VNodeChild | Promise<VNodeChild>;

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

@@ -8,17 +8,16 @@
  * 三态 skip：props 同 + 无 dirty + ctx 版本同 → 复用旧 _child（renderFn 不重跑）。
  */
 import type { VNodeChild } from '../vnode.ts';
-/** 递归文本/数组归一化（children 数组展开——嵌套数组扁平化，DOM 范围对齐） */
-export declare function normalizeChildren(c: VNodeChild | undefined | null): VNodeChild[];
+import { normalizeChildren } from '../vnode.ts';
+export { normalizeChildren };
 export interface PatchCtx {
     browser: any;
     registry: import('./registry.ts').Registry;
-    /** 三态 skip 的 dirty 集合（组件 id → true） */
-    /** 已渲染组件（skip 判定——记录到 ctx，供 scheduler 清 dirty） */
-    rendered?: Set<string>;
-    /** 当前 ctx 版本号 */
+    /** 当前 ctx 版本号（三态 skip 版本比较：组件 _ctxVersion !== 当前版本 → 不 skip，
+     *  强制重渲染——bumpCtxVersion 递增后所有组件重跑 renderFn，如 i18n 切换语言） */
     ctxVersion?: number;
-    getCtxVersion?: (id: string) => number;
+    /** force：跳过三态 skip（mountRoot.rerender 全量重跑用） */
+    force?: boolean;
 }
 /**
  * patchValue — 同步 diff 单一节点。

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

@@ -14,7 +14,7 @@
 export { buildVNode } from './build.ts';
 export { renderValue } from './render.ts';
 export { patchValue } from './diff.ts';
-export { createScheduler, type Scheduler } from './scheduler.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';

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

@@ -7,19 +7,18 @@
 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;
+    renderer?: Renderer;
     onError?: (e: unknown) => void;
 }
 export interface MountHandle {
     ctx: WfuiContext;
     registry: Registry;
-    scheduler: Scheduler;
+    renderer: Renderer;
     /** 挂载根组件 */
     mount(comp: Component | VNodeChild): Promise<void>;
     /** 整树强制重渲染（force——测试辅助/手动刷新：renderFn 重跑 + patch） */
@@ -30,11 +29,21 @@ export interface MountHandle {
 export interface VdomContext {
     ctx: WfuiContext;
     registry: Registry;
-    scheduler: Scheduler;
+    renderer: Renderer;
     rootUi: any;
     destroyPopupListeners: () => void;
 }
-/** 组装 vdom 渲染上下文（ctx/registry/scheduler/rootUi——含完整 hooks 转发） */
+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 */

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

@@ -8,6 +8,8 @@
 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

@@ -3,7 +3,7 @@
  *
  * 与第 1 代 serve.ts 的区别（AGENTS.md §4.0 无自动渲染原则）：
  * - 渲染管线：buildVNode（async 预构建 await 全部）→ renderValue/patchValue（同步落地）
- * - 调度：vdom scheduler（无 flush 批处理——$ 赋值直接 fire-and-forget 渲染）
+ * - 调度：vdom renderer（render() 直接执行——await = DOM 已同步）
  * - 动态挂载：buildVNode 阶段 await（无占位/注释/补全回调）
  *
  * 保留公开 API（uiServe/UIServeOptions/UIServeHandle）——迁移无缝。

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

@@ -24,8 +24,8 @@ export interface VNode {
     _remoteEl?: HTMLElement | undefined;
     /** VNode 的 DOM 归属：'local' 在父 DOM 树下，'remote' 在别处 */
     _placement?: 'local' | 'remote';
-    /** 两阶段组件的 render 函数（mount 返回的函数） */
-    _render?: (props: Record<string, unknown>) => VNode | null;
+    /** 两阶段组件的 render 函数（mount 返回的函数——强制异步：props 变化时可 await 数据） */
+    _render?: (props: Record<string, unknown>) => Promise<VNode | null>;
     /** 组件实例 ID（如 '_wf_0'） */
     _id?: string;
     /** 自定义组件 ID（ctx.ui.selfId() 注册，跨组件精准刷新） */
@@ -36,23 +36,25 @@ export interface VNode {
     _parentVNode?: VNode;
     /** 组件输出的第一个 DOM 节点 */
     _refNode?: Node | null;
-    /** 原生 async 组件缓存（vnode 级按实例）：in-flight Promise → resolved renderFn（diff 传递继承） */
-    _asyncDef?: ((props: Record<string, unknown>) => VNode | null) | Promise<((props: Record<string, unknown>) => VNode | null)> | null;
     /** Fragment 展开后的多个直属 DOM 节点范围（diff 对齐用，见 diff.ts） */
     _childNodes?: Node[];
-    /** 组件 mount/render 时的 ctx 版本号（供三态 skip 判定） */
+    /** 组件 renderFn 上次执行时的 ctx 版本号（buildVNode 剪枝 + diff 三态 skip 的版本比较——
+     *  bumpCtxVersion 递增后版本不同 → 强制重跑 renderFn，如 i18n 切换语言） */
     _ctxVersion?: number;
 }
 /**
- * 两阶段异步组件（统一签名——weifuwu 只支持这一种形态）：
+ * 两阶段异步组件（weifuwu 唯一组件形态）：
  *   async (initProps, ctx) => Promise<renderFn>
- * 外层 = mount（一次，可 await 数据），内层 = render（每次 dirty/props 变化，同步）。
+ * 外层 = mount（一次，可 await 数据），内层 = renderFn（每次 dirty/props 变化——**强制异步**，
+ * 可 await 数据；统一异步心智：两阶段都可 await，无「同步组件 vs 异步组件」二元形态）。
  * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
  *
- * 模式 A（design/async-mode-a-plan.md）：主路径 buildVNode await 全部工厂（无占位）；
- * 动态挂载兑底占位 + 局部补全。渲染器按「返回值是 Promise」原生判别。
+ * renderFn 签名：async (props) => Promise<VNode | null>——同步 renderFn 是类型错误
+ * （diff 永不执行 renderFn——渲染器在 buildVNode 阶段 await，同步上下文拿不到 vnode）。
+ * 渲染器按「返回值是 Promise」判别（主路径 buildVNode await 全部工厂 + renderFn）。
  */
-export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<((props: P) => VNode | null) | null>;
+export type RenderFn<P> = (props: P) => Promise<VNode | null>;
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<RenderFn<P> | null>;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;
@@ -63,6 +65,9 @@ export declare function jsxDEV(type: VNodeType, props: Record<string, any> | nul
 /** `h`（hyperscript）支持 variadic children: `h('div', {class:'x'}, child1, child2)` */
 export declare function h(type: VNodeType, props: Record<string, any> | null, ...children: VNodeChild[]): VNode;
 export declare function isNative(vnode: VNode): boolean;
+/** 递归文本/数组归一化（children 数组展开——嵌套数组扁平化，DOM 范围对齐）。
+ *  栈展开（索引遍历替代 shift/unshift 头部操作——长数组 O(n) 而非 O(n²)）；逆序入栈 + pop 保持原顺序 */
+export declare function normalizeChildren(c: VNodeChild | undefined | null): VNodeChild[];
 export declare function isComponent(vnode: VNode): boolean;
 export declare function isFragment(vnode: VNode): boolean;
 export declare function isPortal(vnode: VNode): boolean;

package/docs/components.md

@@ -2,7 +2,7 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-113 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+113 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`（两阶段组件，与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步），引用 `--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 组件/类型纪律逐步指南。
@@ -133,9 +133,9 @@ import 'weifuwu/components/style.css'   // 包含 Token + 58 布局原语 + 136
 
 ```
 mount ──────────────────────────────────────────
-  const Counter = (_init, ctx) => {       ← mount（只一次）
+  const Counter = async (_init, ctx) => {   ← mount（只一次，可 await）
     let count = 0                           ← 初始化状态
-    return (props) => {                     ← render 函数
+    return async (props) => {               ← renderFn（强制异步）
       // ...                                 ← 每次 dirty/props 变化执行
     }
   }
@@ -149,7 +149,7 @@ ref ─────────────────────────
   })
 
 props 变化 ─────────────────────────────────────
-  return (props) => {
+  return async (props) => {
     // 每次 render 都收到最新 props           ← 相当于 onupdate
     if (props.value !== prevValue) { ... }
   }

package/docs/custom-components.md

@@ -13,31 +13,51 @@
 import { h, type Component } from 'weifuwu/ui-dom'
 
 // Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
-const Badge: Component<{ text: string; color?: string }> = () =>
-  (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
+const Badge: Component<{ text: string; color?: string }> = async () =>
+  async (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
 ```
 
-- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => VNode` 每次渲染执行
-- 不需要状态就不调 `ctx.ui.$()`；需要交互才用
+- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => Promise<VNode>` 每次渲染执行（renderFn 强制异步——可 await 数据）
+- 有状态组件用闭包 `let` + 事件里 `ctx.ui.render()`（render-only）；不需要渲染的状态不调 `render()`
+
+### mount 与 render 的职责（事件函数写在哪层）
+
+| | mount（外层工厂，一次） | render（内层 renderFn，每次） |
+|---|---|---|
+| 职责 | 初始化状态 / 订阅 / 定时器 / **定义依赖稳定引用的回调** | 读最新 props / 派生数据 / **定义依赖它们的回调** / 输出视图 |
+| 可访问 | `initProps`（首次）、`ctx`、mount `let`、稳定 handle | 最新 `props`、mount 闭包、`ctx` |
+| 事件函数 | **只依赖稳定引用**（ctx / mount let / 稳定 handle 如 useChat 的 `chat`）→ mount 定义，天然引用恒等 | 依赖最新 props / 派生状态（如 Table 的 `rowSelection`、Menu 的 `openSet`）→ render 内定义（闭包捕获最新值） |
+
+```tsx
+const AiChat = async (initProps, ctx) => {
+  const chat = initProps.chat           // 稳定 handle（useChat 返回，引用不变）
+  const onSend = () => chat.send()      // ✅ mount 定义：只依赖稳定引用——引用恒等，零重绑
+  return async (props) => {
+    const onSelect = (k: string) => props.onSelect?.(k)   // ✅ render 定义：依赖最新 props——闭包捕获当前值
+    return h('button', { onClick: onSelect }, '选')
+  }
+}
+```
+
+**规则**：回调只依赖 ctx / mount `let` / 稳定 handle → **mount 定义**（天然稳定，不重绑）；依赖最新 props / 派生数据 → **render 内定义**（闭包捕获最新值；引用变化导致事件重绑是**正确性要求**——必须读最新状态，框架不做稳定引用魔法）。
 
 ## 1. 有状态组件
 
 ```tsx
-const Toggle: Component = (_init, ctx) => {
-  const $ = ctx.ui.$()        // 深度 Proxy：赋值自动触发渲染（微任务批量）
-  $.on = false
+const Toggle: Component = async (_init, ctx) => {
+  let on = false        // 普通对象状态（render-only：无 $ Proxy）
 
-  return (props) => h('button', {
+  return async (props) => h('button', {
     class: 'my-toggle',
-    onClick: () => $.on = !$.on,
-  }, $.on ? '开' : '关')
+    onClick: () => { on = !on; ctx.ui.render() },   // 改状态后显式 render()
+  }, on ? '开' : '关')
 }
 ```
 
 | 状态类型 | 存放位置 | 触发渲染 |
 |---------|---------|---------|
-| 自动 UI 状态 | `$.xxx` | 赋值自动（微任务） |
-| 手动 UI 状态 | 闭包 `let` | 需 `ctx.ui.render()` |
+| 组件内部状态 | 闭包 `let` | 改后调 `ctx.ui.render()` |
+| 共享状态 | `createStore` + `ctx.ui.useExternal()` | store 变更自动 |
 | 内部缓存 | 闭包 `let` | 不触发 |
 
 ## 2. 带弹层的组件（最高频的自定义场景）
@@ -45,23 +65,22 @@ const Toggle: Component = (_init, ctx) => {
 用 `ctx.ui.usePopup`——一个组合器收敛 open 状态 + 触发（hover→tap 降级/longpress）+ Escape + 外部点击 + 定位/视口 clamp + portal：
 
 ```tsx
-const MyPopover: Component<{ content: string }> = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.open = false
+const MyPopover: Component<{ content: string }> = async (_init, ctx) => {
+  let open = false
   let wrapEl: HTMLElement | null = null
   const wrapRef = (el: HTMLElement | null) => { wrapEl = el }
 
   const popup = ctx.ui.usePopup({
     trigger: 'hover',          // 触屏自动降级 tap（useHoverCapable 内部判定）
     el: () => wrapEl,          // 锚点
-    isOpen: () => $.open,
-    setOpen: (v) => { $.open = v },   // $ 赋值自动渲染
+    isOpen: () => open,
+    setOpen: (v) => { open = v; ctx.ui.render() },   // 改状态 + render
     width: 320,                // 自动 clamp 视口
     closeOnOutside: true,      // 外部点击关闭（默认）
     closeOnEscape: true,       // Escape 关闭（默认，document 级——portal 焦点也生效）
   })
 
-  return (props) =>
+  return async (props) =>
     h('span', { class: 'anchor', ref: wrapRef, ...popup.wrapProps },
       props.children,
       popup.portal(h('div', { class: 'wf-panel' }, props.content)),
@@ -73,54 +92,62 @@ const MyPopover: Component<{ content: string }> = (_init, ctx) => {
 
 ## 3. 对话框类组件（Modal 系）
 
-全屏对话框（焦点 trap + 滚动锁 + 退场动画）不在 usePopup 范围——用 **`ctx.ui.useDialog`** 组合器（Modal/Drawer 同款：退场状态机 + 滚动锁 + 焦点 trap + animationend 卸载）：
+全屏对话框（焦点 trap + 滚动锁 + 退场动画）是 usePopup 的**会话级模态模式**（`presence/trapFocus/lockScroll/positioning: 'none'`——Modal/Drawer 同款）：
 
 ```tsx
-import { createPortal } from 'weifuwu/ui-dom'
-
-const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx) => {
-  const dialog = ctx.ui.useDialog({ name: 'MyDialog' })   // mount 创建
-
-  return (props) => {
-    const phase = dialog.sync(!!props.open)                // render 同步 open
+const MyDialog: Component<{ open: boolean; onClose: () => void }> = async (_init, ctx) => {
+  let latestOpen = false
+  const popup = ctx.ui.usePopup({
+    presence: true,      // 退场状态机（open → exit → closed + animationend）
+    trapFocus: true,     // 焦点 trap（面板挂载锁定/卸载归还）
+    lockScroll: true,    // 滚动锁（打开锁 / 面板卸载释放）
+    positioning: 'none', // 组件自定义定位（.wf-modal inset:0 居中）
+    closeOnOutside: false, closeOnEscape: false, // 关闭语义组件自控
+    isOpen: () => latestOpen,
+    setOpen: () => {},
+  })                     // mount 创建
+
+  return async (props) => {
+    latestOpen = !!props.open
+    const phase = popup.sync!(latestOpen)                // render 同步 open
     if (phase === 'closed') return null
 
-    return createPortal(h('div', {
+    return popup.portal(h('div', {
       class: 'wf-overlay',
       onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() },
     }, h('div', {
       class: `wf-modal ${phase === 'exit' ? 'wf-modal--exit' : 'wf-modal--enter'}`,
-      ref: dialog.panelRef,                                // 焦点 trap 目标
       onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() },  // Escape 语义组件层
-    }, props.children)), document.body)
+    }, props.children)), 'modal')   // portalKey 语义化（#__wf_portal 容器标记）
   }
 }
 ```
 
-> `dialog.rootRef` 挂到 portal 根（lockScroll + animationend 退场监听）；`panelRef` 挂到面板（trapFocus）。
-> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/ui-dom` 导出（特殊场景组装用）。
+> **ref 接线**：`trapFocus`/`lockScroll`/presence 退场监听全部由 usePopup 内部接线到 portal 面板
+> （`portalPanelRef`——content 的 `ref` prop 会被转发调用）——组件层无需手挂 `rootRef`/`panelRef`。
+> 低层原语 `trapFocus`/`lockScroll` 已收编为 usePopup 内部实现（**不对外导出**——AGENTS.md §5.4）；
+> `animateOut` 仍从 `weifuwu/ui-dom` 导出（非弹窗动画场景用）。
 
 ## 4. AI 组件
 
 会话语义由 `ctx.ui.useChat` 提供（消息/流式/工具/审批/stop/retry 全封装），返回的 handle 与 `$` 同一容器：
 
 ```tsx
-const ChatPanel: Component = (_init, ctx) => {
-  const $ = ctx.ui.useChat({
+const ChatPanel: Component = async (_init, ctx) => {
+  const chat = ctx.ui.useChat({
     url: '/api/chat',
     approveUrl: '/api/approve',   // HITL 审批上行（缺省 approve() 只清卡片）
     body: (messages) => ({ messages, mode: 'agent' }),
   })
 
   return () => h('div', { class: 'chat' },
-    $.messages.map((m) => h('div', { class: `msg-${m.role}` }, m.content)),
-    h('input', { value: $.input, onInput: (e: any) => $.input = e.target.value }),
-    h('button', { onClick: () => $.send() }, $.streaming ? '…' : '发送'),
+    h(AiChat, { chat }),                    // 标准界面：输入/消息/流式/工具卡全内置
+    h('button', { onClick: () => chat.send() }, chat.streaming ? '…' : '发送'),
   )
 }
 ```
 
-**共享 `$` 给子组件**（如 `<AiChat chat={$} />`）：父组件 dirty 不驱动子组件（三态 skip），子组件 mount 期 `initProps.chat.__watch?.(() => ctx.ui.dirty())` 自订阅。
+**共享 handle 给子组件**（如 `<AiChat chat={chat} />`）：会话 handle 带 `subscribe(cb)`——子组件 mount 期 `ctx.ui.useExternal(initProps.chat)` 自订阅（AiChat 已内置），会话状态变化自动重渲染订阅组件。
 
 ## 5. 异步组件（数据声明在工厂层）
 
@@ -129,29 +156,27 @@ const ChatPanel: Component = (_init, ctx) => {
 ```tsx
 const UserCard = async (initProps, ctx) => {
   const user = await ctx.data.get(`/api/user/${initProps.userId}`)  // 三场景：SSR→__DATA__ / hydration 种子 / SPA fetch
-  const $ = ctx.ui.$()
-  $.liked = false
-  return (props) => h('div', {}, user.name, h('button', { onClick: () => $.liked = !$.liked }))
+  let liked = false
+  return async (props) => h('div', {}, user.name, h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }))
 }
 ```
 
-- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；动态挂载兑底占位 + 局部补全；SSR 直接 await
+- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；运行时首次挂载的 async 组件在 buildVNode 阶段 await（无占位/补全回调）；SSR 直接 await
 - 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
-- 占位显示：动态挂载的 async 组件占位 = 注释节点，resolve 后局部补全（Suspense 边界已裁剪）
-- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
+- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `let` + fetch + `render()`
 
 ## 6. 类型纪律（编译期防线）
 
 ```tsx
-const Badge: Component<{ variant: 'primary' | 'muted' }> = () =>
-  (props) => h('span', { class: `badge-${props.variant}` }, props.children)
+const Badge: Component<{ variant: 'primary' | 'muted' }> = async () =>
+  async (props) => h('span', { class: `badge-${props.variant}` }, props.children)
 
 // 负例：variant 传错 → tsc 报错（@ts-expect-error 是类型流测试的写法）
 // @ts-expect-error variant 不允许 'bogus'
 const bad: { variant: 'primary' | 'muted' } = { variant: 'bogus' }
 
 // ctx 注入声明（C 泛型）：声明了才能用，未声明编译期报错
-const Page: Component<{}, { api: ApiInjected['api'] }> = (_init, ctx) => {
+const Page: Component<{}, { api: ApiInjected['api'] }> = async (_init, ctx) => {
   ctx.api.get('/x')
   return () => null
 }
@@ -192,8 +217,8 @@ render() // 重渲染，状态保留
 新受控组件**必须**用 `ctx.ui.useControlled`（受控判定 + 缺回调 warn 一次 + 非受控内部状态跨渲染保持）：
 
 ```tsx
-const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = (_init, ctx) => {
-  return (props) => {
+const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = async (_init, ctx) => {
+  return async (props) => {
     const ctrl = ctx.ui.useControlled<boolean>({ value: props.active, onChange: props.onChange, name: 'CollapseItem' })
     return h('button', {
       onClick: () => ctrl.setValue(!(ctrl.value ?? false)),   // 受控走 onChange；非受控内部状态
@@ -221,10 +246,10 @@ const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => voi
 > SSR 安全（shim 安全默认）+ 测试 mock 单点 + 环境差异隔离。
 
 ```tsx
-const MyComp: Component = (_init, ctx) => {
+const MyComp: Component = async (_init, ctx) => {
   // mount 层取 browser（ctx.browser 优先，测试/无注入环境 fallback jsdom）
   const browser = ctx.browser ?? createClientBrowser()
-  return (props) =>
+  return async (props) =>
     h('button', {
       onClick: () => {
         // 复制/查询/存储/滚动——全部经 browser
@@ -266,9 +291,8 @@ const MyComp: Component = (_init, ctx) => {
 
 ## 已知边界（诚实裁剪）
 
-- `usePopup` 覆盖浮层（Tooltip/Popover/Dropdown/Mentions/Cascader/ContextMenu）；**全屏对话框**（Modal/Drawer）用 useDialog（Escape 语义留组件层）；Command/Img preview 保持独立实现
+- `usePopup` 是**统一弹窗能力层**：锚定浮层（Tooltip/Popover/Dropdown/Select/AutoComplete/Mentions/Cascader/ContextMenu/NavMenu/Popconfirm/TreeSelect）+ 会话级模态（Modal/Drawer/Confirm——presence/trapFocus/lockScroll/positioning 'none'，Escape 语义留组件层）+ mask 模式（Command/Img preview/Tour——mask/maskCentered/自定义 mask VNode）+ focus 触发（DatePicker）+ positioning 'none' 常驻容器（Toast/Notification）——**全部弹窗单一入口**
 - **事件监听纪律**：组件库内部浏览器事件监听**统一走 `ctx.ui.useXXX`**——滚动/观察/弹层/对话框/快捷键/拖拽/DnD 全覆盖：
-  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（ContextMenu 自由定位）、`useDialog`（Modal/Drawer）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
-- 唯一保留：**DatePicker 元素级 `animationend`**（入场动画完成后坐标 settle——与 usePopup panelRef/motion.animateOut 同款框架基础设施，非浏览器全局事件）
-- **Select/DatePicker** 是 inline/absolute 菜单（自适宽），不迁移 usePopup——菜单直接挂在锚点下
+  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（弹窗统一——ContextMenu 自由定位 + Modal/Drawer 模态模式 + mask 遮罩）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
+- **唯一保留 usePopupPosition 独立使用**：Affix / Chart（坐标工具——非弹窗组合器，滚动跟随自动）
 - `createReactiveState` 已导出：组件外建全局 store（`createReactiveState(() => {})` + `$.__watch(cb)` 订阅）