weifuwu 0.88.0 → 0.89.1

package/README.md

@@ -7,7 +7,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 ```
 
 **本地开发（apps/ 下的应用）**：dev 模式经 `node_modules/weifuwu/*` 软链解析到源码
-（`import 'weifuwu/ui-dom'` 等——esbuild bundle 的模块解析；tsconfig paths 只管类型）。
+（`import 'weifuwu/vdom'` 等——esbuild bundle 的模块解析；tsconfig paths 只管类型）。
 新环境 `npm install` 后执行 `node scripts/dev-links.mjs` 创建软链（apps 运行前提）。
 发布时才编译 dist（`node scripts/release.mjs`——dev 零构建）。
 
@@ -19,7 +19,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 |------|-----------|
 | **一个包，零构建** | 服务端 `node --import weifuwu/dev` 直跑 `.tsx`；浏览器 CDN import map 即用；CSS 一条 link 即得完整设计系统——没有构建步骤、没有脚手架 |
 | **协议层全自研** | PG v3 / RESP2 / GraphQL schema / OpenAI 流式协议全部自研——确定性、可预测、错误模型统一；诚实裁剪：**不支持的能力明确报错，绝不静默降级** |
-| **消灭样板** | 动态编译免构建、`ctx.data.get` 一个 API 覆盖 SSR 预取/hydration/SPA、自研 DB 客户端免双重编码与 parseRow 样板 |
+| **消灭样板** | 动态编译免构建、`useAsyncData` 一个 hook 覆盖 SSR 预取/hydration/SPA、自研 DB 客户端免双重编码与 parseRow 样板 |
 | **SaaS 地基随包内置** | rateLimit / email / userSystem / messager / queue / ai 六个中间件**互相咬合**（身份是消息的路由）——从「自建基础设施」变「声明业务」 |
 | **自托管友好** | 运行时仅 esbuild + graphql + ws；部署 = 一个 Node 进程 + Postgres + Redis；数据、代码、模型全部在自己手里 |
 
@@ -28,20 +28,21 @@ npm install weifuwu      # 一个依赖，完整应用栈
 | 层 | 入口 | 能力 |
 |----|------|------|
 | 后端 | `weifuwu` | Trie 路由 / 中间件链 / serve / 自研 PG+Redis / SSR / GraphQL / WebSocket |
-| 前端 | `weifuwu/ui-dom` | **vdom3 精准事件流引擎**——createRouter（路由）+ createRoot（挂载）+ 事件流（渲染本体：`entity:action` 统一命名、DOM = fold、可回放可断言）+ SSR（事件流序列化）；组件=两阶段异步组件 / ctx.params 对齐后端；**weifuwu/components 直接复用**（VNode 契约唯一来源 ui-dom，见 `content/guides/ui-dom-guide.md`） |
+| 前端 | `weifuwu/vdom` | **vdom 引擎**——UIRouter（路由唯一入口：get/notFound/has/resolve——`(Request, ctx) => Response` 签名对齐后端）+ uiServe（浏览器 boot）+ uiSsr（服务端渲染——SSR ≡ SPA 首帧结构吸收）+ 命令流渲染（NDJSON 命令纯数据可回放）；**weifuwu/components 直接复用**（VNode 契约唯一来源 vdom） |
 | 组件 | `weifuwu/components` | 129 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
-| 样式 | `weifuwu/layout` | 66 布局原语 + 157 工具类 + 182 主题 Token，零自定义 CSS 文件 |
+| 样式 | `weifuwu/layout` | 48 布局原语 + 90 工具类 + 183 主题 Token，零自定义 CSS 文件 |
 | SaaS 地基 | 随包内置 | rateLimit / email / userSystem / messager / queue / ai → `ctx.*` 一行接入 |
 
 > ⚠️ **注意：前后端都有 `ctx.ui`，但用途完全不同**
-> - **后端** `ctx.ui`（SSR/编译）：`ctx.ui.html`（HTML 模板）、`ctx.ui.js`（TSX→JS 动态编译）、`ctx.ui.css`（CSS 编译）、`ctx.ui.ssr`（组件 SSR）、`ctx.ui.ssrData`（数据序列化）
-> - **前端** `ctx.ui`（渲染引擎，20+ hooks）：
->   - 渲染：`render()`（唯一触发——render-only）/ `selfId()`（跨组件精准刷新）
->   - 状态：`useControlled()`（受控/非受控）/ `useStableRef()`（稳定 ref）/ `useExternal()`（共享状态订阅）
+> - **后端** `ctx.ui`（SSR/编译）：`ctx.ui.html`（HTML 模板）、`ctx.ui.js`（TSX→JS 动态编译）、`ctx.ui.css`（CSS 编译）、`ctx.ui.ssr`（组件 SSR）
+> - **前端** `ctx.ui`（渲染引擎，20+ hooks——**一切会变化的值都是 getter**）：
+>   - 数据：`useAsyncData(fetcher, key)`（唯一异步边界——同 key 并发合并/竞态取消/缓存保留/SSR 种子预热——**作者零退订零竞态代码**）
+>   - 状态：`signal(n)`（getter 读 + set/update 写——变化自动重渲染）/ `useObservable(obs$)`（任何 Observable → getter）/ `useExternal()`（共享状态）
+>   - 受控：`useControlled()`（受控/非受控）/ `useControlledInput()`（逐键回流）
 >   - 弹层：`usePopup()`（统一能力层——锚定浮层 + 会话级模态）/ `usePopupPosition()`（定位）
 >   - 事件：`useInView()` / `useScrollPosition()` / `useMedia()` / `useBreakpoint()` / `useGlobalKey()` / `useDrag()` / `useDragDrop()` / `useHoverCapable()` / `useLongPress()` / `useVisualViewport()`
->   - 动画：`useAnimationEnd()`（完成回调）/ `usePresence()`（显隐状态机）/ `useTween()`（数值补间）/ `useReducedMotion()`（偏好感知）
->   - AI/数据：`useChat()`（AI 会话）/ `useAsync()`（异步取数）
+>   - 动画：`useAnimationEnd()` / `usePresence()`（显隐状态机）/ `useTween()` / `useReducedMotion()`
+>   - AI/生命周期：`useChat()`（AI 会话）/ `hold(fn)`（卸载清理——等价 onUnmount）
 > 后端的是「把页面和代码交给浏览器」，前端的是「在浏览器里驱动 UI」。
 
 ### 与主流方案的关系
@@ -55,14 +56,13 @@ npm install weifuwu      # 一个依赖，完整应用栈
 | 认证 / 消息 / 队列 | **随包内置、互相咬合** | 自选 + 自缝 | 自选 + 自缝 |
 | 部署 | 一个 Node 进程 + PG + Redis | 各组件自理 | 平台绑定 |
 
-> 定位不是「替代某个框架」，而是**包换包**：用 weifuwu 一个依赖替换你原本要缝合的整套栈。心智模型有借鉴（两阶段组件接近 React、中间件接近 Express），但每一层都是自研的确定性实现——组件模型见[核心概念](#核心概念)，与 antd/Element Plus/shadcn 的对应见 [docs/components-map.md](docs/components-map.md)。
+> 定位不是「替代某个框架」，而是**包换包**：用 weifuwu 一个依赖替换你原本要缝合的整套栈。心智模型有借鉴（组件模型接近 React、中间件接近 Express），但每一层都是自研的确定性实现——组件模型见[核心概念](#核心概念)，与 antd/Element Plus/shadcn 的对应见 [docs/components-map.md](docs/components-map.md)。
 
 ### 从这里开始
 
 | 你想… | 去哪 |
 |--------|------|
 | 10 分钟跑通 SPA + SSR | [快速开始](#快速开始) |
-| 立刻体验（跑现成 demo） | 快速开始的「30 秒体验」 |
 | 零后端原型（一个 HTML 文件） | [CDN 快速原型](#cdn-快速原型零构建纯-html) |
 | 按任务找 API（认证/消息/AI/移动端…） | [能力速查](#能力速查任务--api) |
 | 读完整 API 参考 | [文档导航](#文档导航) |
@@ -71,13 +71,13 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 ## 设计理念
 
-> 顶部「定位」回答了**是什么 / 为什么**；以下是**哲学展开**——四条核心哲学与十一条技术原则。
+> 顶部「定位」回答了**是什么 / 为什么**；以下是**哲学展开**——五条核心哲学与技术原则。
 
 ### 核心哲学
 
 **① 一个包，全栈一体。** 后端、前端、组件、样式装在一个 npm 包里，零配置、零构建、纯 link 可用：服务端 `--import weifuwu/dev` 直接跑 `.tsx`（Node loader + esbuild 同步编译）；浏览器 CDN import map 直接跑；CSS 一条 link 即得完整设计系统。
 
-**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**（已裁剪清单见组件裁剪登记）。
+**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**。
 
 **③ 消灭样板。** 框架的每一层都在消灭一类样板代码：
 
@@ -85,38 +85,28 @@ npm install weifuwu      # 一个依赖，完整应用栈
 |---|---|
 | 构建样板 | 动态编译（`ctx.ui.js` / `weifuwu/dev`），改代码即刷即用，零构建步骤 |
 | 样式样板 | WUI 设计语言 + 语义原语 + 变量定制，零自定义 CSS 文件（`--wf-brand-seed` 改一个值全站换肤，暗色自动派生） |
-| 数据样板 | `ctx.data.get` 一个 API 覆盖 SSR 预取 / hydration 命中 / SPA fetch，写数据像写同步代码 |
+| 异步样板 | `useAsyncData` 内建并发合并/竞态取消/缓存保留/SSR 种子——**作者零退订、零竞态、零 loading 样板** |
 | 协议样板 | 自研 PG/Redis 客户端消灭双重编码、parseRow 样板、`'EX'` 参数顺序陷阱 |
 
-**④ SaaS 地基，应用必须的一等能力。** 不只是库——rateLimit / email / userSystem / messager / queue 五个中间件随包内置，且互相咬合：**身份是消息的路由，消息是身份的交互**（`sendTo(ctx.user.id)` 按身份路由、`createConversation(ctx.user.id)` 创建者即身份、成员校验自动对齐），AI 对话走同一协议。开发者从「自建基础设施」变「声明业务」——`app.use(...)` 一行接入，一个多租户 AI 平台（agent-platform）已完整消费这层地基（auth / AI / 消息 / UI / 数据管道全部框架能力）。
+**④ SaaS 地基，应用必须的一等能力。** 不只是库——rateLimit / email / userSystem / messager / queue 五个中间件随包内置，且互相咬合：**身份是消息的路由，消息是身份的交互**（`sendTo(ctx.user.id)` 按身份路由、`createConversation(ctx.user.id)` 创建者即身份、成员校验自动对齐），AI 对话走同一协议。开发者从「自建基础设施」变「声明业务」——一个多租户 AI 平台（agent-platform）已完整消费这层地基。
 
-### 技术原则（哲学的展开）
-
-**零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 作为运行时依赖随 `npm install weifuwu` 自动安装，`ctx.ui.js()` 开箱即用。
-
-**两阶段组件模型** — 组件 = `async (initProps, ctx) => (props) => Promise<VNode>`。外层工厂只执行一次（mount，可 await 数据），内层 renderFn 每次状态/props 变化时执行（强制异步）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
-
-**render-only 确定性渲染** — 渲染唯一触发 `ctx.ui.render()`（闭包绑定组件），状态是普通对象（`let` + `render()`）；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。行为可静态推导，无隐式触发（详见[组件库](content/guides/components-guide.md)）。
-
-**VDOM 输出透明（写 JSX，看 DOM 即真相）** — VDOM 对用户输入零 magic：条件渲染的 false 在 DOM 里是诊断占位注释（`<!--wf-hole: false-->`），数组项 key 与组件实例 id 直接落 DOM（`data-wf-key` / `data-wf-id`）——devtools 看到的 DOM 就是引擎决策的可读输出；非法输入占位 + warn，不崩溃不静默。转化契约唯一清晰：用户写什么，vnode 就是什么，DOM 就长什么样（规则表为内部开发契约）。
+**⑤ 错误现形，自愈不可消音。** 渲染错误** hole 降级 + 下一拍重试**是容错不是静默——错误必须计数现形（`error-counter` 同错去重不刷屏、恢复清出再报）；路由错误同样去重计数。dev 仪表 `window.__wfRenderHealth` 四轴读数（频率/规模/复用/错误）——**问题出现即读数**，不是问题出现后翻日志。
 
-**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` / `ctx.limit` / `ctx.email` / `ctx.queue` / `ctx.ai` / `ctx.msg` 等），Handler/组件从 `ctx` 读取。
-
-**async 工厂组件** — `async (initProps, ctx) => (props) => Promise<VNode>`（weifuwu **唯一组件形态**——同步组件已不支持）：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`let` + `render()`）、render 输出视图。异步在工厂边界与 renderFn，数据经闭包注入，写数据像写同步代码。三条纪律见[核心概念 · async 组件](#核心概念)。
+### 技术原则（哲学的展开）
 
-**SPA/SSR/Hydration 统一透明** — 同一份路由定义（`createRouter`）一个组件三场景自动适配：后端将 vnode 构建为**事件流**（`renderToEvents`）→ `eventsToHtml` 输出完整 HTML + `serializeEvents` 序列化进 `__DATA__`，客户端 `deserializeEvents` + `replay` 收养（DOM = fold(事件流)——零 DOM 猜测、不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
+**零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。
 
-**AI 是一等公民** — 自研 OpenAI 兼容协议（`docs/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批 + embedding 向量化。后端 `ctx.ai` 一个入口：`chat()` / `stream()` / `agent()`（`stream(messages, { emit })` emitter 抽象——事件可接任意通道，`runToResult()` 结构化结果）/ `approve()` / `embed()` / `embedMany()`；前端 `ctx.ui.useChat()`（会话语义）+ `AiChat` 组件（标准对话界面）——流式 token / 工具调用卡 / 审批卡开箱即用，协议对页面完全透明，不用 ai-sdk。
+**前后端同构，机制公用、实现不一样** — handler 签名 `(req: Request, ctx) => Response` 双端字面同构；**路由内核五层单源**（`src/shared/router/`：trie 匹配 / pipeline 流程骨架 / context URL 解析与 ctx 注入 / chain 中间件链 / ctx-fields 扩展注册表）——`Router.handler()` 与 `UIRouter.resolve()` 跑同一个 `dispatchRouter`，差异点（verb 表/404 形态/错误语义/ctx 扩展）钩子化，**serve（Request/Response 编解码边界）留各自域**。
 
-**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见[SaaS 地基模块](content/guides/saas-guide.md)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
+**工厂同步，异步边界全在 hooks，渲染纯同步** — 组件 = `(initProps, ctx) => (props) => VNode`（**同步工厂——async 即编译错**）。数据加载 `useAsyncData`、多源汇流 `useObservable`——异步全部收敛在 hooks 内部流管道（卸载自动退订——零泄漏）；渲染纯同步（无 async 渲染、无中间态占位）。**一条规则易学易写易用**。
 
-**机制与策略分离** — 框架管**机制**（token 怎么签、消息怎么送达、agent 循环怎么跑），开发者管**策略**（谁能建群、租户隔离 SQL、技能注册表）。这是「诚实裁剪」的积极面：**框架不越界，应用层不被绑架**——agent-platform 迁移验证了边界：多租户隔离（`WHERE tenant_id`）、技能编排、聊天产品模型留在应用层，框架守住通用能力（auth / ai / messager / UI / 数据管道）。
+**信号 getter 纪律** — 一切会变化的值 = `() => T`——**任何位置调用返回最新值**——没有「必须在 render 内调用」的位置规则。`signal` 读 getter + set/update 写，变化自动重渲染；hooks 全部 getter 化（`useScrollPosition()` 返回最新位置）。
 
-**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，主题改一个值（`--wf-brand-seed` 换肤 / `data-preset` 预设 / `--wf-btn-radius` 钩子），暗色自动（详见[布局系统](content/guides/layout-guide.md)与[主题配置](content/guides/styling.md)）。
+**VDOM 输出透明（命令流可回放）** — 渲染 = **命令流**（NDJSON 纯数据——13 种命令完整自足：create/insert/setText/…）——DOM = fold(命令流)，可记录、可回放、可断言。VDOM 对用户输入零 magic：条件渲染的 false 在 DOM 里是诊断占位注释，数组项 key 与组件实例 id 直接落 DOM——devtools 看到的 DOM 就是引擎决策的可读输出。
 
-**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
+**对账防线（演绎保证——错必被抓）** — 双树终态等价对账器 + 命令流模拟器（Sim）+ 状态机迁移表（编译期穷尽）+ fuzz 生成器（1310 对多种子）——**状态机保证暴露机制完整，对账器保证错误必被抓**，两者互补缺一不可。四层验证体系见 [AGENTS.md](AGENTS.md)。
 
-> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（129 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
+**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` / `ctx.limit` / `ctx.email` / `ctx.queue` / `ctx.ai` / `ctx.msg` 等），Handler/组件从 `ctx` 读取——**注入声明（injects/depends）双端同一注册表机制**。
 
 ---
 
@@ -126,22 +116,30 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 | 模式 | 适用场景 | 后端 | 客户端入口 |
 |------|---------|------|-----------|
-| **SPA** | 应用页（Dashboard、工具、后台） | HTML 外壳 | `createRouter(routes, root, { ctx })` |
-| **SSR + Hydration** | 内容页（博客、营销，需要 SEO/首屏） | `renderToEvents` → `eventsToHtml` + `serializeEvents` | `deserializeEvents` + `replay`（事件流收养） |
+| **SPA** | 应用页（Dashboard、工具、后台） | HTML 外壳 | `uiServe(router, { root })` |
+| **SSR + Hydration** | 内容页（博客、营销，需要 SEO/首屏） | `uiSsr(router, url)`（HTML + `__DATA__` 种子） | `uiServe`（结构吸收——首帧复用服务端 DOM） |
 
 ### 先写共享部分（两种模式都一样）
 
 ```tsx
-// routes.tsx —— 路由声明（createRouter——vdom3 事件流引擎）
-import { createRouter, h } from 'weifuwu/ui-dom'
-
-// async 组件（原生）：await 数据 → 返回视图（外层初始化，内层渲染）
-const Home = async (_init, ctx) => {
-  const msg = await ctx.data.get('/api/hello')   // 数据管道：一个 API 三场景
-  return async (props) => <h1>{msg.msg}</h1>
+// router.tsx —— 路由树（UIRouter——前后端同一棵树——单一实现源）
+import { UIRouter, h, type UIContext } from 'weifuwu/vdom'
+
+const Home = (_: unknown, ctx: UIContext) => {
+  // 数据管道：一个 API 三场景（SSR 预取 / hydration 命中 / SPA fetch）
+  const [getMsg] = ctx.ui.useAsyncData(() => fetch('/api/hello').then((r) => r.json()), 'hello')
+  const msg = getMsg()
+  if (!msg) return <p>加载中…</p>
+  return <h1>{msg.msg}</h1>
 }
 
-export const routes = [{ path: '/', render: () => h(Home, {}) }]
+export function buildRouter(): UIRouter {
+  const router = new UIRouter()
+  router.get('/', () => h(Home))
+  router.get('/u/:id', (req, ctx) => h('h1', {}, `用户 ${ctx.params.id}`))   // :param 注入
+  router.notFound(() => h('h1', {}, '404'))
+  return router
+}
 ```
 
 ### 模式 A：纯 SPA
@@ -169,11 +167,11 @@ serve(router, { port: 3000 })
 ```
 
 ```ts
-// src/client.ts —— 纯客户端渲染（vdom3 事件流引擎）
-import { createRouter } from 'weifuwu/ui-dom'
-import { routes } from './routes.tsx'
+// src/client.ts —— 浏览器 boot（uiServe——UIRouter 唯一应用入口）
+import { uiServe } from 'weifuwu/vdom'
+import { buildRouter } from './router.tsx'
 
-createRouter(routes, document.querySelector('#root')!, { ctx })   // 监听 location → 匹配 → 事件流渲染
+uiServe(buildRouter(), { root: '#root' })   // 监听导航 → 匹配 → 命令流渲染
 ```
 
 ### 模式 B：SSR + Hydration（内容页/SEO）
@@ -181,23 +179,22 @@ createRouter(routes, document.querySelector('#root')!, { ctx })   // 监听 loca
 同一份 `routes`、同一个组件，差异只在**后端构建事件流 → HTML + 序列化事件，客户端回放**：
 
 ```ts
-// server.ts —— SSR：vnode → 事件流 → 完整 HTML + __DATA__（DOM = fold 不变量）
+// server.ts —— SSR：同一棵路由树 → 完整 HTML + __DATA__（SSR ≡ SPA 首帧）
 import { serve, Router, ui, cors } from 'weifuwu'
-import { renderToEvents, eventsToHtml, serializeEvents } from 'weifuwu/ui-dom'
-import { routes } from './routes.tsx'
+import { uiSsr } from 'weifuwu/vdom'
+import { buildRouter } from './router.tsx'
 
 const router = new Router()
 router.use(cors())
 router.use(ui())
 
-// 路由级 SSR：匹配共享 routes → 构建 vnode → 事件流 → HTML + __DATA__ 序列化
+// SSR：路由树单源 → 服务端渲染 → HTML + __DATA__ 种子（客户端结构吸收零闪跳）
 router.get('*', async (req, ctx) => {
-  const def = routes.find((r) => r.path === (req.url ?? '/'))
-  const events = await renderToEvents(def?.render({}) ?? null)   // 事件流（服务端真 fetch 数据）
-  const page = `<!doctype html><html><body><div id="root">${eventsToHtml(events)}</div>
-    <script>window.__DATA__=${serializeEvents(events)}</script>
-    <script src="/static/app.js"></script></body></html>`
-  return ctx.ui.html.unsafe(page)
+  const html = await uiSsr(buildRouter(), new URL(req.url).pathname, {
+    title: '我的应用',
+    prefetch: async () => ({ hello: await (await fetch('http://localhost:3000/api/hello')).json() }),
+  })
+  return ctx.ui.html.unsafe(html)
 })
 
 router.get('/static/app.js', (req, ctx) => ctx.ui.js('./src/client.ts'))
@@ -207,13 +204,12 @@ serve(router, { port: 3000 })
 ```
 
 ```ts
-// src/client.ts —— 事件流回放收养（deserializeEvents + replay——零 DOM 猜测）
-import { createRouter, deserializeEvents, replay } from 'weifuwu/ui-dom'
-import { routes } from './routes.tsx'
+// src/client.ts —— 结构吸收（uiServe 首帧复用服务端 DOM——零闪跳）
+import { uiServe } from 'weifuwu/vdom'
+import { buildRouter } from './router.tsx'
 
-const root = document.querySelector('#root')!
-replay(deserializeEvents((window as any).__DATA__), root)  // 收养服务端 HTML（无闪跳）
-createRouter(routes, root)                                  // 之后正常交互渲染
+// 同一棵路由树：服务端 HTML 被吸收（焦点/输入值保持），之后正常交互渲染
+uiServe(buildRouter(), { root: '#root' })
 ```
 
 ### 启动（两种模式都一样）
@@ -244,15 +240,6 @@ cd apps/agent-platform && npm run seed && npm run dev
 
 > 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」——一个 `.html` 文件即可。
 
-### 📦 安装后离线文档（content/ 随包发布）
-
-```bash
-npm i weifuwu
-npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表/纪律/示例/验证）
-```
-
-`node_modules/weifuwu/content/` 是完整文档库（逐组件文档 + 页面/应用模板 + 后端能力 + 指南 + 选型决策树 + 人类质量标准）——版本永远匹配安装的代码；`examples/` 是可复制源码（页面模式 + 应用模板 todo/auth/admin/multi）。LLM 开发路径：`read node_modules/weifuwu/content/index.md` → 目标 .md → 复制 examples/ 源码。
-
 ---
 
 ## CDN 快速原型（零构建、纯 HTML）
@@ -268,7 +255,7 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Weifuwu CDN 示例</title>
 
-  <!-- 组件样式（可选，如只用 weifuwu/ui-dom 则不需要） -->
+  <!-- 组件样式（可选，如只用 weifuwu/vdom 则不需要） -->
   <link
     rel="stylesheet"
     href="https://unpkg.com/weifuwu@latest/dist/components/style.css"
@@ -281,57 +268,34 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
   <script type="importmap">
     {
       "imports": {
-        "weifuwu/ui-dom": "https://unpkg.com/weifuwu@latest/dist/ui-dom/index.js",
+        "weifuwu/vdom": "https://unpkg.com/weifuwu@latest/dist/vdom/index.js",
         "weifuwu/components": "https://unpkg.com/weifuwu@latest/dist/components/index.js"
       }
     }
   </script>
 
   <script type="module">
-    import { createRouter, h } from 'weifuwu/ui-dom'
-    import { Card, Button, Badge } from 'weifuwu/components'
-
-    // 组件 = async (initProps, ctx) => (props) => Promise<VNode>（render-only：改状态后 ctx.ui.render()）
-    const Counter = async (_init, ctx) => {
-      let count = 0 // mount 初始化
-
-      return () =>
-        h(Card, { variant: 'default', padding: 'lg' },
-          h('h2', { style: { textAlign: 'center', margin: 0 } }, '⚡ Weifuwu'),
-          h('div', { style: { fontSize: '4rem', fontWeight: 600, textAlign: 'center' } },
-            String(count)),
-          h('div', { style: { textAlign: 'center', marginTop: '1rem' } },
-            h(Badge, {
-              variant: count % 2 === 0 ? 'success' : 'warning'
-            }, count % 2 === 0 ? '偶数' : '奇数')),
-          h('hr', { style: { margin: '1rem 0', border: 'none', borderTop: '1px solid #eee' } }),
-          h('div', { style: { display: 'flex', gap: '0.5rem', justifyContent: 'center' } },
-            h(Button, { variant: 'secondary', onClick: () => { count--; ctx.ui.render() } }, '➖ 减 1'),
-            h(Button, { variant: 'danger', onClick: () => { count = 0; ctx.ui.render() } }, '↺ 重置'),
-            h(Button, { variant: 'primary', onClick: () => { count++; ctx.ui.render() } }, '➕ 加 1'),
-          ),
-        )
-    }
+    import { UIRouter, uiServe, h } from 'weifuwu/vdom'
 
-    // 路由 + 渲染（vdom3 事件流引擎：createRouter——监听 location → 匹配 → 事件流落地）
-    createRouter(
-      [{ path: '/', render: () => h(Counter, {}) }],
-      document.querySelector('#root')!,
-    )
+    // 路由树（UIRouter——get/notFound——(req, ctx) => Response 同构后端）
+    const router = new UIRouter()
+    router.get('/', () => h('h1', {}, 'Hello weifuwu'))
+    router.get('/u/:id', (req, ctx) => h('h1', {}, `用户 ${ctx.params.id}`))
+    router.notFound(() => h('h1', {}, '404'))
+
+    // 浏览器 boot（uiServe——监听导航 → 匹配 → 命令流渲染）
+    uiServe(router, { root: '#root' })
   </script>
+  <!-- 对照服务端：new Router().get('/', () => new Response(...))——同一签名形状 -->
 </body>
 </html>
 ```
 
-将此 HTML 保存到本地用浏览器打开即可运行。
-
-### CDN 资源地址说明
-
-| 资源 | CDN 地址 | 说明 |
+| 模块 | CDN 路径 | 说明 |
 |------|---------|------|
-| `weifuwu/ui-dom` | `https://unpkg.com/weifuwu@latest/dist/ui-dom/index.js` | 前端运行时（createRouter, createRoot, h, 事件流, 状态管理等） |
+| `weifuwu/vdom` | `https://unpkg.com/weifuwu@latest/dist/vdom/index.js` | 前端运行时（UIRouter, uiServe, h/jsx, hooks 等） |
 | `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 129 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 182 个主题 Token + 66 个布局原语 + 157 个工具类 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 183 个主题 Token + 48 个布局原语 + 90 个工具类 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -342,6 +306,7 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
 | 导入路径 | 模块 | 用途 | 依赖 |
 |---------|------|------|------|
 | `weifuwu` | **Router** | Trie 路由 + 中间件链 + WebSocket + GraphQL | — |
+| `src/shared/router` | **路由内核（前后端共享五层单源）** | trie（匹配）+ pipeline（流程骨架）+ context（URL 解析/ctx 注入）+ chain（中间件链）+ ctx-fields（ctx 扩展注册表）——**同一套机制双端复用**，serve（编解码边界）留各自域 | — |
 | `weifuwu` | **serve** | HTTP 服务器 | Router |
 | `weifuwu` | **cors** | CORS 跨域中间件 | Router |
 | `weifuwu` | **serveStatic** | 静态文件服务（ETag/304/目录索引） | Router |
@@ -349,8 +314,8 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
 | `weifuwu` | **redis** | Redis 客户端（自研 RESP2 协议）→ `ctx.redis` | Router, REDIS_URL |
 | `weifuwu/db` | **Memory 实现** | `createMemorySql()` / `MemoryRedis`——生产契约黑盒实现（开发/测试/单实例零数据库）；`MemoryRedisServer`/`MemoryPostgresServer`——进程内线协议服务器（协议测试零 docker） | — |
 | `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
-| `weifuwu/ui-dom` | **createRouter** | vdom3 路由：RouteDef[] + 中间件面 ctx 注入（对齐后端 `app.use`）——监听 location → 匹配 → 事件流渲染 | — |
-| `weifuwu/ui-dom` | **SSR（事件流形态）** | `renderToEvents` → `eventsToHtml` + `serializeEvents`（DOM = fold——客户端 `replay` 收养） | Router, ui |
+| `weifuwu/vdom` | **UIRouter** | 前端路由唯一入口：get/notFound/has/resolve——`(req, ctx) => Response` 签名对齐后端——params/query/route 注入（shared Trie 五层单源） | — |
+| `weifuwu/vdom` | **uiServe / uiSsr** | uiServe 浏览器 boot（导航监听 → 命令流渲染）；uiSsr 服务端渲染（HTML + `__DATA__` 种子——**结构吸收** SSR ≡ SPA 首帧） | Router, ui |
 | `weifuwu` | **rateLimit** | 限流中间件（fixed/sliding，redis 多实例原子）→ `ctx.limit` | Router, redis |
 | `weifuwu` | **email** | 邮件发送（Resend/SMTP 自研/自定义适配器）→ `ctx.email` | Router |
 | `weifuwu` | **userSystem** | 用户系统（scrypt 密码哈希 + 混合会话 + 多租户感知）→ `ctx.user` / `ctx.auth` / `ctx.tenantId` + `/api/auth/*` | Router, postgres |
@@ -364,17 +329,17 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
 | `weifuwu` | **ok / badRequest / …** | HTTP 响应辅助函数（ok/badRequest/... 等 12 个） | — |
 | `weifuwu` | **parseBody** | JSON 请求体安全解析 | — |
 | Router 方法 | **app.graphql()** | GraphQL 端点（支持 GraphiQL），Router 实例方法（无需单独 import） | Router |
-| `weifuwu/ui-dom` | **createRouter / createRoot** | vdom3 事件流引擎：路由（RouteDef[] + ctx 注入）/ 挂载（组件树）——渲染全链路 `entity:action` 事件流（DOM = fold——可记录/回放/断言）；**事件代理**（监听 O(1)——零重绑——统一注册表）；**app 节点**（多应用加载——registerApp） | — |
-| `weifuwu/ui-dom` | **事件流原语** | `stream` / `ev` / `evKey` / `replay` / `eventsOf` / `expectEventSequence`——渲染可观测/可断言 | — |
-| `weifuwu/ui-dom` | **async 组件** | async 函数即组件（与同步同签名）；数据走 ctx.data 三场景（三条纪律见[核心概念](#核心概念)） | — |
-| `weifuwu/ui-dom` | **ctx.data** | 数据管道：SSR 预取 / hydration 命中 / SPA fetch（`ctx.data.get`） | — |
-| `weifuwu/ui-dom` | **api / auth / ws** | HTTP 客户端 / 认证 / WebSocket 中间件 | — |
-| `weifuwu/ui-dom` | **i18n** | 国际化中间件（运行时切换语言） | — |
-| `weifuwu/ui-dom` | **renderToEvents / eventsToHtml / serializeEvents** | 服务端渲染：vnode → 事件流 → HTML + `__DATA__` 序列化（客户端 `replay` 收养） | — |
-| `weifuwu/ui-dom` | **useChat / AiChat 原语** | AI 会话（流式/工具调用/HITL） | — |
-| `weifuwu/ui-dom` | **事件原语** | `usePopup`（统一弹窗能力层）/ `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 [content/guides/mobile-guide.md](content/guides/mobile-guide.md)） | — |
-| `weifuwu/components` | **129 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
-| `weifuwu/layout` | **CSS 布局** | 66 个布局原语 + 157 个工具类 + 182 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/vdom` | **命令流渲染引擎** | 渲染 = 命令流（NDJSON 纯数据——13 命令完整自足——可回放可断言）；**事件代理**（监听 O(1)——零重绑——统一注册表）；三状态机 + 对账器（终态等价 fuzz 1310 对防线） | — |
+| `weifuwu/vdom` | **渲染健康仪表** | `window.__wfRenderHealth`（频率/规模/复用/错误四轴——dev 模式——渲染问题出现即读数） | — |
+| `weifuwu/vdom` | **组件契约** | 工厂同步（`(initProps, ctx) => RenderFn`）——异步边界全在 hooks（useAsyncData/useObservable）——渲染纯同步（见[核心概念](#核心概念)） | — |
+| `weifuwu/vdom` | **useAsyncData** | 数据管道：同 key 并发合并 / 竞态取消 / 缓存保留 / SSR 种子预热（`ctx.ui.useAsyncData(fetcher, key)`） | — |
+| `weifuwu/vdom` | **api / auth / ws / i18n** | HTTP 客户端 / 认证 / WebSocket / 国际化中间件（ctx 注入） | — |
+
+| `weifuwu/vdom` | **hooks 全家** | usePopup/useControlled/useExternal/useInView/useScrollPosition/useTween/useBreakpoint/... （getter 纪律——任意位置读最新） | — |
+| `weifuwu/vdom` | **useChat / AiChat 原语** | AI 会话（流式/工具调用/HITL） | — |
+| `weifuwu/vdom` | **事件原语** | `usePopup`（统一弹窗能力层）/ `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 —） | — |
+| `weifuwu/components` | **129 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/vdom |
+| `weifuwu/layout` | **CSS 布局** | 48 个布局原语 + 90 个工具类 + 183 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -384,106 +349,102 @@ npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表
 
 | 任务 | 用 | 位置 |
 |------|-----|------|
-| 起 HTTP 服务 + 路由 | `serve(app)` + `new Router()` + `app.get/post/...` | [content/guides/server-guide.md](content/guides/server-guide.md) |
-| 渲染页面（SPA / SSR） | `createRouter(routes, root, { ctx })`；SSR = `renderToEvents` → `eventsToHtml` + `replay`（事件流形态） | [content/guides/ui-dom-guide.md](content/guides/ui-dom-guide.md) · [content/guides/frontend.md](content/guides/frontend.md) |
-| 数据持久化 | `postgres()` → `` ctx.sql`SELECT *` `` · `redis()` → `ctx.redis` · **`sql.query`**（Query Language AST 双后端） | [content/guides/data-guide.md](content/guides/data-guide.md) |
-| 零数据库开发/测试 | `createMemorySql()` / `MemoryRedis`——契约同真库、替换成本为零 | [content/guides/data-guide.md](content/guides/data-guide.md) |
-| 数据管道（SSR 预取/hydration/SPA） | `ctx.data.get(key)` + async 组件 | [content/guides/frontend.md](content/guides/frontend.md) |
-| 用户注册/登录/会话/多租户 | `userSystem()` → `ctx.auth` + `/api/auth/*` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| 限流防爆破 | `rateLimit()` + `ctx.limit()` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| 发邮件 | `email()` → `ctx.email`（Resend/SMTP） | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| 实时消息/聊天/通知 | `messager()` → `ctx.msg` + `app.ws` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| 后台任务/定时 | `queue()` → `ctx.queue` · `scheduler()` → `ctx.schedule/cron` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| AI 对话 / Agent / HITL 审批 | `ai()` → `ctx.ai` + `ctx.ui.useChat()` + `AiChat` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
-| GraphQL / WebSocket | `app.graphql(handler)` · `app.ws(path, handler)` | [content/guides/realtime-guide.md](content/guides/realtime-guide.md) |
-| 前端 UI 组件 | `weifuwu/components`（129 个：Button/Table/Modal/AiChat/...） | [content/guides/components-guide.md](content/guides/components-guide.md) |
-| 布局/主题/暗色 | `weifuwu/layout`（58 原语 + 157 工具类 + 182 Token） | [content/guides/layout-guide.md](content/guides/layout-guide.md) |
-| 样式定制（零自定义 CSS） | `--wf-*` 变量覆盖 + 组件定制钩子 | [content/guides/styling.md](content/guides/styling.md) |
-| 移动端适配（tap/长按/键盘/弹层） | `usePopup` / `useHoverCapable` / `useLongPress` / `useVisualViewport` | [content/guides/mobile-guide.md](content/guides/mobile-guide.md) |
-| 前后端类型安全中间件 | `createMiddleware`（声明注入即类型化） | [content/guides/server-guide.md](content/guides/server-guide.md) |
+| 起 HTTP 服务 + 路由 | `serve(app)` + `new Router()` + `app.get/post/...` | — |
+| 渲染页面（SPA / SSR） | `UIRouter` + `uiServe(router, { root })`；SSR = `uiSsr(router, url)`（结构吸收——首帧零差异） | — · — |
+| 数据持久化 | `postgres()` → `` ctx.sql`SELECT *` `` · `redis()` → `ctx.redis` · **`sql.query`**（Query Language AST 双后端） | — |
+| 零数据库开发/测试 | `createMemorySql()` / `MemoryRedis`——契约同真库、替换成本为零 | — |
+| 数据管道（SSR 预取/hydration/SPA） | `ctx.ui.useAsyncData(fetcher, key)`（并发合并/竞态取消/SSR 种子） | — |
+| 用户注册/登录/会话/多租户 | `userSystem()` → `ctx.auth` + `/api/auth/*` | — |
+| 限流防爆破 | `rateLimit()` + `ctx.limit()` | — |
+| 发邮件 | `email()` → `ctx.email`（Resend/SMTP） | — |
+| 实时消息/聊天/通知 | `messager()` → `ctx.msg` + `app.ws` | — |
+| 后台任务/定时 | `queue()` → `ctx.queue` · `scheduler()` → `ctx.schedule/cron` | — |
+| AI 对话 / Agent / HITL 审批 | `ai()` → `ctx.ai` + `ctx.ui.useChat()` + `AiChat` | — |
+| GraphQL / WebSocket | `app.graphql(handler)` · `app.ws(path, handler)` | — |
+| 前端 UI 组件 | `weifuwu/components`（129 个：Button/Table/Modal/AiChat/...） | — |
+| 布局/主题/暗色 | `weifuwu/layout`（49 原语 + 90 工具类 + 183 Token） | — |
+| 样式定制（零自定义 CSS） | `--wf-*` 变量覆盖 + 组件定制钩子 | — |
+| 移动端适配（tap/长按/键盘/弹层） | `usePopup` / `useHoverCapable` / `useLongPress` / `useVisualViewport` | — |
+| 前后端类型安全中间件 | `createMiddleware`（声明注入即类型化） | — |
 
 ---
 
 ## 核心概念
 
-### 三层形态（路由 / 组件 / async 组件工厂）
-
-| 层 | 签名 | 异步 | 生命周期 |
-|----|------|------|---------|
-| **UIHandler**（路由） | `async (location, ctx) => VNode` | ✅ 整体 | 每次路由变化执行 |
-| **Component**（唯一形态） | `async (initProps, ctx) => (props) => Promise<VNode>` | ✅ 工厂 + renderFn | mount 一次 + render 每次；同步组件已不支持（类型强制 Promise） |
+### 一条规则：工厂同步、异步在 hooks、渲染纯同步
 
-异步只在两个边界——路由 handler（整页）和组件工厂（数据声明）+ renderFn（强制异步）。渲染器按「返回值 instanceof Promise」统一判别：主路径 `buildVNode` async 预构建（await 全部工厂，兄弟并行）→ 原子落地（无**中间态**占位、无补全回调——注意：数组内 false/null 的静态诊断占位 `<!--wf-hole-->` 是另一回事，见「VDOM 输出透明」）；运行时首次挂载的 async 组件同样在 buildVNode 阶段 await；骨架屏：预置骨架屏 HTML → 首帧原子替换 + `handle.ready`。
-### 两阶段组件（新手必读：为什么是两层）
-
-组件 = `async (initProps, ctx) => (props) => Promise<VNode>`——**外层 = 初始化（只执行一次，可 await 数据），内层 = 渲染（每次状态/props 变化时执行，强制异步）**。类比：外层是对象的构造函数，内层是它的 render 方法。
+```tsx
+type Component<P, C> = (initProps: P, ctx: C) => RenderFn<P>   // 工厂同步（毫秒即挂载完）
+type RenderFn<P> = (props: P) => VNode | null | (VNode | null)[]  // 渲染纯同步
+```
 
 ```tsx
-const Counter = async (_init, ctx) => {
-  // 外层（mount）：只跑一次——初始化状态、订阅、定时器（可 await 数据）
-  let count = 0
-  return async (props) =>
-    // 内层（render）：每次变化执行（强制异步）——读状态输出视图（render-only：改状态后显式 render()）
-    <button onClick={() => { count++; ctx.ui.render() }}>{count}</button>
+const Counter = (_init, ctx) => {
+  // 工厂（mount 一次）：建 signal、订阅、定时器——同步执行
+  const count = ctx.ui.signal(0)
+  return () => (
+    // 渲染（每次变化自动执行）：读 getter——最新值
+    <button onClick={() => count.set((c) => c + 1)}>{count()}</button>
+  )
 }
 ```
 
-> 为什么不是单层函数（React 风格）？单层函数每次渲染都执行整个函数体，需要 hooks 记忆机制来区分"初始化"和"渲染"；两阶段用**位置即语义**——外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱。
-> 异步数据用原生 async 组件（见下文）：`async (initProps, ctx) => await ctx.data.get(...)` → 返回 renderFn，数据经闭包注入。
+> **为什么工厂必须同步？** 同步工厂 = 毫秒级挂载（无 mounting 窗口、无 async
+> 竞态、SSR/客户端行为完全一致）。异步需求全部收敛到 hooks 内部流管道——
+> 作者层面**没有 await 渲染**这件事。事件回调内 `await` 合法（非渲染路径）。
 
-### 中间件模式（前后端一致）
+### 数据：useAsyncData（唯一异步边界）
 
-```
-后端:  app.use(cors())
-       app.use(postgres())
-       app.get('/users', (req, ctx) => { ctx.sql`SELECT *` })
-       // ctx 已注入 ctx.sql
-
-前端:  const router = createRouter(routes, root, { ctx })
-       router.use(api({ baseURL: '/api' }))
-       router.use(auth())
-       router.get('/users', async (location, ctx) => h(UsersPage, {}))
-       // createRouter = 监听 location → 匹配 → 事件流渲染落地
-       // ctx 已注入 ctx.api, ctx.auth
+```tsx
+const Home = (_: unknown, ctx: UIContext) => {
+  const [getMsg, reload] = ctx.ui.useAsyncData(
+    () => fetch('/api/hello').then((r) => r.json()), 'hello')
+  const msg = getMsg()                  // getter——最新值（null = loading/降级）
+  if (!msg) return <p>加载中…</p>
+  return <h1>{msg.msg} <button onClick={reload}>刷新</button></h1>
+}
 ```
 
-前端 req = `window.location`，res = `VNode`，`createRouter` = 事件流渲染落地——与后端 `Request → Response`、`serve(router)` 完全同构。
+**内建语义（作者零代码）**：同 key 并发合并（N 组件 fetch 1 次）· 竞态取消
+（旧请求作废）· 缓存保留（重挂载零请求）· 卸载自动退订（零泄漏）· SSR 种子
+预热（首帧零请求）。多源汇流：`ctx.ui.useObservable(obs$)` + `combineLatest`。
 
-### 状态管理
+### 路由：前后端同一内核
 
-| 模式 | 后端 | 前端 |
-|------|------|------|
-| 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
-| 读取 | handler 读取 ctx | 组件读取 ctx |
-| 渲染 | 返回 Response | `ctx.ui.render()` 触发局部 VDOM patch（render-only）；共享状态 `createStore` + `useExternal` |
+```
+后端:  const app = new Router()
+       app.get('/u/:id', (req, ctx) => Response.json(ctx.params))
+       serve(app, { port: 3000 })
 
-### async 组件（三条纪律）
+前端:  const router = new UIRouter()
+       router.get('/u/:id', (req, ctx) => h('h1', {}, ctx.params.id))
+       uiServe(router, { root: '#root' })
+```
 
-async 组件让"拿数据渲染页面"像写同步代码——签名与同步组件一致，唯一差别是 `async` 关键字：`async (initProps, ctx) => renderFn`。异步只在工厂边界：
+**`(req: Request, ctx) => Response` 字面同构**——两者内部跑同一个
+`dispatchRouter`（`src/shared/router/` 五层单源：trie 匹配 / pipeline 骨架 /
+context 解析与注入 / chain 中间件链 / ctx-fields 注册表）。差异点钩子化：
+verb 表（server）/ctx.route 注入（client）/404 形态——**serve（编解码边界）留各自域**。
+
+### 中间件注入一切（前后端一致）
 
-```tsx
-const UserProfile = async (_init, ctx) => {
-  const user = await ctx.data.get(`/api/user/${ctx.params.id}`)   // ① 工厂层：声明数据（三场景自动）
-  let liked = false                                                // ② mount：客户端状态（render-only）
-  return async (props) =>
-    h('div', {},
-      h('p', {}, user.name),          // 服务端状态（闭包，SSR 进 HTML）
-      h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }, liked ? '❤️' : '🤍'))
-}
 ```
+后端:  app.use(cors()); app.use(postgres())
+       app.get('/users', (req, ctx) => ctx.sql`SELECT *`)
+       // ctx 已注入 ctx.sql——injects/depends 声明受检
 
-**三条纪律**（不遵守就是隐性 bug）：
+前端:  ctx.ui.useAsyncData / useObservable / useChat / hold
+       // ctx.ui 渲染原语面——信号 getter 纪律
+```
 
-| 纪律 | 反例 | 正确 |
-|---|---|---|
-| ① 数据 key 必须含维度 | `ctx.data.get('/api/user')`——`/users/1 → /users/2` 导航命中旧缓存 | `ctx.data.get(\`/api/user/${ctx.params.id}\`)` |
-| ② 会变的数据放组件状态 | `const count = data.count`——点击永不更新 | `let count = data.count` + 交互后 `ctx.ui.render()`（初始值 seed 自服务端数据） |
-| ③ 初始状态必须确定性 | `let w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
+### 状态管理
 
-**常见坑**：
-- 工厂按**实例**执行（N 处实例 = N 次工厂调用）——数据必须走 `ctx.data`（自带缓存 + 并发合并，重复执行零成本）；禁止副作用/昂贵操作裸写工厂
-- 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）
-- **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在客户端 `let` + fetch + `render()`
+| 场景 | API | 语义 |
+|------|-----|------|
+| 组件内状态 | `ctx.ui.signal(n)` | getter 读 + set/update 写——变化自动重渲染 |
+| 跨组件共享 | `createStore` + `ctx.ui.useExternal(store)` | 共享状态订阅——getter 最新 |
+| 任意 Observable | `ctx.ui.useObservable(obs$, initial)` | rxjs 风格流 → getter（卸载自动退订） |
+| 服务端状态 | handler 返回 Response | 每请求独立 |
 
 ### 渲染策略：SPA 还是 SSR？
 
@@ -492,17 +453,23 @@ const UserProfile = async (_init, ctx) => {
 | | SPA | SSR + Hydration |
 |---|---|---|
 | 适用 | 应用页（后台、工具、Dashboard） | 内容页（博客、营销，需要 SEO/首屏） |
-| 后端 | HTML 外壳 | `renderToEvents` → `eventsToHtml` + `serializeEvents`（完整 HTML + `__DATA__`） |
-| 客户端 | `createRouter(routes, root, { ctx })` | `deserializeEvents` + `replay`（事件流收养——DOM = fold） |
+| 后端 | HTML 外壳 | `uiSsr(router, url)`（完整 HTML + `__DATA__` 种子——同一棵路由树） |
+| 客户端 | `uiServe(router, { root })` | **结构吸收**（首帧复用服务端 DOM——焦点/输入值保持——失败原子回退重建） |
 
-**怎么选**：默认 SPA；需要 SEO 或首屏即内容时用 SSR。两种模式可混合——SSR 走共享 routes，未匹配走普通 handler。
+**怎么选**：默认 SPA；需要 SEO 或首屏即内容时用 SSR。两种模式可混合。
 
-### Closeable 接口
+### VDOM 输出透明
 
-所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用。
+- **命令流可回放**：渲染 = NDJSON 命令流（纯数据）——DOM = fold(命令流)——
+  可记录/回放/断言（测试基础设施与渲染本体同源）
+- **诊断占位**：条件渲染 false → `<!--wf-hole-->` 注释锚（兄弟不误删）
+- **id 落 DOM**：`data-wf-id` / `data-wf-key`——devtools 即引擎决策日志
+- **非法输入显式化**：重复 key warn（不静默）、事件非函数 warn、受控缺回调
+  warn——**A 级检测兜底**
 
----
+### Closeable 接口
 
+所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用（WS 1001 握手先行 + 重复 close 幂等）。
 
 ---
 
@@ -514,23 +481,23 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 
 | 文档 | 内容 |
 |------|------|
-| [content/guides/server-guide.md](content/guides/server-guide.md) | HTTP 服务层：Router / serve / cors / serveStatic / HttpError / 响应辅助 / parseBody |
-| [content/guides/data-guide.md](content/guides/data-guide.md) | 数据层：postgres（PG v3 自研协议）/ redis（RESP2 自研协议）/ Query Language（AST 双后端）/ Memory 实现（零数据库）/ 测试零外部依赖 |
-| [content/guides/realtime-guide.md](content/guides/realtime-guide.md) | 实时与渲染：scheduler / ui（SSR + JS/CSS 编译）/ graphql / WebSocket |
-| [content/guides/saas-guide.md](content/guides/saas-guide.md) | SaaS 地基：rateLimit / email / userSystem / messager / queue / ai |
+| — | HTTP 服务层：Router / serve / cors / serveStatic / HttpError / 响应辅助 / parseBody |
+| — | 数据层：postgres（PG v3 自研协议）/ redis（RESP2 自研协议）/ Query Language（AST 双后端）/ Memory 实现（零数据库）/ 测试零外部依赖 |
+| — | 实时与渲染：scheduler / ui（SSR + JS/CSS 编译）/ graphql / WebSocket |
+| — | SaaS 地基：rateLimit / email / userSystem / messager / queue / ai |
 | [docs/ai-contract.md](docs/ai-contract.md) | AI Stream Protocol：wf: 事件（SSE 下行 + POST 上行）——流式/工具/审批 |
 
 ### 前端开发者
 
 | 文档 | 内容 |
 |------|------|
-| [content/guides/frontend.md](content/guides/frontend.md) | 前端核心：应用引导（createRouter/createRoot——vdom3 事件流）/ 组件模型 / 异步组件 / 状态管理 / 条件与列表 / ref / 类型（weifuwu/client 已并入 ui-dom） |
-| [content/guides/ui-dom-guide.md](content/guides/ui-dom-guide.md) | **ui-dom**：vdom3 精准事件流引擎（createRouter/createRoot + 事件流）——components 复用 + SSR（事件流形态）（前端唯一运行时） |
-| [content/guides/middleware.md](content/guides/middleware.md) | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
-| [content/guides/components-guide.md](content/guides/components-guide.md) | 组件库（129 个组件 + 使用示例 + 组件列表） |
-| [content/guides/layout-guide.md](content/guides/layout-guide.md) | 布局系统：66 个布局原语 + 157 个工具类 + 182 个主题 Token |
+| — | 前端核心：应用引导（UIRouter/uiServe）/ 组件模型（工厂同步 + hooks 异步边界）/ 状态管理 / 条件与列表 / ref |
+| — | **vdom**：命令流渲染引擎（UIRouter + uiServe/uiSsr + hooks）——components 复用 + SSR 结构吸收（前端唯一运行时） |
+| — | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
+| — | 组件库（129 个组件 + 使用示例 + 组件列表） |
+| — | 布局系统：48 个布局原语 + 90 个工具类 + 183 个主题 Token |
 | [docs/style-guide.md](docs/style-guide.md) | 样式学习路径与命名规范：三档学习（组件 → 原语 → 速查）|
-| [content/guides/styling.md](content/guides/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
+| — | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
 
 ### 通用
 
@@ -538,9 +505,9 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 |------|------|
 | [docs/examples.md](docs/examples.md) | 组合场景示例：登录表单 / 数据列表 + 搜索 / 消息提示 |
 | [docs/environment.md](docs/environment.md) | 环境变量与开发命令 |
-| [content/guides/mobile-guide.md](content/guides/mobile-guide.md) | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
+| — | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
 | [docs/components-map.md](docs/components-map.md) | 组件速查：weifuwu ↔ antd / Element Plus / shadcn 对应 + 迁移路径 |
-| [content/guides/custom-component.md](content/guides/custom-component.md) | 自定义组件开发指南：usePopup / useControlled / 动画 / AI 组件 / 类型纪律 |
+| — | 自定义组件开发指南：usePopup / useControlled / 动画 / AI 组件 / 类型纪律 |
 
 > **贡献**：见 [CONTRIBUTING.md](CONTRIBUTING.md)——四条路径（文档/测试/demo/组件）+ 质量防线。
 >