weifuwu 0.83.0 → 0.85.0

package/docs/frontend-middleware.md

@@ -1,45 +1,46 @@
 # 前端中间件与工具（weifuwu/ui-dom）
 
-> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（UIRouter + uiServe），见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（vdom3 事件流引擎：createRouter + createRoot），见 [frontend-ui-dom.md](frontend-ui-dom.md)。
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-## UIRouter — 前端路由
+## createRouter — 前端路由（vdom3）
 
 ```tsx
-import { UIRouter, uiServe, h } from 'weifuwu/ui-dom'
-import type { UIHandler } from 'weifuwu/ui-dom'
-
-const app = new UIRouter()
-app.get('/', () => h(Home, {}))
-app.get('/users', () => h(UserList, {}))
-app.get('/users/:id', (loc, ctx) => h(UserDetail, { id: ctx.params.id }))
-app.notFound(() => h(NotFound, {}))
-app.use(toast())                    // 中间件（ctx 注入）——app.use(mw)
-
-uiServe(app, { root: '#root' })     // 客户端落地（hydrate: true 收养 SSR HTML）
+import { createRouter, h } from 'weifuwu/ui-dom'
+
+let ctx: any = {}
+ctx = v3Toast()(ctx)                  // 中间件面展开（ctx 注入——对齐后端 app.use）
+
+const handle = createRouter(
+  [
+    { path: '/', render: () => h(Home, {}) },
+    { path: '/users', render: () => h(UserList, {}) },
+    { path: '/users/:id', render: (params) => h(UserDetail, { id: params.id }) },
+    { path: '*', render: () => h(NotFound, {}) },
+  ],
+  document.querySelector('#root')!,
+  { ctx },
+)
 ```
 
-### 嵌套布局（中间件两阶段）
+### 嵌套布局（RouteDef.layout——跨路由工厂不重跑）
 
 ```tsx
-const DashboardLayout: UIMiddleware = async (_loc, ctx, children) => {
+const DashboardLayout = async (page: any) => {
   let open = true
-  return async (loc, c) => {
-    const child = await children(loc, c)   // 子路由/嵌套路由内容
-    return h('div', { class: 'wf-row' },
-      h('aside', {}, '导航菜单'),
-      h('main', {}, child),
-    )
-  }
+  return h('div', { class: 'wf-row' },
+    h('aside', {}, '导航菜单'),
+    h('main', {}, page),   // 子路由内容（layout 包装——工厂复用——状态保持）
+  )
 }
-app.use(DashboardLayout)
+// { path: '/users', layout: DashboardLayout, render: () => h(UserList, {}) }
 ```
 
 ### 编程式导航
 
 ```tsx
-// 在任意组件/页面中（uiServe 注入）
+// 在任意组件/页面中（ctx.app——createRouter 注入）
 ctx.app?.navigate('/users/123?tab=profile')
 ```
 
@@ -51,28 +52,28 @@ ctx.app?.navigate('/users/123?tab=profile')
 | `ctx.route.query` | `Record<string, string>` | 查询参数 |
 | `ctx.app.navigate(path)` | `(string) => void` | 编程式导航 |
 
-| UIRouter API | 签名 | 说明 |
-|--------------|------|------|
-| `get(path, handler)` | `(string, UIHandler)` | 页面路由（handler = async 组件：`async (location, ctx) => vnode`） |
-| `use(prefix, sub)` / `use(mw)` | `(string, UIRouter) \| (mw)` | 子路由树挂载 / 中间件（ctx 注入） |
-| `notFound(handler)` | `(UIHandler)` | 404 页面 |
-| `mode` | `'history' \| 'hash'` | 路由模式（默认 history） |
+| RouteDef | 签名 | 说明 |
+|---------|------|------|
+| `path` | `string` | 路径（`:id` 参数 / `*` 通配） |
+| `render(params)` | `(params) => VNode` | 页面（params 注入——`ctx.route.params` 同源） |
+| `layout(page)` | `(VNode) => VNode` | 嵌套布局（跨路由工厂不重跑——状态保持） |
 
 | UIHandler | 类型 | 说明 |
 |-----------|------|------|
 | 签名 | `(location, ctx) => Promise<VNode> \| VNode` | 页面 = 异步组件（`ctx.data.get` 三场景；async 组件无需包装） |
-| 返回值 | `VNode \| null` | 数据结构（落地由 uiServe/ssrPage 决定） |
+| 返回值 | `VNode \| null` | 数据结构（落地由 createRouter 事件流渲染决定） |
 
 ---
 
 ## api — HTTP 客户端中间件
 
 ```tsx
-import { UIRouter, api, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h, api } from 'weifuwu/ui-dom'
 
-const app = new UIRouter()
-app.use(api({ baseURL: '/api' }))
-uiServe(app, { root: '#root' })
+let ctx: any = {}
+const root = document.querySelector('#root')!
+ctx = api({ baseURL: '/api' })(ctx)
+createRouter([], root, { ctx })
 
 // 在组件中使用
 async function loadUsers(ctx: WfuiContext) {
@@ -124,11 +125,12 @@ try {
 ## auth — 认证中间件
 
 ```tsx
-import { UIRouter, auth, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h, auth } from 'weifuwu/ui-dom'
 
-const app = new UIRouter()
-app.use(auth())
-uiServe(app, { root: '#root' })
+let ctx: any = {}
+const root = document.querySelector('#root')!
+ctx = auth()(ctx)
+createRouter([], root, { ctx })
 
 // 在组件中
 async function Profile(_props: {}, ctx: WfuiContext) {
@@ -176,11 +178,12 @@ await ctx.auth?.refresh()  // → boolean
 ## ws — WebSocket 客户端中间件
 
 ```tsx
-import { UIRouter, ws, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h, ws } from 'weifuwu/ui-dom'
 
-const app = new UIRouter()
-app.use(ws({ url: '/ws' }))
-uiServe(app, { root: '#root' })
+let ctx: any = {}
+const root = document.querySelector('#root')!
+ctx = ws({ url: '/ws' })(ctx)
+createRouter([], root, { ctx })
 
 // 发送消息
 ctx.ws?.send({ type: 'chat', body: 'hello' })
@@ -216,9 +219,10 @@ unsubscribe?.()
 ## i18n — 国际化中间件
 
 ```tsx
-import { UIRouter, i18n, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h, i18n } from 'weifuwu/ui-dom'
 
-const app = new UIRouter()
+let ctx: any = {}
+const root = document.querySelector('#root')!
 app.use(i18n({
     locale: 'zh-CN',
     messages: {
@@ -301,12 +305,13 @@ import { ErrorBoundary } from 'weifuwu/ui-dom'
 **① 命令式 `ctx.confirm()`（推荐，操作前询问）**
 
 ```tsx
-import { UIRouter, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h } from 'weifuwu/ui-dom'
 import { confirm } from 'weifuwu/components'
 
-const app = new UIRouter()
-app.use(confirm())
-uiServe(app, { root: '#root' })
+let ctx: any = {}
+const root = document.querySelector('#root')!
+ctx = confirm()(ctx)
+createRouter([], root, { ctx })
 
 // 任意代码中（组件事件、async 逻辑）
 async function handleDelete(ctx: WfuiContext) {
@@ -357,12 +362,13 @@ import { Confirm } from 'weifuwu/components'
 `ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
 
 ```tsx
-import { UIRouter, uiServe } from 'weifuwu/ui-dom'
+import { createRouter, h } from 'weifuwu/ui-dom'
 import { toast } from 'weifuwu/components'
 
-const app = new UIRouter()
-app.use(toast({ position: 'top-right', duration: 3000, max: 3 }))
-uiServe(app, { root: '#root' })
+let ctx: any = {}
+const root = document.querySelector('#root')!
+ctx = toast({ position: 'top-right', duration: 3000, max: 3 })(ctx)
+createRouter([], root, { ctx })
 
 // 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
 ctx.toast?.('保存成功', 'success')

package/docs/frontend-ui-dom.md

@@ -1,168 +1,151 @@
-# ui-dom — 前端运行时（UIRouter + uiServe + SSR/hydration）
+# ui-dom — 前端运行时（vdom3 精准事件流引擎）
 
-> **weifuwu 前端唯一运行时**（`weifuwu/ui-dom`，随 npm 包发布）：
-> **UIRouter（纯路由 + ctx 注入链）+ uiServe（渲染运行时）+ ssrPage/hydration**，
-> 复用 `weifuwu/components`（VNode 契约唯一来源，组件零修改）。
-> 已取代 `weifuwu/client`——前端运行时唯一入口（createApp/router 旧 API 已删除）。
->
-> 概念对齐：**req = window.location**，**res = VNode**（数据结构），
-> **uiServe = VDOM**（落地机制），**params/query 在 ctx**（对齐后端 `ctx.params`）。
+> **createRouter（路由）+ createRoot（挂载）+ 精准事件流（渲染本体）**，
+> 组件 = 两阶段异步组件（`async (initProps, ctx) => (props) => VNode`），
+> **params 在 ctx**（对齐后端 `ctx.params`），渲染全链路可观测/可回放/可断言。
 
-## 为什么是 ui-dom（开发者价值）
+## 架构：vdom3 事件流引擎
 
-### 心智模型统一：一套 API 贯穿两端，无需「两套前端」
-
-```
-后端: Request → [Middleware → ctx.field] → Handler → Response
-前端: window.location → [UIMiddleware → ctx.field] → Handler → VNode
 ```
-
-- **req/res 契约同构**：`UIRequest = window.location`（原生对象，不包装）对齐后端 `Request`；`UIResponse = VNode` 对齐 `Response`。后端开发者迁移到前端，中间件思维直接复用（`app.use(mw)` 与 `router.use(mw)` 累积类型同构）。
-- **SSR 不是另一套代码**：同一份 `router.ts`（两端共享），`ssrPage(router, { url })` 服务端直接跑，`uiServe(router, { root, hydrate: true })` 客户端收养。`ctx.data.get(key)` 一个 API 三场景自动适配（SSR 真 fetch → 序列化进 `__DATA__` → hydration 种子命中 → SPA 未命中触发 fetcher）——**开发者不需要理解「首屏/水合/客户端渲染」的区别**。
-
-### 两阶段组件模型：从 hooks 心智负担中解脱
-
-```tsx
-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
-}
+用户操作（ctx.render()）
+  → 决策层事件（jsx/vdom）：comp:render → vnode:patch（reuse/rebuild 决策）
+  → 执行层事件（dom）：node:create/insert/remove/move、prop:update、
+    text:update、event:bind/unbind、ref:cleanup
+  → DOM（精准状态变化——事件数 = 实际变化数）
 ```
 
-- **没有 hooks 规则、没有依赖数组、没有闭包陷阱**。外层 = 初始化（一次），内层 = 渲染（每次变化）。
-- **render-only 确定性渲染**：渲染只发生在 `ctx.ui.render()` 调用处——改状态后显式 `render()`，行为可静态推导。无 `$` Proxy、无隐式触发；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。
-
-### 框架即纪律：浏览器环境抽象把常见坑变成编译期/审计期错误
-
-- **`ctx.browser` 唯一入口**：复制/查询/滚动/存储/主题/定时器/媒体查询/事件监听全部经 BrowserEnv（组件侧 46 处迁移清零 + 测试侧 ~300 处对齐，SSR shim 三态同构）。开发者不需要记「SSR 里 `window.innerWidth` 会崩」这类环境知识——**框架替他们承担**。
-- **诚实裁剪**：不支持的能力明确抛 `ProtocolError('unsupported')`——确定性失败，绝不静默降级。
-
-### 零依赖 + 确定性：可审计、可测试、可读的运行时
-
-- **零 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、可推导**（规则表为内部开发契约）
-- **零构建步骤**：`weifuwu/dev` loader + `ctx.ui.js/css` 动态编译，服务端直接跑 `.tsx`，改组件刷新即生效。
-
-### 弹层/浮层体系：最难的 UI 类别变成复用的原语
-
-`ctx.ui.usePopup()` 一个组合器覆盖：portal 渲染、fixed 定位 + 视口夹紧、锚点变化自动重算、外部点击/Escape 关闭、el-null 微任务重试、ref 稳定化。**开发者不需要再写任何弹层脚手架**——这是传统前端最常重复造轮子的地方。弹窗纪律（portal 必须、z-index token、exit 动画成对）由审计测试强制。
+- **统一命名**：对象 + 动作 + 参数（`{ entity, action, target, payload }`——键 `entity:action`）——location（`route:change`）/ jsx（`comp:render`/`props:update`）/ vdom（`vnode:patch`）/ dom（`node:insert` 等）四层同构
+- **DOM = fold(事件流)**：初始 DOM + 事件序列 = 任意时刻 DOM——可记录（`stream.events()`）、回放（`replay`）、断言（`expectEventSequence`/`eventsOf`）
+- **不变量：无事件流不渲染**——所有状态变化都通过事件流（DOM 操作/组件生命周期/索引/事件注册/错误/挂起/内部决策/文本操作/副作用）——静态审计 + 运行时对照审计（`__WF_VDOM_AUDIT='1'`）守护
+- **render-only**：渲染唯一触发 `ctx.render()`（组件级——只重跑该组件 renderFn + patch 其输出，兄弟零执行）；`ctx.ui.render()` 为兼容面（同义）
+- **组件级精准更新**：`ctx.render()` 只刷新自身——组件 O(1) 索引定位——props 未变的子组件剪枝——事件数 = 实际变化数
 
-### 对贡献者的价值：纪律 = 事故沉淀
+### 事件代理（所有监听统一注册表）
 
-AGENTS.md 每条纪律对应真实事故（JSONViewer selfId 错位、AutoComplete 焦点丢失、TreeSelect 0 rect、Kanban draggable 空字符串解析 false）——新贡献者站在「踩过坑」的肩膀上。分层清晰（UIRouter 纯路由 → uiServe 装配点 → ctx.browser 环境边界 → components 消费层），改动边界由架构约束，协议层改动 TDD 先行 + 真实库验证（CS-04/CS-05）。
+元素事件/全局监听/动画钩子全部收敛到**代理注册表**（`delegate.ts`）：
+- 元素事件（onClick 等 props）→ 挂载点监听（每挂载点每事件一次——O(1)）+ 按 data-v3-id 祖先链分发（handler 更新 = Map 覆盖——**零重绑零噪音**）
+- 全局监听（keydown/mousedown/pointer/popstate/scroll/选区/剪贴板）→ `addGlobalListener`（同事件聚合——EventTarget 每事件一次）
+- 动画钩子（animationend）→ `bindElementListener`（once 自动解绑）
+- 不冒泡事件（error/load）→ 捕获监听；`e.currentTarget` 还原为绑定元素（与元素级语义一致）
 
-| 维度 | 价值 |
-|------|------|
-| **上手** | 两阶段组件 + 改状态后 render()——无 hooks/依赖数组心智负担 |
-| **后端互迁** | req/res/中间件契约同构，SSR 透明，一份 router 两端共享 |
-| **可靠性** | 确定性失败、诚实裁剪、环境边界、测试侧同构 |
-| **效率** | 弹层/数据管道/事件原语全覆盖——不重复造轮子 |
-| **可维护** | 零依赖可审计、纪律沉淀事故教训、构建可选 |
-
-> 一句话：ui-dom 不是「又一个 React」——它是把 weifuwu 后端中间件生态的确定性、可测试性和纪律性，原样移植到了前端。开发者得到的是一个行为可预测、失败可预期、源码可读懂的运行时。
-
-## 快速开始
+## 快速开始（SPA）
 
 ```tsx
-import { UIRouter, uiServe, h } from './src/ui-dom/index.ts'
-import { toast } from './src/ui-dom/Toast.ts'
-import { Button } from './src/components/index.ts'
-
-const app = new UIRouter()
-
-app.use(toast()) // ctx 注入链（对齐后端 app.use——注入 ctx.toast）
+import { createRouter, h } from 'weifuwu/ui-dom'
+import { Button } from 'weifuwu/components'
+
+// 两阶段异步组件：外层工厂（mount 一次——状态/数据），内层 renderFn（每次渲染）
+const Counter = async (_init, ctx) => {
+  let count = 0
+  return async () =>
+    h('div', {},
+      h('button', {
+        onClick: () => { count++; ctx.render() },   // render-only：显式触发
+      }, `count:${count}`),
+    )
+}
 
-// 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: '首页' }))
-  let clicks = 0
-  return h('div', {},
-    h('h2', {}, info.title),
-    h(Button, { onClick: () => { clicks++; ctx.ui.render() } }, `点击 ${clicks} 次`),
-    h(Button, { variant: 'secondary', onClick: () => ctx.toast?.('提示', 'success') }, '弹 toast'),
-  )
-})
+createRouter(
+  [{ path: '/', render: () => h(Counter, {}) }],
+  document.querySelector('#root') as HTMLElement,
+)
+```
 
-app.get('/users/:id', (location, ctx) => h('div', {}, `用户 ${ctx.params.id}`))
-app.notFound(() => h('div', {}, '404'))
+- 页面组件 ctx：`ctx.render()`（页面级刷新）/ `ctx.route`（`{ path, params }`——动态参数）/ `ctx.ui`（24 hooks）
+- 中间件面注入：`createRouter(routes, root, { ctx })`——`ctx` 为中间件展开结果（`api/auth/toast/confirm/i18n` 等——与后端 `app.use` 同理念）：
 
-uiServe(app, { root: '#root' }) // 装配点：路由已注册 → serve 监听 URL → 渲染
+```ts
+let ctx: any = {}
+ctx = await api({ baseURL: '', token: ... })(ctx)
+ctx = auth({ ... })(ctx)
+ctx = v3Toast()(ctx)
+createRouter([...], root, { ctx })
 ```
 
-## 核心概念
-
-### req / res / 落地分离
+## 无路由挂载（createRoot）
 
-| 概念 | 含义 |
-|------|------|
-| req | `window.location`（浏览器原生，不包装） |
-| res | `VNode`（handler 返回的数据结构） |
-| uiServe | VDOM 落地（renderValue/patchValue diff·patch DOM） |
-| ssrPage | 服务端落地（renderSsr → HTML + `__DATA__`） |
+组件树直接挂载（弹窗宿主、微前端片段、非路由页面）：
 
-handler 只产 VNode，落地由 serve 决定——SSR 与 SPA 是两种落地，同一 router 定义共享。
+```ts
+import { createRoot, h } from 'weifuwu/ui-dom'
+const handle = createRoot(h(App, {}), document.getElementById('root')!, { ctx })
+await handle.ready  // 首帧完成
+```
 
-### UIRouter 三态 use（对齐后端 app.use）
+## ctx.ui（组件库消费面——24 hooks）
 
-| 形态 | 签名 | 用途 |
-|------|------|------|
-| ctx 注入 | `use(mw: AppMiddleware)` | `(ctx) => ctx`——注入 ctx.toast/confirm 等（类型累积 `UIRouter<C & O>`） |
-| 渲染中间件 | `use(mw: UIMiddleware)` | `(location, ctx, children) => (location, ctx) => vnode`——layout/SSR 包装 children |
-| 子路由 | `use(prefix, sub)` | 独立路由树（sub 的中间件/notFound/嵌套均生效） |
+`useExternal`（共享状态）/ `useControlled`/`useControlledInput`（受控原语）/ `useOpen`/`usePopup`（弹层组合器——portal 定位/Escape/外部点击）/ `usePopupPosition` / `useTween` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag`/`useDragDrop` / `useMedia`/`useBreakpoint` / `useReducedMotion` / `useStableRef` / `useAnimationEnd` / `usePresence`（退场状态机）/ `useLongPress` / `useHoverCapable` / `useVisualViewport` / `useAsync` / `useChat`（AI 会话——消息/工具调用/审批）。
 
-运行时按 `arg.length` 区分（1 参 = ctx 注入；3 参 = 渲染）。
+组件库（weifuwu/components）零引擎耦合：只消费 `ctx.ui` 契约——vdom3 与未来引擎可无缝替换。
 
-### components 复用（零修改）
+## 事件流可观测（调试/测试）
 
-VNode 契约以 ui-dom 为唯一来源（Fragment/Portal symbol 由 ui-dom 自持）——components 产的 VNode
-直接被 ui-dom 渲染器识别。渲染算法（render/diff/createUi 原语）在 ui-dom 内自主实现，
-**registry/popup-tracker 局部实例**（serve 每实例隔离）。
+```ts
+import { stream, evKey } from 'weifuwu/ui-dom'
+import { eventsOf, expectEventSequence } from 'weifuwu/ui-dom'
 
-命令式工厂（toast/confirm/notification）位于 ui-dom（`src/ui-dom/Toast.ts` 等）：
-components 消费端 import `weifuwu/ui-dom`（构建外部化，共享同一模块实例）。
+const events = stream.events()
+eventsOf(events, 'node:create').length   // 创建了几个节点
+// 决策层事件解释"为什么"（reuse/rebuild），执行层事件是"做了什么"——完全可断言
+```
 
-### render-only 渲染（唯一触发：ctx.ui.render()）
+**完整事件覆盖**（任何问题都在事件流可定位）：
+- **错误**：`error:throw/caught`（工厂/renderFn/挂载/更新失败——phase 定位）+ **挂起超时**（renderFn/buildVNode 永不 resolve → 3s 检测——静默失败不再静默）
+- **内部决策**：`internal:queue/notfound/skip`（busy 排队/组件未定位）
+- **事件流自身**：`stream:overflow`（溢出可审计）/ `stream:watermark`（水位预警）/ `size()`/`capacity()`/`overflowCount()`/`subscribe(filter, fn)`（按层过滤订阅）
+- **文本操作**：`text:input`（输入/组合）/ `text:select`（选区）/ `text:copy/cut/paste`（剪贴板摘要）
+- **组件副作用**：`ref:mount` + `effect:animate/lock/unlock/focus/scroll`（动画/滚动锁/焦点 trap/滚动）
 
-| 原语 | 触发 | 重渲染范围 |
-|------|------|-----------|
-| `ctx.ui.render()`（无参） | 主动调用 | 当前组件（闭包绑定，无 this 陷阱） |
-| `ctx.ui.render(['id'])` | 主动调用 | 指定组件（selfId 注册的语义 ID） |
-| `ctx.ui.useExternal(store)` | store 变更自动 | **仅订阅组件**（unmount 自动退订） |
+测试纪律（jsdom）：`renderVNode`（VNode 层）/ `mountComponent`（同实例 re-render）/ `expectEventSequence`（精确事件序列）——渲染 = 事件序列断言。
 
-- 状态是普通对象（`let` / `createStore`）——改状态后显式 `render()`，无赋值自动渲染
-- 跨组件共享：`createStore` + `useExternal`（替代已删除的 `$` Proxy / `dirty`）
-- hooks（useMedia/useInView/usePopup 等）事件驱动重渲染——与"赋值自动"本质不同
+### 多应用加载（app 节点）
 
-## SSR + hydration（端到端）
+```ts
+import { registerApp, App } from 'weifuwu/ui-dom'
 
-```tsx
-// 服务端（Node 无 DOM）：ssrPage → 完整 HTML + __DATA__
-import { ssrPage } from './src/ui-dom/ssr.ts'
-import { app } from './router.ts' // 路由定义两端共享
+// 注册子应用（工厂——可 await 初始化——appId 复用不重跑）
+registerApp('mini-todo', (props, ctx) => h(MiniTodo, {}))
+// 父树中嵌入（不隔离设计——共享流/全局 id——天然归属唯一）
+h(App, { appId: 'mini-todo', props: { title } })
+```
+- 边界事件（同流）：`app:mount` / `app:update`（props keys）/ `app:unmount` / `app:error`（unknown-app）——payload 带 appId 可区分
+- 子应用独立状态（工厂闭包）——渲染/事件与父同流（全链路可观测——调试一条流）
+
+## SSR（事件流形态——DOM = fold 不变量）
+
+vdom3 SSR 不是 HTML 字符串 + 游标收养，而是**事件流序列化**：
+
+```ts
+// 服务端：构建 → 事件流 → HTML + 序列化事件
+import { renderToEvents, eventsToHtml, serializeEvents } from 'weifuwu/ui-dom'
+const events = await renderToEvents(vnode)      // 事件流（node:create/insert/...）
+const html = eventsToHtml(events)                // 首帧 HTML
+const data = serializeEvents(events)             // 序列化事件（__DATA__）
+// 客户端：replay(events, root) —— 零 DOM 猜测，与服务端 HTML 同构
+import { deserializeEvents, replay } from 'weifuwu/ui-dom'
+replay(deserializeEvents(data), root)
+```
 
-const { page } = await ssrPage(app, { url: '/users/42' })
+`ctx.data.get(key, fetcher)` 三场景自动适配（SSR 真 fetch → 序列化进 `__DATA__` → 客户端种子命中 → SPA 未命中触发 fetcher）。
 
-// 客户端：uiServe hydrate（收养服务端 HTML + __DATA__ 种子命中不重取数）
-uiServe(app, { root: '#root', hydrate: true })
-```
+## 组件纪律速查（事故沉淀——详见 AGENTS.md）
 
-- SSR 时 `ctx.data.get` 写入 dataStore → `__DATA__` 脚本；hydrate 从种子同步命中
-- renderSsr：组件两阶段 + async 组件 await（数据 per-request）/ Portal 内联 / 事件剥离
-- SSR 确定性：ui 19 原语 shim 全 no-op（不启动监听/会话）；渲染期非确定性由开发者规避
+- **render-only**：状态是普通对象（`let` + 显式 `render()`）——禁止隐式触发
+- **mount/render 分工**：只依赖稳定引用的回调（ctx/挂载闭包）→ mount 定义（零重绑）；依赖最新 props → render 内定义（重绑是正确性要求）
+- **ref 稳定**：带清理的 ref 定义在 mount 作用域（内联 ref 每次渲染新函数 → ref(null) 反复触发）
+- **浮层 portal**：`ctx.ui.usePopup` + `popup.portal()`（#__wf_portal）——禁止 absolute 相对父容器
+- **浏览器环境**：组件用 `ctx.browser`（禁裸 window/document）——SSR 安全三态
+- **事件 handler**：代理 Map 覆盖——handler 更新零重绑零事件（稳定引用仅为性能建议——结构共享收益前提）
+- **props 不可变（红线——Chat 空 bubble 事故）**：**禁止原地修改 props 引用的对象**（`m.content += text`）——vdom3 剪枝按 props 浅比较判断"未变"→ 复用旧输出 → 渲染不更新。**状态更新必须新建对象**（`$.msgs[i] = { ...m, content: ... }`——引用变 → 剪枝不命中 → 重渲染）。排查"渲染没更新"时看 `__wf_tail` 的 `comp:build` 事件 `reason: 'reuse-skip'`（= 契约：props 引用未变）
 
-## ctx 注入
+## 与后端共享
 
-| 字段 | 说明 |
-|------|------|
-| `ctx.params` / `ctx.query` | 路由参数 / URL query（顶层，对齐后端） |
-| `ctx.data.get/set/has` | 数据管道（缓存 + in-flight 合并 + `__DATA__` 种子） |
-| `ctx.ui.*` | 原语（`render`/`useExternal`/`usePopup`/`useChat`/`useInView`…） |
-| `ctx.browser.*` | 环境抽象（window/document 唯一入口，SSR shim 同构） |
-| `ctx.toast` / `ctx.confirm` / `ctx.notification` | 命令式注入（`app.use(toast())` 等） |
+- 中间件理念同构：后端 `app.use`（ctx.sql/redis/api/...）↔ 前端 `createRouter(routes, root, { ctx })`（ctx.api/auth/...）
+- 路由参数：`ctx.route.params`（对齐后端 `ctx.params`）
+- `weifuwu/dev`（Node loader）：服务端直接跑 `.tsx`——与 `ctx.ui.js` 前端动态编译对称，两端同一 JSX 运行时
 
-## demo
+## 参考
 
-`apps/layouts-demo`：UIRouter + uiServe + components 的布局蓝本壳（hash 路由切换 8 种布局模式）——
-`apps/components-demo`：全部 115 组件 + ui-dom 交互演示（含 Toast/Confirm 注入、SSR/hydrate）。
+- 组件库蓝本：`apps/components-demo`（115 组件 + createRouter 装配）
+- 完整应用：`apps/agent-platform`（多租户 AI 平台——认证守卫/嵌套布局/AI 会话）
+- 布局蓝本：`apps/layouts-demo`（8 种布局模式）

package/docs/frontend.md

@@ -5,7 +5,7 @@
 > createRoot + 事件流）。vdom2（本文档）为当前生产引擎（冻结中——bug 修复在 vdom3）。
 > 迁移路线图见仓库 `design/vdom3-migration-plan.md`。
 
-> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——本页 import 均用 `weifuwu/ui-dom`。前端运行时唯一入口是 **`weifuwu/ui-dom`**（UIRouter 纯路由 + uiServe 渲染运行时 + SSR/hydration），权威参考见 **[docs/frontend-ui-dom.md](frontend-ui-dom.md)**。
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——本页 import 均用 `weifuwu/ui-dom`。前端运行时唯一入口是 **`weifuwu/ui-dom`**（vdom3 精准事件流引擎：createRouter + createRoot——渲染全链路 `entity:action` 事件流），权威参考见 **[docs/frontend-ui-dom.md](frontend-ui-dom.md)**。
 
 > 以下为完整 API 参考，按需查阅。新手建议先阅读 README 的「核心概念」和「快速开始」。
 
@@ -25,31 +25,34 @@ esbuild.build({
 
 ---
 
-## 应用引导（UIRouter + uiServe）
+## 应用引导（vdom3 事件流引擎——createRouter）
 
 ```tsx
-import { UIRouter, uiServe } from 'weifuwu/ui-dom'
-
-const app = new UIRouter()
-
-// 注册中间件（ctx 注入）
-app.use(middleware1)
-app.use(middleware2)
-
-// 页面路由（handler = 异步组件）
-app.get('/', () => h(Home, {}))
-
-// 落地：客户端渲染（hydrate: true 收养 SSR HTML）
-const handle = uiServe(app, { root: '#root' })
+import { createRouter } from 'weifuwu/ui-dom'
+
+// 中间件面展开（对齐后端 app.use 链——ctx 注入）
+let ctx: any = {}
+ctx = await api({ baseURL: '' })(ctx)
+ctx = await auth({ ... })(ctx)
+ctx = v3Toast()(ctx)
+
+// 路由（RouteDef[]）+ 落地（事件流渲染）
+const handle = createRouter(
+  [
+    { path: '/', render: () => h(Home, {}) },
+    { path: '/users/:id', render: (params) => h(UserPage, { id: params.id }) },
+  ],
+  document.querySelector('#root')!,
+  { ctx },
+)
 ```
 
 | API | 说明 |
 |------|------|
-| `new UIRouter()` | 创建路由实例 |
-| `app.use(mw)` | 注册中间件（AppMiddleware / UIMiddleware） |
-| `app.get(path, handler)` / `use(prefix, sub)` / `notFound(handler)` | 页面路由 / 子路由树 / 404 |
-| `uiServe(app, { root, hydrate })` | 客户端落地（返回 handle，`handle.close()` 卸载） |
-| `app.ctx` | 当前 WfuiContext |
+| `createRouter(routes, root, { ctx })` | vdom3 路由：RouteDef[]（`{ path, render, layout? }`）+ 中间件面 ctx 注入 |
+| `handle.navigate(path)` / `refresh()` / `close()` | 导航 / 重渲染当前页 / 卸载 |
+| `ctx.route` | 当前路由 `{ path, params }`（对齐后端 ctx.params） |
+| `createRoot(vnode, root, { ctx })` | 无路由组件树挂载（`handle.ready` 首帧完成） |
 
 ---
 
@@ -94,10 +97,11 @@ const Home: Component<{}, ApiInjected & RouteInjected> = async (_init, ctx) => {
 }
 // 未声明的注入字段编译期报错——注入从"文档约定"变成"类型保证"
 
-const app = new UIRouter<{}>()
-  .use(api())                    // 注入 ctx.api
-  .use(toast())                  // 注入 ctx.toast
-uiServe(app, { root: '#root' })  // 类型累积完整（UIRouter<C & O>）
+// 中间件面展开 + createRouter（options.ctx 注入——类型由中间件函数累积）
+let ctx: any = {}
+ctx = api()(ctx)                 // 注入 ctx.api
+ctx = v3Toast()(ctx)             // 注入 ctx.toast
+createRouter(routes, root, { ctx })
 ```
 
 > 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/ui-dom` 导入）。