weifuwu 0.76.0 → 0.78.0

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,16 @@ const MyComp: Component = (_init, ctx) => {
 
 ## 已知边界（诚实裁剪）
 
-- `usePopup` 覆盖浮层（Tooltip/Popover/Dropdown/Mentions/Cascader/ContextMenu）；**全屏对话框**（Modal/Drawer）用 useDialog（Escape 语义留组件层）；Command/Img preview 保持独立实现
+- **引擎自动写入的 DOM 属性（开发者不需要处理，但写自定义组件时会在 DOM 里看到）**：
+  - `data-wf-id`——组件实例 id，写到组件输出**每个顶层节点**（多根全部写）——渲染定位/audit/debug 用；存在性可预期，值不可预期（`_wf_N` 引擎分配）
+  - `data-wf-key`——数组项 key（显式或默认下标），写到元素项自身 / **组件项穿透到输出每个顶层节点**——列表项身份可见，动态增删重排建议显式 key（默认下标 = 位置复用 + 状态继承）
+  - `<!--wf-hole: xxx-->` 占位注释——条件渲染 false/null/true/非法输入的占位节点（`{cond && <X/>}`=false 时 DOM 里有注释而非消失）——不是 bug，是引擎的透明占位
+  - SSR 不输出 `data-wf-id`（id 客户端运行时分配）；`data-wf-key` SSR 同步输出
+  - 断言/快照测试注意：`outerHTML` 包含这些属性与占位注释；按类选择器/子项数量断言不受影响
+- **列表 key 纪律**：渲染的列表是**有内部状态的组件实例 + 动态增删/重排**（如可输入的卡片）→ 必须显式 key（项 id），否则默认下标位置复用会让后续项继承被删项的内部状态；纯元素列表（格子/行/节点 div）默认下标即可——通用列表组件对外提供 `keyBy`（如 `List`）
+
+- `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)` 订阅）

package/docs/examples.md

@@ -5,12 +5,11 @@
 ## 登录表单
 
 ```tsx
-const LoginPage = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.errors = {}
-  $.submitting = false
+const LoginPage = async (_init, ctx) => {
+  let errors: Record<string, string> = {}
+  let submitting = false
 
-  return (props) =>
+  return async (props) =>
     h('div', { class: 'wf-stack', style: { maxWidth: 400, margin: '40px auto' } },
       h(Card, { padding: 'lg' },
         h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
@@ -21,17 +20,19 @@ const LoginPage = (_init, ctx) => {
               password: [{ required: true, minLength: 6, message: '密码至少6位' }],
             },
             onSubmit: async (values) => {
-              $.submitting = true
+              submitting = true
+              ctx.ui.render()
               await ctx.api?.post('/login', values)   // api 客户端由中间件注入 ctx.api
-              $.submitting = false
+              submitting = false
+              ctx.ui.render()
             },
-            onError: (errors) => { $.errors = errors },
+            onError: (errs) => { errors = errs; ctx.ui.render() },
           }, [
-            h(Field, { label: '邮箱', error: $.errors.email },
+            h(Field, { label: '邮箱', error: errors.email },
               h(Input, { name: 'email', type: 'email', placeholder: 'name@example.com' })),
-            h(Field, { label: '密码', error: $.errors.password },
+            h(Field, { label: '密码', error: errors.password },
               h(Input, { name: 'password', type: 'password' })),
-            h(Button, { type: 'submit', loading: $.submitting, block: true }, '登录'),
+            h(Button, { type: 'submit', loading: submitting, block: true }, '登录'),
           ])
         )
       )
@@ -42,20 +43,19 @@ const LoginPage = (_init, ctx) => {
 ## 数据列表 + 搜索
 
 ```tsx
-const UserList = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.keyword = ''
-  $.sortKey = 'name'
-  $.sortOrder = 'asc'
+const UserList = async (_init, ctx) => {
+  let keyword = ''
+  let sortKey = 'name'
+  let sortOrder = 'asc'
   const users = [
     { id: 1, name: '张三', email: 'zhang@example.com', role: '管理员' },
     { id: 2, name: '李四', email: 'li@example.com', role: '编辑' },
   ]
 
-  return (props) => {
-    // 派生数据必须在 render 内计算（每次 render 读最新 $.keyword）
+  return async (props) => {
+    // 派生数据必须在 render 内计算（每次 render 读最新 keyword）
     const filtered = users.filter(u =>
-      !$.keyword || u.name.includes($.keyword) || u.email.includes($.keyword)
+      !keyword || u.name.includes(keyword) || u.email.includes(keyword)
     )
 
     return h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
@@ -85,39 +85,33 @@ const UserList = (_init, ctx) => {
 ## 消息提示
 
 ```tsx
-// 在任意组件中调用
-let toastId = 0
+// 官方推荐：命令式中间件（app.use(toast()) → ctx.toast('消息', 'success')）
+app.use(toast())
+// 任意组件：ctx.toast?.('操作成功', 'success')
 
-function showToast(ctx: WfuiContext, type: ToastType, message: string) {
-  // 通过 ctx 管理 Toast 列表
-  const $ = ctx.ui.$()
-  $.toasts = $.toasts ?? []
-  const id = String(++toastId)
-  $.toasts = [...$.toasts, { id, type, message }]
+// 自管理列表（render-only：let + render()）
+let toasts: { id: string; type: string; message: string }[] = []
+let toastId = 0
 
-  // 自动消失
+function showToast(ctx: WfuiContext, type: string, message: string) {
+  toasts = [...toasts, { id: String(++toastId), type, message }]
+  ctx.ui.render()
   if (type !== 'error') {
-    setTimeout(() => {
-      $.toasts = $.toasts.filter((t: any) => t.id !== id)
-    }, 3000)
+    setTimeout(() => { toasts = toasts.filter((t: any) => t.id !== String(toastId)); ctx.ui.render() }, 3000)
   }
 }
 
 // 页面中使用
-const App = (_init, ctx) => {
-  const $ = ctx.ui.$()
-  $.toasts = []
-
-  return (props) =>
+const App = async (_init, ctx) => {
+  toasts = []
+  return async (props) =>
     h('div', {}, [
-      h(Button, {
-        onClick: () => showToast(ctx, 'success', '操作成功'),
-      }, '显示提示'),
+      h(Button, { onClick: () => showToast(ctx, 'success', '操作成功') }, '显示提示'),
       h(Toast, {
-        toasts: $.toasts,
+        toasts,
         position: 'top-right',
         max: 3,
-        onRemove: (id) => { $.toasts = $.toasts.filter((t: any) => t.id !== id) },
+        onRemove: (id) => { toasts = toasts.filter((t: any) => t.id !== id); ctx.ui.render() },
       }),
     ])
 }

package/docs/frontend-middleware.md

@@ -24,8 +24,7 @@ uiServe(app, { root: '#root' })     // 客户端落地（hydrate: true 收养 SS
 
 ```tsx
 const DashboardLayout: UIMiddleware = async (_loc, ctx, children) => {
-  const $ = ctx.ui.$()
-  $.open = true
+  let open = true
   return async (loc, c) => {
     const child = await children(loc, c)   // 子路由/嵌套路由内容
     return h('div', { class: 'wf-row' },
@@ -132,8 +131,8 @@ app.use(auth())
 uiServe(app, { root: '#root' })
 
 // 在组件中
-function Profile(_props: {}, ctx: WfuiContext) {
-  return (props) => {
+async function Profile(_props: {}, ctx: WfuiContext) {
+  return async (props) => {
     if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
     return <p>欢迎, {ctx.auth?.user?.name}</p>
   }

package/docs/frontend-ui-dom.md

@@ -23,16 +23,15 @@
 ### 两阶段组件模型：从 hooks 心智负担中解脱
 
 ```tsx
-const Counter = (initProps, ctx) => {
-  const $ = ctx.ui.$()
-  $.count = initProps.initial ?? 0      // mount：只执行一次
-  return (props) =>
-    h('button', { onClick: () => $.count += props.step }, $.count)  // render
+const Counter = async (initProps, ctx) => {
+  let count = initProps.initial ?? 0        // mount：只执行一次
+  return async (props) =>
+    h('button', { onClick: () => { count += props.step; ctx.ui.render() } }, count)  // render
 }
 ```
 
-- **没有 hooks 规则、没有依赖数组、没有闭包陷阱**。外层 = 初始化（一次），内层 = 渲染（每次变化）。`$` Proxy 赋值自动触发组件级重渲染——**状态更新就是赋值**，不需要思考 `useState`/`useEffect`/`useMemo` 三件套的触发时机。
-- **状态驱动渲染**：`$.x = val` → dirty → 局部 patch。组件库手动优先（行为可预测、测试简单），业务层自动优先（省样板、不易遗漏）——按场景选模式而非被迫统一。
+- **没有 hooks 规则、没有依赖数组、没有闭包陷阱**。外层 = 初始化（一次），内层 = 渲染（每次变化）。
+- **render-only 确定性渲染**（design/render-only-plan.md）：渲染只发生在 `ctx.ui.render()` 调用处——改状态后显式 `render()`，行为可静态推导。无 `$` Proxy、无隐式触发；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。
 
 ### 框架即纪律：浏览器环境抽象把常见坑变成编译期/审计期错误
 
@@ -43,6 +42,7 @@ const Counter = (initProps, ctx) => {
 
 - **零 npm 运行时依赖**（对比 React + react-dom + react-router + 状态库 + SSR 工具 5+ 依赖）。
 - **自研 VDOM/diff**（keyed children、style diff、CSS 变量、Portal、hydration 游标收养）——每个算法都有对应测试与纪律条目（真实事故沉淀）。**读源码即可完全理解框架行为**。
+- **VDOM 对开发者透明（占位法 + 单一规则源）**：写 JSX → 看 DOM 即真相——`data-wf-key`（数组项身份，元素/组件一致）、`data-wf-id`（组件实例身份）、`<!--wf-hole: xxx-->`（条件渲染 false 的占位注释）直接在 DOM 可见；非法输入（对象/数字 type）→ 诊断占位 + warn，不崩溃不静默；`?vdom_debug=1` 开启 patch trace + 结构 audit。**转化路径唯一清晰、无 magic、可推导**（规则表：design/vdom-transform-rules.md）
 - **零构建步骤**：`weifuwu/dev` loader + `ctx.ui.js/css` 动态编译，服务端直接跑 `.tsx`，改组件刷新即生效。
 
 ### 弹层/浮层体系：最难的 UI 类别变成复用的原语
@@ -55,7 +55,7 @@ AGENTS.md 每条纪律对应真实事故（JSONViewer selfId 错位、AutoComple
 
 | 维度 | 价值 |
 |------|------|
-| **上手** | 两阶段组件 + 赋值即渲染——无 hooks/依赖数组心智负担 |
+| **上手** | 两阶段组件 + 改状态后 render()——无 hooks/依赖数组心智负担 |
 | **后端互迁** | req/res/中间件契约同构，SSR 透明，一份 router 两端共享 |
 | **可靠性** | 确定性失败、诚实裁剪、环境边界、测试侧同构 |
 | **效率** | 弹层/数据管道/事件原语全覆盖——不重复造轮子 |
@@ -74,14 +74,13 @@ const app = new UIRouter()
 
 app.use(toast()) // ctx 注入链（对齐后端 app.use——注入 ctx.toast）
 
-// handler = 异步组件：async (location, ctx) => VNode（$ 有效）
+// handler = 异步组件：async (location, ctx) => VNode（render-only——改状态后 ctx.ui.render()）
 app.get('/', async (location, ctx) => {
   const info = await ctx.data.get('/api/info', async () => ({ title: '首页' }))
-  const $ = ctx.ui.$()
-  $.clicks = $.clicks ?? 0
+  let clicks = 0
   return h('div', {},
     h('h2', {}, info.title),
-    h(Button, { onClick: () => $.clicks++ }, `点击 ${$.clicks} 次`),
+    h(Button, { onClick: () => { clicks++; ctx.ui.render() } }, `点击 ${clicks} 次`),
     h(Button, { variant: 'secondary', onClick: () => ctx.toast?.('提示', 'success') }, '弹 toast'),
   )
 })
@@ -119,17 +118,22 @@ handler 只产 VNode，落地由 serve 决定——SSR 与 SPA 是两种落地
 
 VNode 契约以 ui-dom 为唯一来源（Fragment/Portal symbol 由 ui-dom 自持）——components 产的 VNode
 直接被 ui-dom 渲染器识别。渲染算法（render/diff/createUi 原语）在 ui-dom 内自主实现，
-**registry/popup-tracker/dirty 集合局部实例**（serve 每实例隔离）。
+**registry/popup-tracker 局部实例**（serve 每实例隔离）。
 
 命令式工厂（toast/confirm/notification）位于 ui-dom（`src/ui-dom/Toast.ts` 等）：
 components 消费端 import `weifuwu/ui-dom`（构建外部化，共享同一模块实例）。
 
-### $ 响应式（两层）
+### render-only 渲染（唯一触发：ctx.ui.render()）
 
-| 层级 | 触发 | 重渲染范围 |
+| 原语 | 触发 | 重渲染范围 |
 |------|------|-----------|
-| 路由实例级 `$`（handler 的 `ctx.ui.$()`） | 赋值 | 重渲染 handler（data 缓存命中） |
-| 组件级 `$`（子组件 `ctx.ui.$()`） | 赋值 | **仅该组件**（父 handler 不重跑） |
+| `ctx.ui.render()`（无参） | 主动调用 | 当前组件（闭包绑定，无 this 陷阱） |
+| `ctx.ui.render(['id'])` | 主动调用 | 指定组件（selfId 注册的语义 ID） |
+| `ctx.ui.useExternal(store)` | store 变更自动 | **仅订阅组件**（unmount 自动退订） |
+
+- 状态是普通对象（`let` / `createStore`）——改状态后显式 `render()`，无赋值自动渲染
+- 跨组件共享：`createStore` + `useExternal`（替代已删除的 `$` Proxy / `dirty`）
+- hooks（useMedia/useInView/usePopup 等）事件驱动重渲染——与"赋值自动"本质不同
 
 ## SSR + hydration（端到端）
 
@@ -154,7 +158,7 @@ uiServe(app, { root: '#root', hydrate: true })
 |------|------|
 | `ctx.params` / `ctx.query` | 路由参数 / URL query（顶层，对齐后端） |
 | `ctx.data.get/set/has` | 数据管道（缓存 + in-flight 合并 + `__DATA__` 种子） |
-| `ctx.ui.*` | 19 原语（`$`/`dirty`/`render`/`usePopup`/`useChat`/`useInView`…） |
+| `ctx.ui.*` | 原语（`render`/`useExternal`/`usePopup`/`useChat`/`useInView`…） |
 | `ctx.browser.*` | 环境抽象（window/document 唯一入口，SSR shim 同构） |
 | `ctx.toast` / `ctx.confirm` / `ctx.notification` | 命令式注入（`app.use(toast())` 等） |