weifuwu 0.88.0 → 0.89.0

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 零构建）。
 
@@ -28,9 +28,9 @@ 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`，但用途完全不同**
@@ -96,7 +96,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **两阶段组件模型** — 组件 = `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)）。
+**render-only 确定性渲染** — 渲染唯一触发 `ctx.ui.render()`（闭包绑定组件），状态是普通对象（`let` + `render()`）；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。行为可静态推导，无隐式触发（详见组件库）。
 
 **VDOM 输出透明（写 JSX，看 DOM 即真相）** — VDOM 对用户输入零 magic：条件渲染的 false 在 DOM 里是诊断占位注释（`<!--wf-hole: false-->`），数组项 key 与组件实例 id 直接落 DOM（`data-wf-key` / `data-wf-id`）——devtools 看到的 DOM 就是引擎决策的可读输出；非法输入占位 + warn，不崩溃不静默。转化契约唯一清晰：用户写什么，vnode 就是什么，DOM 就长什么样（规则表为内部开发契约）。
 
@@ -104,15 +104,15 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **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 运行时。
+**SPA/SSR/Hydration 统一透明** — 同一棵路由树（`UIRouter` 单一实现源）一个组件三场景自动适配：服务端 `uiSsr(router, url)` 输出完整 HTML（**结构吸收**——客户端首帧复用 DOM 零差异、不重建、无闪跳——失败原子回退重建），浏览器端 `uiServe(router)` 接管后续交互渲染。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
 
 **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。
 
-**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见[SaaS 地基模块](content/guides/saas-guide.md)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
+**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见SaaS 地基模块）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
 
 **机制与策略分离** — 框架管**机制**（token 怎么签、消息怎么送达、agent 循环怎么跑），开发者管**策略**（谁能建群、租户隔离 SQL、技能注册表）。这是「诚实裁剪」的积极面：**框架不越界，应用层不被绑架**——agent-platform 迁移验证了边界：多租户隔离（`WHERE tenant_id`）、技能编排、聊天产品模型留在应用层，框架守住通用能力（auth / ai / messager / UI / 数据管道）。
 
-**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，主题改一个值（`--wf-brand-seed` 换肤 / `data-preset` 预设 / `--wf-btn-radius` 钩子），暗色自动（详见[布局系统](content/guides/layout-guide.md)与[主题配置](content/guides/styling.md)）。
+**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，主题改一个值（`--wf-brand-seed` 换肤 / `data-preset` 预设 / `--wf-btn-radius` 钩子），暗色自动（详见布局系统与主题配置）。
 
 **自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
@@ -126,22 +126,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 +177,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 +189,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 +214,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 +250,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 +265,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 +278,35 @@ 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'
+
+    // 路由树（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'))
 
-    // 路由 + 渲染（vdom3 事件流引擎：createRouter——监听 location → 匹配 → 事件流落地）
-    createRouter(
-      [{ path: '/', render: () => h(Counter, {}) }],
-      document.querySelector('#root')!,
-    )
+    // 浏览器 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/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 +317,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 +325,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 +340,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,23 +360,23 @@ 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.data.get(key)` + async 组件 | — |
+| 用户注册/登录/会话/多租户 | `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`（声明注入即类型化） | — |
 
 ---
 
@@ -439,15 +415,15 @@ const Counter = async (_init, ctx) => {
        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
+前端:  const router = new UIRouter()
+       router.get('/users', (req, ctx) => h(UsersPage, {}))
+       // UIRouter.resolve = 监听导航 → shared Trie 匹配 → params 注入 →
+       // handler 执行——与后端 dispatchRouter 同一内核（shared/router
+       // 五层单源：trie/pipeline/context/chain/ctx-fields）
+       // ctx 注入：params/query/route（enrichCtx）——对齐后端中间件注入
 ```
 
-前端 req = `window.location`，res = `VNode`，`createRouter` = 事件流渲染落地——与后端 `Request → Response`、`serve(router)` 完全同构。
+前端 req = 标准 `Request`，res = 命令流 `Response`，`UIRouter.resolve` = `dispatchRouter` 内核——与后端 `Request → Response`、`serve(router)` **字面同构**（同一 pipeline 骨架——差异只在 verb 表与 serve 边界）。
 
 ### 状态管理
 
@@ -492,8 +468,8 @@ 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。
 
@@ -514,23 +490,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 +514,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/组件）+ 质量防线。
 >

package/dist/client/components/ActionSheet/ActionSheet.d.ts

@@ -2,7 +2,7 @@
  * weifuwu/components — ActionSheet 动作面板（移动端底部滑出）
  *
  * 命令列表 + 取消按钮（iOS 风格）——移动端 App 常用弹层（照片选择/分享/
- * 更多操作）。与 Modal/Drawer 同款会话级模态（usePopup presence 退场状态机 +
+ * 更多操作）。与 Modal/Drawer 同款会话级模态（openPopup presence 退场状态机 +
  * 焦点 trap + 滚动锁）。
  *
  * 纪律：

package/dist/client/components/AiChat/AiChat.d.ts

@@ -1,7 +1,7 @@
 /**
  * AiChat — 标准 AI 对话组件（useChat 的标准展示层）
  *
- * 组件库第一个领域复合组件：接收 ctx.ui.useChat() 返回的 handle，
+ * 组件库第一个领域复合组件：接收 ctx.ui.useChat() 返回的 handle  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
  * 渲染完整对话界面：消息气泡、工具调用卡（ToolCallCard）、HITL 审批卡
  * （ApprovalCard）、思考/工具状态、usage、错误 + 重试、输入条 + 自动滚动。
  *
@@ -14,7 +14,7 @@
  * 文案默认中文（与 ToolCallCard/ApprovalCard 一致），labels 可覆盖。
  *
  * ```tsx
- * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+ * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
  * return () => h(AiChat, { chat: $ })
  * ```
  */
@@ -34,8 +34,7 @@ export interface AiChatLabels {
     empty: string;
 }
 export interface AiChatProps {
-    /** ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） */
-    chat: UseChatHandle;
+    /** ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） */ chat: UseChatHandle;
     /** 消息列表最大高度（默认 '70vh'） */
     maxHeight?: string;
     /** 界面文案覆盖 */

package/dist/client/components/ChatInput/ChatInput.d.ts

@@ -49,6 +49,11 @@ export interface ChatInputProps {
      *  回调必须 mount 层定义（稳定引用——vdom3 props 剪枝）；禁止 out-param 对象（props 不可变契约——
      *  原地写 control.current 触发 vdom3 audit） */
     onControl?: (handle: ChatInputControl) => void;
+    /** 按键拦截（@ 菜单键盘导航——2026-08）：**onKeyIntercept**（非 onKeyDown——
+     *  组件 props 的 on+大写被 vdom 当 DOM 事件拦截（EVENT_RE——不传组件）——
+     *  实测 onKeyDown 静默失效——改名避开）——返回 true = 已处理（菜单开时
+     *  ↑↓/Enter/Esc 消费方接管）——falsy = ChatInput 默认行为 */
+    onKeyInterceptFn?: (e: KeyboardEvent) => boolean | void;
 }
 export interface ChatInputControl {
     /** 直接写内部输入态（不触发 onChange——程序化改写如 @ 补全） */

package/dist/client/components/CitationCard/CitationCard.d.ts

@@ -32,7 +32,7 @@ export interface CitationCardProps {
     maxVisible?: number;
     /** 初始展开（默认折叠） */
     defaultExpanded?: boolean;
-    /** 点击条目回调（提供时不渲染链接，由调用方处理跳转/打开） */
+    /** 点击条目回调（提供时 a 不带 href——role=button + onClick——跳转/打开由调用方处理） */
     onOpen?: (citation: Citation) => void;
 }
 export declare const CitationCard: Component<CitationCardProps, UIContext>;

package/dist/client/components/Command/Command.d.ts

@@ -18,5 +18,5 @@ export interface CommandProps {
     /** 全局快捷键，如 'mod+k'（cmd/ctrl + k）；null 关闭全局监听 */
     globalShortcut?: string | null;
 }
-/** 命令面板（对应 shadcn Command）：usePopup mask 全屏遮罩 + 搜索 + 键盘流（↑↓ Enter Escape）+ Cmd+K 全局快捷键 */
+/** 命令面板（对应 shadcn Command）：openPopup mask 全屏遮罩 + 搜索 + 键盘流（↑↓ Enter Escape）+ Cmd+K 全局快捷键 */
 export declare const Command: Component<CommandProps>;

package/dist/client/components/ContextMenu/ContextMenu.d.ts

@@ -14,6 +14,6 @@ export interface ContextMenuProps {
     className?: string;
 }
 /** 右键菜单（对应 shadcn ContextMenu）：桌面右键 / 触屏长按 在光标处弹出，点外部/Escape 关闭，方向键导航。
- * 实现：ctx.ui.usePopup（longpress 触发 + 外部点击/Escape 关闭 + 自由定位光标处 + portal 视口 clamp）——
+ * 实现：openPopup 内核（longpress 触发 + 外部点击/Escape 关闭 + 自由定位光标处 + portal 视口 clamp）——
  * 不再自建 document 监听；onTrigger 记录光标坐标，position getter 供定位。 */
 export declare const ContextMenu: Component<ContextMenuProps>;

package/dist/client/components/DatePicker/DatePicker.d.ts

@@ -2,7 +2,7 @@
  * weifuwu/components — DatePicker
  *
  * 四合一日期选择器，支持 mode: date | datetime | time | range
- * 统一 usePopup：focus 触发 + mask 遮罩 + 自由定位（left 对齐 + width 跟随 trigger）。
+ * 统一 openPopup 内核：focus 触发 + mask 遮罩 + 自由定位（left 对齐 + width 跟随 trigger）。
  *
  * 状态管理：闭包变量 + ctx.render()
  */

package/dist/client/components/Dropdown/Dropdown.d.ts

@@ -1,7 +1,7 @@
 /**
  * weifuwu/components — Dropdown
  *
- * usePopup 组合器：click 触发 + 受控 open + 外部点击/Escape（document 级，
+ * openPopup 内核：click 触发 + 受控 open + 外部点击/Escape（document 级，
  * 弹层在 portal 中按 Escape 也能关）+ 定位/视口 clamp + portal。
  */
 import type { Component } from '../../vdom/index.ts';

package/dist/client/components/Editor/model/html.d.ts

@@ -8,6 +8,16 @@
  * parse 需要 DOM（DOMParser）——浏览器环境全局可用；测试注入 jsdom document。
  */
 import type { DocState } from './types.ts';
+/**
+ * URL 协议白名单（纯函数——node 直测）。
+ *
+ * http(s)/mailto/相对/锚/query 放行；javascript:/vbscript:/data: 阻断
+ * （data:image/* 仅 src 场景放行——粘贴截图）。
+ * scheme 判定前剥空白/控制字符（`java\tscript:` 类绕过阻断）。
+ *
+ * @returns 安全 URL（原样或剥控制字符）/ null（不安全——调用方删属性或降级空 href）
+ */
+export declare function safeUrl(url: unknown, allowDataImage?: boolean): string | null;
 /** HTML → DocState（doc 可注入——jsdom 测试；浏览器默认全局） */
 export declare function parseHtml(html: string, doc?: Document): DocState;
 /** DocState → HTML（块标签 + 对齐 + marks + embeds；相邻 ul/ol 段合并列表） */

package/dist/client/components/ImageCropper/ImageCropper.d.ts

@@ -2,8 +2,12 @@
  * ImageCropper — 图片裁剪（canvas 原生 API + 拖拽裁剪框，零依赖）
  *
  * 用法：<ImageCropper src={url} aspect={1} onCrop={dataUrl => ...} />
- * 实现：图片绘制到 canvas → 裁剪框（useDrag 拖动/缩放）→ onCrop 输出 dataURL。
- * 纪律：canvas 浏览器 API 经 ctx.browser（SSR 无害——null 检查）。
+ * 实现：图片绘制到 canvas → 裁剪框（pointer 事件拖动/右下柄等比缩放）→
+ * onCrop 输出 dataURL。
+ * 纪律：canvas 浏览器 API 经 ctx.browser（SSR 无害——null 检查）；
+ * 拖拽重绘直调 draw()（canvas 内部状态——非渲染路径，不走 ctx.render——
+ * 避免 vdom 全量 diff——2027-09 死交互实证修复：dragging/move/resize
+ * 曾为死代码——注释声称拖拽但从未接线）。
  */
 import type { Component } from '../../vdom/index.ts';
 export interface ImageCropperProps {

package/dist/client/components/Menu/Menu.d.ts

@@ -3,7 +3,7 @@
  *
  * 导航菜单（侧栏导航）：分组项 + 图标 + 选中态 + 方向键导航 + Enter 激活 + 子菜单 + 折叠。
  * 用于 SaaS 应用侧边导航（替代手写 nav-item 循环）。
- * 裁剪（CS-05，见 design/components-cuts.md）：水平菜单栏（Menubar，独立组件）、子菜单自动互斥。折叠态子菜单浮层已实现（usePopup 基座）。
+ * 裁剪（CS-05，见 design/components-cuts.md）：水平菜单栏（Menubar，独立组件）、子菜单自动互斥。折叠态子菜单浮层已实现（openPopup 内核基座）。
  */
 import type { Component } from '../../vdom/index.ts';
 export interface MenuItem {

package/dist/client/components/NavMenu/NavMenu.d.ts

@@ -6,7 +6,7 @@
  *
  *   <NavMenu items={[{ key, label, children: [...] }]} activeKey onSelect />
  *
- * 弹层纪律（）：子菜单/嵌套子菜单全部经 usePopup 组合器
+ * 弹层纪律（）：子菜单/嵌套子菜单全部经 openPopup 内核
  * （createPortal + fixed + 视口夹紧 + Escape + 外部点击）——不 absolute 定位。
  *
  * 裁剪（CS-05，见 design/components-cuts.md）：不做 hover 延迟微调/子菜单动画曲线定制；