weifuwu 0.76.0 → 0.78.0

package/docs/frontend.md

@@ -6,7 +6,7 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-零外部 npm 运行时依赖。组件签名：`(initProps, ctx) => (props) => VNode`（两阶段模型，外层 mount 只一次，内层 render 每次变化时执行）。无状态组件可简写为 `() => () => VNode`。
+零外部 npm 运行时依赖。组件签名：`async (initProps, ctx) => (props) => Promise<VNode>`（两阶段模型，外层 mount 只一次可 await 数据，内层 renderFn 每次变化时执行——强制异步）。同步组件已不支持；无状态组件可简写为 `async (_init) => (props) => VNode`。
 
 构建配置（esbuild）：
 
@@ -54,12 +54,12 @@ const handle = uiServe(app, { root: '#root' })
 import type { Component, WfuiContext } from 'weifuwu/ui-dom'
 
 // 两阶段组件：mount（只一次）→ render（每次 dirty/props 变化）
-const Counter: Component = (_init, ctx) => {
+const Counter: Component = async (_init, ctx) => {
   // ── mount ──
   let count = 0
 
   // ── render ──
-  return (props) =>
+  return async (props) =>
     h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
 }
 
@@ -82,7 +82,7 @@ const DeckCard: Component<DeckCardProps> = (_init, ctx) =>
 // <DeckCard title="x" pages="8" />     ✗ 编译期报错
 
 // ② ctx 注入声明：use(api()).use(router()) 后组件声明依赖，ctx 直接访问
-const Home: Component<{}, ApiInjected & RouteInjected> = (_init, ctx) => {
+const Home: Component<{}, ApiInjected & RouteInjected> = async (_init, ctx) => {
   ctx.api.get('/users')   // ✓ 有类型
   ctx.app.navigate('/x')  // ✓ 有类型
   return () => <h1>Home</h1>
@@ -104,7 +104,7 @@ uiServe(app, { root: '#root' })  // 类型累积完整（UIRouter<C & O>）
 | render 阶段 | 内层函数每次 dirty/props 变化时执行，返回 VNode |
 | 无 class | 无 `this`，无实例方法 |
 | 无 hook | 无 `useState` / `useEffect` / `useMemo` |
-| 状态 | 闭包变量 + `ctx.ui.render()` 手动触发，或 `ctx.ui.$()` 响应式容器 |
+| 状态 | 闭包变量 `let` + `ctx.ui.render()` 手动触发；跨组件共享用 `createStore()` + `ctx.ui.useExternal()` |
 | ref 引用 | `ref={el => { if (el) init; else cleanup }}` 获取 DOM |
 
 ### JSX 工厂
@@ -184,18 +184,18 @@ await browser.copyText(text)
 | `useAsync()` | `useAsync(fetcher)` | 异步取数：`data/loading/error` 响应式 + `reload()` |
 | `useControlled()` | `useControlled({ value, onChange, name })` | 受控/非受控统一：受控判定 + 缺回调 warn + 内部状态跨渲染保持 |
 | `useStableRef()` | `useStableRef(init, cleanup?)` | 稳定 ref 引用（根治内联 ref 陷阱） |
-| `useDialog()` | `useDialog({ name })` | 全屏对话框：退场状态机 + 滚动锁 + 焦点 trap（Modal/Drawer 同款） |
+| `usePopup()` 会话级模态 | `usePopup({ presence, trapFocus, lockScroll, positioning })` | **统一弹窗能力**：锚定浮层 + 会话级模态（Modal/Drawer 同款——退场状态机 + 滚动锁 + 焦点 trap + 居中定位）——一个入口按 options 组合 |
 | `useGlobalKey()` | `useGlobalKey(handler)` | 全局键盘监听（window keydown：mount 注册 + 卸载清理） |
 | `useDrag()` | `useDrag({ onMove, onStart?, onEnd? })` | 指针拖拽（pointerdown 捕获 → window move delta / up 释放） |
 | `useDragDrop()` | `useDragDrop({ onDrop, onDragOver?, onDragLeave? })` | 原生 DnD（drop/dragover/dragleave + preventDefault，dropProps spread） |
 | `useReducedMotion()` | `useReducedMotion()` | 响应式系统偏好（JS 动画侧跳过；CSS 动画已有全局降级） |
 | `useAnimationEnd()` | `useAnimationEnd(cb, { once? })` | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定） |
 | `useTween()` | `useTween(target, { duration?, ease? })` | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset） |
-| `usePresence()` | `usePresence({ name? })` | 通用显隐状态机（open→exit→closed，animationend 延迟卸载；useDialog 是其特例） |
+| `usePresence()` | `usePresence({ name? })` | 通用显隐状态机（open→exit→closed，animationend 延迟卸载；usePopup presence 模式内部使用） |
 | `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
 | `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
 | `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
-| `usePopup()` | `usePopup(opts)` | **弹层组合器**：触发（hover/tap 降级/longpress）+ Escape + 外部点击 + 定位/clamp + portal |
+| `usePopup()` | `usePopup(opts)` | **统一弹窗能力层**：触发（hover/tap 降级/longpress）+ Escape + 外部点击 + 定位/clamp + portal + 会话级模态（presence/trapFocus/lockScroll/positioning none——Modal/Drawer 同款） |
 | `useHoverCapable()` | `useHoverCapable()` | 设备是否支持 hover（`matchMedia '(hover: hover)'`），触屏降级判断 |
 | `useLongPress()` | `useLongPress({ onLongPress, duration })` | 长按手势（pointer 事件 + 位移取消 + 桌面右键兼容） |
 | `useVisualViewport()` | `useVisualViewport()` | 可视视口跟踪（键盘弹起/缩放），`{ height, offsetTop, keyboardOpen }` 响应式 |
@@ -208,12 +208,11 @@ await browser.copyText(text)
 
 | API | 触发时机 | 渲染方式 | 作用域 | 使用场景 |
 |------|---------|---------|--------|---------|
-| `$.x = val` | 赋值后自动 | 微任务批量（异步） | 当前组件 | **日常 UI 状态** — 表单输入、切换开关、异步数据加载等 |
-| `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | 当前/指定 | **绕过 Proxy 后手动标记** |
-| `ctx.ui.render()` | 主动调用 | 立即同步 | 当前/指定 | **需要立即拿到最新 DOM** — DOM 测量、动画触发 |
-| `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
-| `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动 dirty |
-| `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动 dirty |
+| `ctx.ui.render()` | 主动调用 | 异步落地（fire-and-forget，`await` 可精确等待） | 当前组件 | **唯一渲染触发** — 改状态后调用；`await` 后拿最新 DOM（测量/动画） |
+| `ctx.ui.render(['id'])` | 主动调用 | 异步落地 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
+| `ctx.ui.useExternal(store)` | 订阅共享状态 | store 变更自动重渲染（unmount 退订） | 当前组件 | **跨组件共享状态** — createStore 唯一消费通道 |
+| `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动重渲染 |
+| `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动重渲染 |
 | `ctx.ui.usePopupPosition()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **弹层坐标跟随** — scroll/resize 时自动重算 fixed 坐标 |
 | `ctx.ui.usePopup()` | 注册监听 | 事件驱动 + document 监听 | 当前组件 | **弹层组合器** — 触发 + Escape + 外部点击 + 定位/clamp + portal（移动端友好由构造保证） |
 | `ctx.ui.useHoverCapable()` | mount 期判定 | 一次 matchMedia | 当前组件 | **hover 能力检测** — 触屏降级 tap 判断 |
@@ -222,89 +221,80 @@ await browser.copyText(text)
 | `ctx.ui.useInView()` | 注册监听 | IO 合成器线程评估 | 当前组件 | **可见性观察**（IO 封装，无 scroll-linked 警告）— Affix/BackTop/InView 统一使用；rootMargin/threshold 支持函数 |
 | `ctx.ui.useScrollPosition()` | 注册监听 | 全局 scroll + rAF 节流 | 当前组件 | **滚动位置跟踪** — `y` 响应式（视口/内部容器通用），Affix/VirtualList 使用 |
 
-`render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
+`render()` 无参 = 当前组件（闭包绑定），传参 = 指定组件列表。hooks（useMedia/useInView 等）是事件驱动重渲染——与"赋值自动"本质不同。
 
-### 闭包变量 + `ctx.ui.render()`（简单场景）
+### 闭包变量 + `ctx.ui.render()`（唯一状态模式）
 
 ```tsx
-const Counter: Component = (_init, ctx) => {
+const Counter: Component = async (_init, ctx) => {
   let count = 0
-  return (props) =>
+  return async (props) =>
     h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
 }
 ```
 
-适合状态极少的简单组件。每次修改后手动调用 `ctx.ui.render()` 同步刷新 DOM。
+**render-only 唯一规则**：渲染只发生在 `render()` 调用处（design/render-only-plan.md）——
+状态是普通对象（`let` / `createStore`），**没有 `$` Proxy、没有赋值自动渲染**。改状态后必须显式 `ctx.ui.render()`。
 
-### `ctx.ui.$()` — 响应式 Proxy（推荐首选）
+### `createStore` + `ctx.ui.useExternal()` — 跨组件共享状态
 
-`ctx.ui.$()` 返回**深度 Proxy** 容器。任意层级赋值操作自动触发渲染（微任务批量合并）：
+需要多个组件共享同一状态时（登录态、主题、全局缓存），用 `createStore`（`weifuwu/ui-dom`）订阅：
 
 ```tsx
-const FormPage: Component = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.email = ''
-  $.loading = false
-  return (props) =>
-    h('input', {
-      value: $.email,
-      onInput: (e: any) => { $.email = e.target.value }
-    })
-}
-```
-
-**深度 Proxy 拦截**：
-- `$.x = val` → 自动排队重渲染
-- `$.obj.a = 1` → 自动 dirty（嵌套对象递归包装）
-- `$.arr.push(val)` / `$.arr[0].x = y` → 自动 dirty（数组变异 + 嵌套属性拦截）
-- `delete $.x` → 自动 dirty
-- 每个组件实例独立 Proxy，同名变量不冲突
+// 模块级单例（或组件内 createStore 传递）
+const store = createStore({ user: null, theme: 'light' })
 
-**注意**：mount/render 中 `$.x = val` **不触发渲染**，仅事件/timer/Promise.then 中生效。这是有意设计——初始化和 mount 阶段设置状态不应触发额外渲染。
+const NavBar: Component = async (_init, ctx) => {
+  const state = ctx.ui.useExternal(store)   // 订阅：store 变更 → 自身自动重渲染
+  return async (props) => h('div', { class: 'nav' }, state.user?.name ?? '未登录')
+}
 
-**何时用 `$`**：所有需要触发 UI 重新渲染的状态。90% 以上的场景用 `$` 就够。
+// 任意位置更新（写入方不需要知道谁在订阅）：
+store.set({ theme: 'dark' })         // 合并写 + 通知
+store.update((s) => { s.user = user })  // 可变写 + 通知
+store.notify()                       // 手动通知
+```
 
-**何时不用**：
-- 不需要触发渲染的内部缓存（用闭包变量 `let`）
-- 简单组件只有一两个状态变量（闭包变量 + `render()` 更轻量）
+- `useExternal` 在 mount 阶段订阅、unmount 自动退订（无需手动清理）
+- `store.state` 是普通对象（非 Proxy）——渲染期读最新值，无隐式触发
+- SSR 无害：服务端 shim 返回 `store.state` 只读不订阅
 
 ### 响应式自适应组件
 
 #### `ctx.ui.useMedia(query, callback)` — 响应式媒体查询
 
-注册媒体查询监听，值变化时自动调用 callback（callback 内赋值 `$` 触发 dirty）：
+注册媒体查询监听，值变化时自动重渲染当前组件（回调内改状态 + `ctx.ui.render()`）：
 
 ```tsx
-const Card = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.isMobile = false
-  // 立即回调一次（取当前值），之后变化时自动重新回调
-  ctx.ui.useMedia('(max-width: 640px)', (v) => { $.isMobile = v })
-
-  return (props) => (
-    <div class={$.isMobile ? 'wf-stack' : 'wf-row'}>
-      {!$.isMobile && <Sidebar />}
+const Card = async (_init, ctx) => {
+  let isMobile = false
+  // 立即回调一次（取当前值），之后变化时自动重渲染
+  ctx.ui.useMedia('(max-width: 640px)', (v) => { isMobile = v; ctx.ui.render() })
+
+  return async (props) => (
+    <div class={isMobile ? 'wf-stack' : 'wf-row'}>
+      {!isMobile && <Sidebar />}
       <Content />
     </div>
   )
 }
 ```
 
-`callback` 在 mount 时立即执行一次，之后断点变化时再次执行。赋值给 `$` 的属性自动触发渲染。
+`callback` 在 mount 时立即执行一次，之后断点变化时再次执行。回调里改状态后调 `ctx.ui.render()` 触发渲染（hooks 内部已封装——组件内通常无需手动 render）。
 
 #### `ctx.ui.useBreakpoint(callback)` — 命名断点
 
 预设三个断点名称：`mobile`（<640px）、`tablet`（640-1023px）、`desktop`（≥1024px）：
 
 ```tsx
-const Layout = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  ctx.ui.useBreakpoint((vp) => { $.vp = vp })
-
-  return (props) =>
-    <div class={`sidebar-${$.vp}`}>
-      {$.vp === 'mobile' ? <BottomNav /> : <SideNav />}
-      {$.vp === 'mobile' ? <MobileContent /> : <Content />}
+const Layout = async (_init, ctx) => {
+  let vp = 'desktop'
+  ctx.ui.useBreakpoint((next) => { vp = next; ctx.ui.render() })
+
+  return async (props) =>
+    <div class={`sidebar-${vp}`}>
+      {vp === 'mobile' ? <BottomNav /> : <SideNav />}
+      {vp === 'mobile' ? <MobileContent /> : <Content />}
     </div>
 }
 ```
@@ -314,7 +304,7 @@ const Layout = (_init, ctx) => {
 ```tsx
 ctx.ui.useBreakpoint(
   { narrow: '(max-width: 480px)', wide: '(min-width: 1200px)' },
-  (vp) => { $.size = vp },
+  (vp) => { size = vp; ctx.ui.render() },
 )
 ```
 
@@ -322,8 +312,10 @@ ctx.ui.useBreakpoint(
 
 解决弹出层（Popover / Tooltip / Dropdown / DatePicker 等）在 **页面滚动 / 窗口缩放后不跟随触发元素** 的问题。基于 `position: fixed` + `getBoundingClientRect()`（视口坐标）的弹层，滚动后坐标需要重算——本 API 用全局 scroll/resize 监听（rAF 节流）自动重算并精准刷新当前组件。
 
+> **使用场景**：`usePopup` 内部已集成 usePopupPosition（弹窗组件无需直接使用）；本 API 供**坐标工具**独立使用（Affix 阈值重算 / Chart tooltip）或**自定义弹层**场景。
+
 ```tsx
-const DatePicker = (_init, ctx) => {
+const CustomPopup = async (_init, ctx) => {
   let show = false
   let inputEl: HTMLElement | null = null
   let prevOpen = false
@@ -335,7 +327,7 @@ const DatePicker = (_init, ctx) => {
     compute: (r) => ({ top: r.bottom + 4, left: r.left }),  // rect → 坐标
   })
 
-  return (props) => {
+  return async (props) => {
     const isOpen = show
     // 打开瞬间算一次初始坐标（受控/非受控统一覆盖）
     if (isOpen && !prevOpen) pos.refresh()
@@ -368,12 +360,14 @@ const DatePicker = (_init, ctx) => {
 - **hover 触发在触屏自动降级为 tap**（内部 `matchMedia '(hover: hover)'` 判定）
 - **Escape 关闭是 document 级**——焦点在 portal 弹层内按 Escape 也能关
 - **外部点击关闭**（document mousedown，点弹层内部不关）
-- **宽度自动 clamp 视口**（≤ `100vw - 32px`，375px 屏不横向溢出）
+- **宽度自动 clamp 视口**（≤ `100vw - 32px`，375px 屏不横向溢出）；`width` 支持 getter（DatePicker 跟随 trigger 宽）
 - **定位 + 视口夹紧**（复用 `usePopupPosition`，超高/超宽面板平移回视口）
+- **mask 遮罩**（`mask: true`——全屏遮罩 + 点击关闭；`maskCentered` 全屏居中——Modal 缩放预览/Command 面板；`mask: VNode` 自定义遮罩内容——Tour 挖洞高亮）
+- **trigger `'focus'`**（DatePicker）——focus 开 + blur 延迟关（`closeDelay` 窗口内面板交互生效）
 - 支持受控（`open`/`onOpenChange`）、动态 props（`placement`/`trigger`/`openDelay` 支持 getter）
 
 ```tsx
-const Tooltip = (_init, ctx) => {
+const Tooltip = async (_init, ctx) => {
   let show = false
   let wrapEl: HTMLElement | null = null
   const wrapRef = (el) => { wrapEl = el }
@@ -389,7 +383,7 @@ const Tooltip = (_init, ctx) => {
     openDelay: () => delay,      // hover 延迟（HoverCard 用）
   })
 
-  return (props) => h('div', { ref: wrapRef, ...popup.wrapProps }, [
+  return async (props) => h('div', { ref: wrapRef, ...popup.wrapProps }, [
     props.children,
     popup.portal(h('div', { class: 'wf-tooltip' }, props.content), 'tooltip'),
   ].filter(Boolean))
@@ -397,12 +391,15 @@ const Tooltip = (_init, ctx) => {
 ```
 
 - `popup.wrapProps` — 触发 + Escape + focus 处理，spread 到包装/触发元素
-- `popup.portal(content, portalKey)` — 定位 + clamp + portal（挂载 `#__wf_portal`），关闭时返回 null；自动附加 `wf-popup` 基类
+- `popup.portal(content, portalKey)` — 定位 + clamp + portal（挂载 `#__wf_portal`），关闭时返回 null；自动附加 `wf-popup` 基类；`positioning: 'none'` 时不加坐标（只 `position: fixed`——组件自定义定位，Modal/Toast 用）
 - `popup.open` / `popup.setOpen()` — 状态读取与设置
+- `popup.sync(open)` / `popup.phase` — 会话级模态模式（`presence: true`）render 期同步打开状态 + 读退场 phase（`'closed' | 'open' | 'exit'`——exit 阶段保留退场动画）
+
+**会话级模态模式**（Modal/Drawer/Confirm 同款）：`presence: true`（退场状态机）+ `trapFocus: true`（焦点 trap）+ `lockScroll: true`（滚动锁）+ `positioning: 'none'`（自定义定位）——全部能力 usePopup 内部实现（`trapFocus`/`lockScroll` 不对外导出）。
 
-**边界（诚实裁剪）**：Modal/Drawer 全屏对话框不进 `usePopup`（focus-trap/scroll-lock/退场状态机生命周期不同，各自实现）。
+**已迁移组件（全部弹窗统一 usePopup 单一入口）**：Tooltip / HoverCard / Popover / Dropdown / Menubar / Mentions / Cascader / ContextMenu / Select / AutoComplete / NavMenu / Popconfirm / DatePicker（focus 触发）/ Tour（mask 自定义遮罩）/ Toast / Notification（positioning 'none' 常驻容器）/ Modal / Drawer / Confirm / Command / Img（mask 全屏遮罩）/ TreeSelect。
 
-已迁移组件：**Tooltip / HoverCard / Popover / Dropdown / Menubar / Mentions / Cascader / ContextMenu**（长按双通道）。
+**usePopupPosition 独立用户**：Affix / Chart（tooltip）——坐标工具（非弹窗组合器），滚动跟随自动。
 
 #### `ctx.ui.useHoverCapable()` / `useLongPress()` / `useVisualViewport()` — 移动端原语
 
@@ -433,58 +430,59 @@ const vv = ctx.ui.useVisualViewport()
 
 ```tsx
 // 组件 A：mount 阶段注册自定义 ID
-const StatsPanel = (_init, ctx) => {
+const StatsPanel = async (_init, ctx) => {
   ctx.ui.selfId('stats')
-  const $ = ctx.ui.$()
-  $.data = []
-  return (props) => h('div', {}, String($.data.length))
+  let data: unknown[] = []
+  return async (props) => h('div', {}, String(data.length))
 }
 
 // 组件 B（或其他任何地方）用 ID 精准刷新
-ctx.ui.render(['stats'])        // 同步刷新
-// 或：ctx.ui.dirty(['stats'])   // 异步批处理版本
+ctx.ui.render(['stats'])
 ```
 
 **语义**：
 
-- 必须在 **mount 阶段**调用（组件初始化时），注册后组件即可被 `render(['id'])` / `dirty(['id'])` 精准定位
+- 必须在 **mount 阶段**调用（组件初始化时），注册后组件即可被 `render(['id'])` 精准定位
 - **同名冲突直接抛错**，每个自定义 ID 必须全局唯一
 - 配合 `selfId` 注册的组件在跨组件场景下无需把刷新逻辑层层传 props
 
 #### `ctx.ui.useChat(options)` — AI 对话会话（AiChat 配套）
 
-会话语义的流式 AI 状态容器：消息累积 / 工具调用内嵌 / HITL 审批 / stop / retry，协议对页面完全透明（wf: 协议见 `design/ai-contract.md`）。返回的 handle 与 `ctx.ui.$()` **同一个 $**（页面状态与会话状态共处一容器）：
+会话语义的流式 AI 状态容器：消息累积 / 工具调用内嵌 / HITL 审批 / stop / retry，协议对页面完全透明（wf: 协议见 `design/ai-contract.md`）。返回 handle 带 `subscribe(cb)`——子组件用 `ctx.ui.useExternal(chat)` 订阅会话变化（render-only 共享状态原语）：
 
 ```tsx
 // mount 阶段（服务端 `ai()` 中间件 + `AiChat` 组件配套）
-const $ = ctx.ui.useChat({
+const chat = ctx.ui.useChat({
   url: '/api/chat',          // POST 端点（返回 wf: SSE 流）
   approveUrl: '/api/approve', // HITL 审批上行（缺省时 approve() 只清卡片）
   body: (messages) => ({ messages, mode: 'agent' }),  // 定制请求体
   onEvent: (name, data) => { console.log('x:' + name, data) },  // x:* 透传
 })
 
-return (props) =>
+// 子组件订阅会话变化（AiChat 已内置 useExternal）：
+// const state = ctx.ui.useExternal(chat)
+
+return async (props) =>
   h('div', {},
-    h(AiChat, { chat: $ }),        // 标准对话界面：流式 token/工具卡/审批卡/自动滚动
-    $.streaming ? '生成中…' : '',  // 会话状态与页面状态同容器
+    h(AiChat, { chat }),             // 标准对话界面：流式 token/工具卡/审批卡/自动滚动
+    chat.streaming ? '生成中…' : '',  // 会话状态（直接读 handle）
   )
 ```
 
-**状态（`$` 上）**：
+**状态（handle 上）**：
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `$.messages` | `UiMessage[]` | 消息列表（`{ id, role, content, status, toolCalls?, approval?, usage?, error? }`） |
-| `$.input` | `string` | 输入框值（双向绑定） |
-| `$.streaming` | `boolean` | 是否正在流式生成 |
-| `$.error` | `WfError \| null` | 最近错误（code + message） |
-| `$.usage` | `WfUsage \| null` | token 用量（prompt/completion/total） |
-| `$.step` | `WfStep \| null` | 最近 agent 步骤指示（思考/工具），done/error 时清空 |
+| `chat.messages` | `UiMessage[]` | 消息列表（`{ id, role, content, status, toolCalls?, approval?, usage?, error? }`） |
+| `chat.input` | `string` | 输入框值（双向绑定） |
+| `chat.streaming` | `boolean` | 是否正在流式生成 |
+| `chat.error` | `WfError \| null` | 最近错误（code + message） |
+| `chat.usage` | `WfUsage \| null` | token 用量（prompt/completion/total） |
+| `chat.step` | `WfStep \| null` | 最近 agent 步骤指示（思考/工具），done/error 时清空 |
 
-**操作（`$` 上的方法）**：`$.send()`（发送当前输入）/ `$.stop()`（中止）/ `$.retry()`（截断到最后一条 user 重生成）/ `$.clear()`（清空）/ `$.approve(decision, note?)`（响应审批）/ `$.dispose()`（卸载时释放流）。
+**操作（handle 上的方法）**：`chat.send()`（发送当前输入）/ `chat.stop()`（中止）/ `chat.retry()`（截断到最后一条 user 重生成）/ `chat.clear()`（清空）/ `chat.approve(decision, note?)`（响应审批）/ `chat.dispose()`（卸载时释放流）。
 
-**共享 $ 的子组件**（如 `<AiChat chat={$}>`）：父组件 dirty 不驱动子组件（三态 skip），子组件 mount 阶段 `chat.__watch?.(() => ctx.ui.dirty())` 自订阅（AiChat 已内置）。
+**共享 handle 的子组件**（如 `<AiChat chat={chat}>`）：会话状态变化 → `notify()` → `useExternal` 订阅者自动重渲染（AiChat 已内置——替代已删除的 `__watch`）。
 
 #### `ctx.ui.useAsync(fetcher)` — 异步取数
 
@@ -496,7 +494,7 @@ const list = ctx.ui.useAsync(() => ctx.api.get<User[]>('/users'))
 return () => list.loading ? h(Loading) : list.data?.map(u => h('div', {}, u.name))
 ```
 
-- `list.data` / `list.loading` / `list.error` 赋值自动 dirty 当前组件
+- `list.data` / `list.loading` / `list.error` 变化自动重渲染当前组件
 - `list.reload()` 重跑；组件卸载后旧 Promise resolve 不再触发渲染（idRegistry 查无此组件，安全忽略）
 
 #### 动画原语（4 层能力）
@@ -506,7 +504,7 @@ return () => list.loading ? h(Loading) : list.data?.map(u => h('div', {}, u.name
 | 原语 | 层 | 说明 |
 |------|----|------|
 | `useAnimationEnd(cb, { once? })` | 生命周期 | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定）——**组件内动画事件唯一入口** |
-| `usePresence({ name? })` | 生命周期 | 显隐状态机：open → exit → closed（animationend 延迟卸载）；`useDialog` 是其对话框特例 |
+| `usePresence({ name? })` | 生命周期 | 显隐状态机：open → exit → closed（animationend 延迟卸载）；`usePopup` presence 模式内部使用 |
 | `useTween(target, { duration?, ease? })` | 数值驱动 | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset + 每帧自动渲染） |
 | `useReducedMotion()` | 偏好感知 | 响应式系统偏好——**JS 动画**（rAF/tween）侧跳过（CSS 动画已有全局降级） |
 | `useInView` / `useScrollPosition` | 数值驱动 | 进入视口播 / 滚动位置联动（已有） |
@@ -565,117 +563,134 @@ if (!ctx.ui.useReducedMotion()) { /* 启动 rAF/动画 */ }
 
 > **移动端开发指南**：断点体系 / 44px 命中区纪律 / usePopup / 手势原语 / safe-area / 验收清单 → [`docs/mobile.md`](mobile.md)
 
-### `ctx.ui.dirty()` — 异步标记脏
-
-异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
-
-与 `render()` 的区别：`dirty()` 是**异步**（微任务批量合并，同帧多次调用只渲染一次），`render()` 是**同步**（立即执行 VDOM diff + patch）。日常 UI 状态用 `$` 或 `dirty()`，需要立即拿到最新 DOM（测量/动画/第三方库）时用 `render()`。
+### `ctx.ui.render()` — 渲染唯一入口（render-only）
 
-### `ctx.ui.render()` — 同步强制渲染
-
-与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。无参时只刷新当前组件，传参时可精准刷新指定组件。
+**渲染只发生在 `render()` 调用处**——改状态后必须调 `ctx.ui.render()`（无参 = 当前组件，传参 = 指定组件列表）。异步落地（fire-and-forget，`await` 可精确等待），多次调用合并为一次渲染。
 
 **何时必须用 `render()`**：
 
 ```tsx
 // 1. DOM 测量（读取 offsetHeight/scrollWidth 等）
-// 用 ref 在 DOM 创建后操作
-ref: (el) => {
+// 用 ref 在 DOM 创建后操作；需要最新 DOM 时 await render()
+ref: async (el) => {
   if (!el) return
   el.style.height = 'auto'
-  ctx.ui.render()
+  await ctx.ui.render()          // await 等 VDOM patch 完成
   const h = el.offsetHeight
   el.style.height = h + 'px'
 }
 
 // 2. 动画触发（需要确保上一帧 DOM 已提交）
 function startAnimation() {
-  $.animating = true
-  ctx.ui.render()                // 同步刷新 DOM
+  animating = true
+  ctx.ui.render()
   el.startViewTransition(...)    // 拿到最新 DOM 启动动画
 }
 
 // 3. 第三方库需要在事件回调中读取最新 DOM
-onClick: () => {
-  $.selected = !$.selected
-  ctx.ui.render()                // 确保 DOM 已更新
+onClick: async () => {
+  selected = !selected
+  await ctx.ui.render()          // 确保 DOM 已更新
   thirdPartyLib.measure(el)      // 读取最新状态
 }
 ```
 
-**规则**：能用 `$` 就用 `$`。只有当你**必须同步拿到最新 DOM 状态**时才用 `render()`。
+**规则**：状态是普通对象（`let` / `createStore`），改状态后必须显式 `render()`；共享状态用 `createStore` + `useExternal`（store 变更自动重渲染订阅组件）。
 
 ### 三种方式速查
 
 ```tsx
-// 自动：$.x = val — 微任务批量，绑定当前组件
-const $ = ctx.ui.$()
-$.count++
-$.name = 'hello'         // 多次赋值合并为一次渲染
-
-// 手动：ctx.ui.render() — 同步，无参=当前，传参=指定
+// 手动：ctx.ui.render() — 异步落地（fire-and-forget），无参=当前，传参=指定
 let count = 0
 count++
-ctx.ui.render()          // DOM 立刻更新
+ctx.ui.render()          // DOM 更新（await 可精确等待）
 ctx.ui.render(['stats']) // 精准刷新指定组件
 
-// 异步：ctx.ui.dirty() — 微任务批量，同 render() 作用域
-ctx.ui.dirty()
-ctx.ui.dirty(['stats'])  // 批处理合并
+// 共享：createStore + useExternal — store 变更自动重渲染订阅组件
+const store = createStore({ count: 0 })
+store.set({ count: store.state.count + 1 })  // 通知订阅者
 ```
 
 **性能说明**：
-- `$.x = val` 和 `dirty()` 都是微任务批量合并
-- `render()` 从 dirty 组件**向下**遍历（scope render），兄弟组件不遍历
-- **三态 skip 自动优化**：组件重新渲染时，框架自动检查三个维度：
-  - **props**（含 children 元素级比较）——值没变则不渲染
-  - **`$` 状态**——没被 dirty 标记则不渲染
-  - **ctx 版本**——ctx 没变化则不渲染
-  三个条件全部满足时跳过整个子树（零 `_render` 调用、零 `patchValue` 遍历）
+- `render()` 精准渲染目标组件（renderByIds），兄弟组件不遍历
+- **剪枝/三态 skip 自动优化**：组件重新渲染时，框架自动检查：
+  - **props**（含 children 元素级比较）——值没变则复用旧 _child（renderFn 不重跑）
+  - **ctx 版本**——`bumpCtxVersion` 后版本变化强制重跑（i18n 切换语言）
+  全部满足时跳过整个子树（零 `_render` 调用、零 `patchValue` 遍历）
 - **lastIndex keyed diff**：列表 diff 采用正向 lastIndex 算法（React 同款），顺序不变时零 `insertBefore`。对比传统的逆序循环全量移动，DOM 修改从 O(N) 降到 O(0)。
 - 示例：DemoButton 点击一次，DOM 修改从 34 次降到 **1 次**（仅变更文本节点的 `textContent`）
 
-### 实践建议
+### 实践建议（render-only 唯一模式）
 
-**组件库**（可分享组件）推荐手动模式：
+**组件库与业务层同一模式**：
 
 ```tsx
-const DatePicker = (_init, ctx) => {
+const DatePicker = async (_init, ctx) => {
   let show = false             // let 不触发渲染
-  return (props) =>
+  return async (props) =>
     h('input', {
       onClick: () => { show = true; ctx.ui.render() }
     })
 }
 ```
 
-行为只由 `render()` 显式控制，不依赖 `$`，测试中 `render()` 直接 mock 为空函数。
+行为只由 `render()` 显式控制，测试中 `render()` mock 为空即可。
+
+**跨组件共享**（业务层）：
+
+```tsx
+const store = createStore({ orders: [], loading: false })
+
+const OrderPage = async (_init, ctx) => {
+  const state = ctx.ui.useExternal(store)   // 订阅：store 变更自动重渲染
+  return async (props) => h('div', {}, state.loading ? h(Spinner) : h(OrderList, { orders: state.orders }))
+}
+
+// 数据到达：store.set({ orders, loading: false }) → 订阅组件自动更新
+```
+
+内部状态用 `let` + `render()`，共享状态用 `store` + `useExternal`。
 
-**业务层**推荐自动模式：
+**配置式数据定义在 mount 层 / 模块层**（剪枝命中率——三态 skip 的组件侧纪律）：
 
 ```tsx
-const OrderPage = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.orders = []                // $ 赋值自动触发渲染
-  $.loading = false
-  return (props) => h('div', {}, $.loading ? h(Spinner) : h(OrderList, { orders: $.orders }))
+// ❌ 差：columns/options 内联 renderFn——每次 render 新建数组 + 内联函数 → Table 全量重跑
+const DemoTable = async (_init, ctx) =>
+  async () => h(Table, { columns: [{ key: 'name', render: v => <Badge>{v}</Badge> }], ... })
+
+// ✅ 好：静态配置定义在 mount 层 / 模块层——引用稳定 → 子组件 props 稳定 → 剪枝命中不重跑
+const COLS = [{ key: 'name', sortable: true }]   // 模块层（纯静态）
+const DemoTable2 = async (_init, ctx) => {
+  const cols = COLS                                // 或工厂层（读 ctx/状态时）
+  return async () => h(Table, { columns: cols, ... })
 }
 ```
 
-省事、安全、`$` 绑定所属组件不波及兄弟。
+**规则**：不依赖 render 期数据的配置（columns/options/items/NAV）→ mount 层或模块层定义（引用稳定，子组件剪枝命中）；依赖 render 期派生数据（过滤后的列表）→ 才在 render 内构建。
 
-同一个组件内可以按变量混用两种模式：需要渲染的用 `$`，不需要的用 `let`。
+**薄封装用普通函数**（不建组件——组件有工厂 + childCtx 开销）：
+
+```tsx
+// ❌ 薄封装组件：TypeBadge 无状态无实例需求，却是 async 组件形态 → 每实例走 mountAsyncComponent
+const TypeBadge: Component = async (_init) => async (props) => h(Badge, {...}, props.label)
+
+// ✅ 普通函数：在父 renderFn 内调用（不参与 vdom 组件树——无工厂/childCtx 开销）
+const typeBadge = (label: string, type: string) => h(Badge, { variant: ... }, label)
+```
+
+**规则**：纯透传 / 派生渲染 → 普通函数（父 renderFn 内调用）；有状态 / 需实例化 / props 驱动重渲染 → 组件形态。
 
 ### VDOM diff 优化机制
 
-weifuwu 的 VDOM 在每次 render 时自动执行**三态 skip 判定**，减少不必要的组件渲染和 DOM 操作：
+weifuwu 的 VDOM 在每次渲染时自动执行**剪枝 + 三态 skip 判定**，减少不必要的组件渲染和 DOM 操作：
 
 ```
-canSkip = (props 没变) AND ($ 没脏) AND (ctx 版本一致)
-          ↑ 值级浅比较    ↑ VNode dirty 标记  ↑ 全局版本号
+canSkip = (props 没变) AND (ctx 版本一致) AND (旧 _child 已构建)
+          ↑ 值级浅比较    ↑ bumpCtxVersion 后强制重跑  ↑ renderFn 不重跑
 ```
 
-三个维度各自独立判断，AND 合并。任何一个维度说
+条件全部满足时复用旧 `_child`（零 `_render` 调用、零 `patchValue` 遍历）——
+版本变化（i18n 切换）时剪枝失效，所有组件重跑 renderFn。
 
 ---
 
@@ -694,6 +709,35 @@ canSkip = (props 没变) AND ($ 没脏) AND (ctx 版本一致)
 ))}
 ```
 
+### 列表性能（v3——剪枝命中率是唯一性能变量）
+
+渲染引擎对**大列表**的性能模型：剪枝命中（props 同 + 版本同）→ 复用旧子树（renderFn 不重跑 + diff 零递归）。
+**剪枝只对组件生效**——native 元素（`<div>`/`<tr>` 等）每次渲染都会全量 patch：
+
+| 列表行形态 | 更新单行 | 说明 |
+|---|---|---|---|
+| **组件包裹**（推荐） | 剪枝命中，~O(1) | 行 props 不变 → renderFn 不重跑 + diff 跳过 |
+| 裸 native 元素 | 全量 patch O(n) | 每次 render 重建整树 + 全量 diff（1000 行 ~30-40ms jsdom） |
+
+```tsx
+// ✅ 大列表行用组件包裹（剪枝生效——更新单行 O(1)）
+const Row = (_init, ctx) =>
+  (props) => h('div', { class: 'row' }, h('span', {}, props.label))
+
+const List = (_init, ctx) =>
+  (props) => h('div', {}, props.items.map(r => h(Row, { key: r.id, label: r.label })))
+
+// ❌ 裸 native 行：每次 render 全量 patch（1000 行 = 全量遍历）
+{items.map(item => <div key={item.id}>{item.name}</div>)}
+```
+
+- **更新单行/单单元格**：数据模型建议行级状态（行组件各自持有状态 + `ctx.ui.render()` 精准刷新该行），
+  而非整表状态（整表 renderFn 重跑必然重建全部行）
+- **稳定数组透传**：renderFn 直接返回 `props.items`（不 map 重建）时，引用短路生效——未变项零 diff
+  （V3-3a）
+- 基准（1000 行 keyed 列表，jsdom）：首帧 build 0.6ms + render 26ms；更新单行（组件剪枝）DOM 写 0；
+  头部插入 DOM 写 1
+
 ---
 
 ## ref 管理 DOM
@@ -701,10 +745,10 @@ canSkip = (props 没变) AND ($ 没脏) AND (ctx 版本一致)
 使用 `ref` prop 获取元素引用，适合管理第三方库或读取 DOM：
 
 ```tsx
-const Timer: Component = (_init, ctx) => {
+const Timer: Component = async (_init, ctx) => {
   let timer: ReturnType<typeof setInterval> | undefined
 
-  return (props) =>
+  return async (props) =>
     h('div', {
       ref: (el) => {
         if (el) {
@@ -733,45 +777,76 @@ return h('div', {},
 
 ### 异步组件
 
-在 mount 阶段发起请求，数据通过 `$.x = val` 自动触发渲染：
+在 mount 阶段发起请求，数据到达后 `ctx.ui.render()` 触发渲染：
 
 ```tsx
-const UserProfile: Component = (initProps, ctx) => {
-  const $ = ctx.ui.$()
-  $.loading = true
+const UserProfile: Component = async (initProps, ctx) => {
+  let loading = true
+  let user: { name?: string } | null = null
 
   fetch(`/api/user/${initProps.id}`)
     .then(r => r.json())
-    .then(user => { $.user = user; $.loading = false })
+    .then(u => { user = u; loading = false; ctx.ui.render() })
 
-  return (props) =>
-    $.loading
+  return async (props) =>
+    loading
       ? h('div', {}, '加载中...')
-      : h('div', {}, $.user?.name ?? '')
+      : h('div', {}, user?.name ?? '')
 }
 ```
 
 ### async 组件（原生）
 
-组件 = 函数，async 组件 = async 函数：签名与同步组件一致 `(initProps, ctx) => renderFn`，渲染器按「返回值是 Promise」原生判别。数据经闭包注入，渲染无 loading 分支：
+组件 = 函数，async 组件 = async 函数：**两阶段都异步**（统一签名 `async (initProps, ctx) => async (props) => Promise<VNode>`）——工厂层（mount 一次）与 renderFn（每次 dirty/props 变化）都可 await 数据。渲染器在 buildVNode 阶段 await 全部；diff 永不执行 renderFn。数据经闭包注入，渲染无 loading 分支：
 
 ```tsx
 const UserProfile = 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', {},
-      h('p', {}, user.name),             // 服务端状态（闭包，SSR 进 HTML）
-      h('button', { onClick: () => $.liked = !$.liked }, $.liked ? '❤️' : '🤍'),
+  const user = await ctx.data.get(`/api/user/${initProps.userId}`)   // ① 工厂层：数据不随 props 变（三场景：SSR→__DATA__ / hydration 种子 / SPA fetch）
+  let liked = false                        // 客户端状态（交互后变化，render-only）
+  return async (props) => {
+    const related = await ctx.data.get(`/api/user/${props.userId}/related`)  // ② renderFn 层：数据随 props 变（每次重跑取新数据）
+    return h('div', {},
+      h('p', {}, user.name),               // 服务端状态（闭包，SSR 进 HTML）
+      h('span', {}, `相关 ${related.length}`),
+      h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }, liked ? '❤️' : '🤍'),
     )
+  }
 }
 ```
 
-- **客户端**：主路径 `buildVNode` async 预构建（await 全部工厂；兄弟并行）→ 落地零占位；动态挂载兑底占位 → 局部补全——N 处实例 = N 次工厂调用，数据走 `ctx.data` 则零成本（缓存 + 并发合并）
-- **服务端**：`ctx.ui.ssr()` 直接 await 工厂 → 数据进 HTML（无占位）
-- **占位显示**：动态挂载的 async 组件占位 = 注释节点，resolve 后局部补全（Suspense 边界已裁剪）
-- 会变的数据：初始值 seed 自服务端数据（`$.count = data.count`），交互改 `$`；初始状态必须确定性（禁止 `window.innerWidth` 直接初始化 → SSR/hydration mismatch）
+- **两阶段数据分层**：数据不随 props 变 → 工厂层 await（只一次，`ctx.data` 缓存）；随 props/状态变 → renderFn 层 await（每次重跑，props 变化自动刷新）
+- **客户端**：主路径 `buildVNode` async 预构建（await 全部工厂 + renderFn；**兄弟组件并行取数**）→ 落地零占位；运行时首次挂载的 async 组件在 buildVNode 阶段 await（无占位/补全回调）——N 处实例 = N 次工厂调用，数据走 `ctx.data` 则零成本（缓存 + 并发合并）
+- **服务端**：`ctx.ui.ssr()` 直接 await 工厂 + renderFn → 数据进 HTML（无占位；数组分支 Promise.all 并行取数）
+- 初始状态必须确定性（禁止 `window.innerWidth` 直接初始化 → SSR/hydration mismatch）
+
+### 取数模式（机制与策略分离——不绑定 ctx.data）
+
+renderFn 内可 await **任意 Promise**（fetch / `ctx.api` / 第三方 SDK / `ctx.data`）——渲染管线对三种模式一视同仁（并发取数 + 原子落地 + props 自动刷新都成立）。取数是**策略**（开发者决定），框架只提供机制：
+
+| 模式 | 写法 | 语义 | 适用 |
+|---|---|---|---|
+| **ctx.data 管道** | `await ctx.data.get(key, fetcher)` | 缓存 + 并发合并 + SSR 三场景（fetcher 可以是任意函数） | 重复执行 / 跨组件共享 / 需要 SSR 的数据 |
+| **直接 await** | `await fetch(...)` / `ctx.api.get(...)` / SDK | **每次 renderFn 重跑重新执行**（无缓存） | 一次性局部取数 |
+| **事件驱动** | 闭包 `let` + fetch + `ctx.ui.render()` | 只执行一次，renderFn 读闭包 | 需精确控制触发时机 / 有副作用 |
+
+**决策规则**：数据会重复执行或跨组件共享？→ ctx.data；一次性局部数据？→ 直接 await；需精确控制时机？→ 事件驱动。
+
+**红线**：
+- 直接 await = **每次 renderFn 重跑重新请求**（父组件无关状态变化也会触发）——高频数据用 ctx.data 缓存防重复
+- renderFn 内 await 应为**幂等取数**（副作用走事件驱动）
+- ctx.data 的 fetcher 可以是**任意函数**（不只框架 API）：`ctx.data.get('/key', () => sdk.query(...))`
+
+**页面形态纪律（B-1）**：路由 handler（UIHandler）直接返回 vnode——**页面根是 native vnode，无组件 `_render`/`_id`，handler 闭包内的 `let` 状态 + `ctx.ui.render()` 无效**（静默空操作——`render()` 无参无目标会 console.warn 提示）。页面内部状态两种正确写法：
+1. **async 组件形态**（推荐）：`const Page: Component = async (initProps, ctx) => { let state = ...; return async (props) => h(...) }`——handler 返回 `h(Page, {})`
+2. **createStore + useExternal**：跨页面共享状态
+
+```tsx
+// ❌ UIHandler 闭包内部状态（render() 空操作）
+const Home: UIHandler = async (_loc, ctx) => { let clicks = 0; return h(Button, { onClick: () => { clicks++; ctx.ui.render() } }) }
+// ✅ handler 只返回组件 vnode，状态在组件里
+const ClickCounter: Component = async (_init, ctx) => { let clicks = 0; return async () => h(Button, { onClick: () => { clicks++; ctx.ui.render() } }) }
+const Home: UIHandler = async () => h('div', {}, h(ClickCounter, {}))
+```
 
 ---