weifuwu 0.74.0 → 0.75.0

package/dist/ui-dom/registry.d.ts

@@ -4,19 +4,13 @@
  * 复制自 client/registry.ts（算法相同），但**无模块级单例**——uiServe 创建实例
  * 注入 ctx.__registry，render/diff/ui 经 getRegistry(ctx) 读取，与 createApp 零交叉。
  */
-import type { VNode, Component, AsyncComponent } from './vnode.ts';
-import type { WfuiContext } from './types.ts';
+import type { VNode } from './vnode.ts';
 type UnmountHook = (id: string) => void;
-interface FactoryEntry {
-    promise: Promise<Component<any, any>>;
-    resolved?: Component<any, any>;
-}
 /** 注册表实例状态 */
 export interface Registry {
     idCounter: number;
     idRegistry: Map<string, VNode>;
     unmountHooks: UnmountHook[];
-    asyncFactoryCache: WeakMap<AsyncComponent<any, any>, FactoryEntry>;
 }
 /** 创建局部注册表（uiServe 每实例一个——组件 id/dirty/卸载钩子与 createApp 隔离） */
 export declare function createRegistry(): Registry;
@@ -26,12 +20,6 @@ export declare function getRegistry(ctx: any): Registry;
 export declare function nextComponentIdFor(reg: Registry): string;
 /** 指定实例注册卸载钩子（组件从 idRegistry 注销时触发） */
 export declare function onComponentUnmountFor(reg: Registry, hook: UnmountHook): () => void;
-/** 启动 async 工厂（幂等，缓存） */
-export declare function startAsyncFactory(reg: Registry, Comp: AsyncComponent, ctx: WfuiContext): FactoryEntry;
-/** async 模式：await 工厂定义 */
-export declare function resolveAsyncFactory(reg: Registry, Comp: AsyncComponent, ctx: WfuiContext): Promise<Component>;
-/** sync 模式：工厂已解析 → 定义；未解析 → undefined */
-export declare function resolveAsyncFactorySync(reg: Registry, Comp: AsyncComponent): Component | undefined;
 /** 包裹 ref 回调调用——用户 ref 逻辑抛错时不中断渲染/卸载管线 */
 export declare function safeCallRef(ref: Function, arg: any, phase: 'mount' | 'cleanup', name?: string): void;
 /** 通知 ref 清理 + Portal 子容器清理（指定实例） */

package/dist/ui-dom/render.d.ts

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client 渲染器 — VNode → DOM + patchValue diff
+ * weifuwu/ui-dom 渲染器 — VNode → DOM + patchValue diff
  *
  * render(vnode, ctx)      → 首次渲染，返回 DOM
  * patchValue(el, old, new, ctx) → 增量更新

package/dist/ui-dom/scroll-lock.d.ts

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client — ScrollLock
+ * weifuwu/ui-dom — ScrollLock
  */
 export declare function lockScroll(): void;
 export declare function unlockScroll(): void;

package/dist/ui-dom/ssr.d.ts

@@ -53,4 +53,5 @@ export declare function ssrPage(router: UIRouter, opts: {
     title?: string;
     lang?: string;
     rootId?: string;
+    styles?: string[];
 }): Promise<SsrPageResult>;

package/dist/ui-dom/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client 类型定义
+ * weifuwu/ui-dom 类型定义
  */
 import type { UseChatHandle, UseChatOptions } from './use-chat.ts';
 import type { VNode } from './vnode.ts';
@@ -543,23 +543,23 @@ export interface WfuiContext {
     };
     /** API 客户端（由 api 中间件注入）；options 为 ApiRequestOptions 形状（headers/signal） */
     api?: {
-        get: <T = unknown>(url: string, options?: {
+        get: <T = any>(url: string, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        post: <T = unknown>(url: string, body?: unknown, options?: {
+        post: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        put: <T = unknown>(url: string, body?: unknown, options?: {
+        put: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        patch: <T = unknown>(url: string, body?: unknown, options?: {
+        patch: <T = any>(url: string, body?: unknown, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;
-        delete: <T = unknown>(url: string, options?: {
+        delete: <T = any>(url: string, options?: {
             headers?: Record<string, string>;
             signal?: AbortSignal;
         }) => Promise<T>;

package/dist/ui-dom/ui.d.ts

@@ -1,5 +1,5 @@
 /**
- * weifuwu/client ctx.ui 工厂 — createApp 注入的 UI 能力
+ * weifuwu/ui-dom ctx.ui 工厂 — createApp 注入的 UI 能力
  *
  * 从 app.ts 拆出（P2 结构拆分）。createUi(deps) 返回完整 ui 对象：
  * render / dirty / $ / useChat / useMedia / useBreakpoint / usePopupPosition / selfId

package/dist/ui-dom/vnode.d.ts

@@ -1,10 +1,10 @@
 /**
- * weifuwu/client VNode — 虚拟 DOM 节点
+ * weifuwu/ui-dom VNode — 虚拟 DOM 节点
  *
  * VNode 是纯 JS 对象，不依赖 DOM。组件返回 VNode。
  *
  * h/jsx 由 esbuild JSX 编译调用：
- *   --jsxImportSource=weifuwu/client
+ *   --jsxImportSource=weifuwu/ui-dom
  */
 import type { WfuiContext } from './types.ts';
 export type VNodeType = string | Component<any, any> | AsyncComponent | typeof Fragment | typeof Portal;
@@ -52,25 +52,9 @@ export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiC
  *
  * 渲染器统一判别「返回值 instanceof Promise」：
  *   客户端：占位 → resolve 后整树重渲染（vnode 级 _asyncDef 按实例缓存）
- *   SSR：直接 await（无占位）
- *
- * asyncComponent() 是兼容包装（工厂签名 (ctx)，WeakMap 全局一次——代码分割场景）。
- */
-export type AsyncComponent<C extends object = {}, P = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<Component<P, C> | null>;
-/**
- * 兼容包装：async 工厂（旧签名 (ctx)，WeakMap 全局一次——代码分割/昂贵一次性资源）。
- * 统一为原生 async 组件签名 (initProps, ctx) => Promise<Component>，渲染器原生处理。
- *
- * ```tsx
- * const UserProfile = asyncComponent(async (ctx) => {
- *   const { default: def } = await import('./view.tsx')
- *   return def
- * })
- * ```
+ *   SSR/hydration：直接 await（无占位）
  */
-export declare function asyncComponent<C extends object = {}, P = {}>(factory: (ctx: WfuiContext & C) => Promise<Component<P, C>>): AsyncComponent<C, P>;
-/** 判定一个组件类型是否为 async 工厂（asyncComponent 包装过） */
-export declare function isAsyncComponent(type: any): type is AsyncComponent;
+export type AsyncComponent<C extends object = {}, P = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<((props: P) => VNode | null) | null>;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;

package/dist/user/token.d.ts

@@ -2,7 +2,7 @@
  * 会话令牌（零依赖，node:crypto）
  *
  * access token：HMAC-SHA256 签名的 JWT 形态（base64url），
- *   与 weifuwu/client 的 auth() 兼容（客户端解码 payload 检查 exp）。
+ *   与 weifuwu/ui-dom 的 auth() 兼容（客户端解码 payload 检查 exp）。
  * refresh token：不透明随机串（256-bit），DB 只存 SHA-256 哈希（可撤销）。
  */
 /** 签发 JWT access token（HS256） */

package/docs/compat-three-library.md

@@ -105,7 +105,7 @@
 ### 框架级
 | antd | weifuwu | 状态 | 备注 |
 |------|---------|:----:|------|
-| App | `createApp` | 🔧 | client 框架内置 |
+| App 引导 | `UIRouter + uiServe` | 🔧 | ui-dom 框架内置（weifuwu/client 已并入 ui-dom） |
 | ConfigProvider | `--wf-*` token + ctx 注入 | 🔧 | client 框架内置 |
 
 ---

package/docs/components-map.md

@@ -193,4 +193,4 @@
 | **StatCard ⬆️** | 增强 | antd Statistic.Countdown | countdown 模式：剩余 HH:MM:SS + 结束回调（1s tick + 清理纪律） |
 
 > 三库 208 项（antd 84 / EP 74 / shadcn 50）→ 100% 覆盖（业务组件全对应；
-> 框架级 App/ConfigProvider/Teleport/Overlay 由 createApp/createPortal/--wf-* token 内置）。
+> 框架级 App/ConfigProvider/Teleport/Overlay 由 UIRouter+uiServe/createPortal/--wf-* token 内置）。

package/docs/custom-components.md

@@ -1,8 +1,8 @@
 # 自定义组件开发指南
 
 
-> ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
-> 用 weifuwu/client 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
+> ⚠️ **weifuwu/client 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> 用 weifuwu/ui-dom 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
 > 前置：[前端概念](frontend.md)（两阶段模型/ctx.ui）+ [组件列表](components.md)。
 
 ---
@@ -10,7 +10,7 @@
 ## 0. 最小骨架
 
 ```tsx
-import { h, type Component } from 'weifuwu/client'
+import { h, type Component } from 'weifuwu/ui-dom'
 
 // Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
 const Badge: Component<{ text: string; color?: string }> = () =>
@@ -76,7 +76,7 @@ const MyPopover: Component<{ content: string }> = (_init, ctx) => {
 全屏对话框（焦点 trap + 滚动锁 + 退场动画）不在 usePopup 范围——用 **`ctx.ui.useDialog`** 组合器（Modal/Drawer 同款：退场状态机 + 滚动锁 + 焦点 trap + animationend 卸载）：
 
 ```tsx
-import { createPortal } from 'weifuwu/client'
+import { createPortal } from 'weifuwu/ui-dom'
 
 const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx) => {
   const dialog = ctx.ui.useDialog({ name: 'MyDialog' })   // mount 创建
@@ -98,7 +98,7 @@ const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx)
 ```
 
 > `dialog.rootRef` 挂到 portal 根（lockScroll + animationend 退场监听）；`panelRef` 挂到面板（trapFocus）。
-> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/client` 导出（特殊场景组装用）。
+> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/ui-dom` 导出（特殊场景组装用）。
 
 ## 4. AI 组件
 
@@ -138,7 +138,6 @@ const UserCard = async (initProps, ctx) => {
 - 渲染器按「返回值是 Promise」判别：客户端未 resolve → 占位（`Placeholder`），resolve 后整树补全；SSR 直接 await（无占位）
 - 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
 - 占位显示：无边界 → null；`<Suspense fallback={...}>` → 占位处显示 fallback（可选）
-- 代码分割/昂贵一次性资源：`asyncComponent(async (ctx) => { const { default: def } = await import('./view'); return def })`（WeakMap 全局一次，兼容保留）
 - **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
 
 ## 6. 类型纪律（编译期防线）

package/docs/data.md

@@ -27,9 +27,11 @@ app.post('/decks', async (req, ctx) => {
   // 读回来自动是对象：rows[0].deck_json === { slides: [...] }（不是字符串）
 })
 
-// ③ 事务（postgres.js 兼容 begin）
+// ③ 事务（中间件实例 pg.transaction——不在 ctx.sql 接口）
+const pg = postgres()
+app.use(pg)
 app.post('/transfer', async (req, ctx) => {
-  await ctx.sql.begin(async sql => {
+  await pg.transaction(async sql => {
     await sql`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
     await sql`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
   })
@@ -105,20 +107,12 @@ const q = queue({ redis })
 | timestamp / date / interval | `string`（无时区语义——转 Date 按本地时区解析即时区魔法，诚实裁剪不转） |
 | NULL | `null` |
 
-### 类型层（查询泛型 + schema 写前校验）
+### 类型层（查询泛型）
 
 ```ts
-// ① 查询结果泛型（编译期类型，无需手写 interface + 断言）
+// 查询结果泛型（编译期类型，无需手写 interface + 断言）
 interface Deck { id: number; title: string; deck_json: { slides: unknown[] } }
-const decks = await ctx.sql.query<Deck>('SELECT id, title, deck_json FROM decks')
-
-// ② schema 注册 → insert 写前校验（脏数据源头拦截）
-ctx.sql.register('decks', {
-  title: { type: 'text', required: true },
-  status: { type: 'enum', values: ['outline', 'ready'] },
-  deck_json: { type: 'jsonb' },
-})
-await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → ValidationError
+const decks = await ctx.sql`SELECT id, title, deck_json FROM decks` as Deck[]
 ```
 
 ### 方法面
@@ -126,17 +120,13 @@ await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → Validati
 | 方法 | 说明 |
 |------|------|
 | `ctx.sql\`...\`` | tagged template → 参数化查询（插值=参数，表名需硬编码） |
-| `ctx.sql.query<T>(sql, params?)` | 参数化查询 + 泛型 |
-| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名） |
-| `ctx.sql.begin(fn)` | 事务（回调收到 tagged template sql） |
-| `ctx.sql.transaction(fn)` | 事务（回调收到 `{ query }`） |
-| `ctx.sql.register(table, schema)` | 注册表结构（写前校验） |
-| `ctx.sql.insert(table, row)` | schema 校验 + 参数化插入 |
-| `ctx.sql.insertMany(table, rows[], { batchSize? })` | **批量插入**：多行 VALUES 单次往返（默认 500/批；所有行键必须一致） |
-| `ctx.sql.update(table, set, where, { returning? })` | **参数化 UPDATE**：SET/WHERE 全部参数化，返回 `affectedRows` |
-| `ctx.sql.delete(table, where)` | **参数化 DELETE**：WHERE 必填（防全表误删），返回 `affectedRows` |
-| `ctx.sql\`...\` 内嵌片段` | 条件 SQL 片段（嵌套过滤，参数自动重编号） |
-| `ctx.sql.close()` | 关闭连接池 |
+| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名；`$1` 占位符） |
+| `ctx.sql.query` | **Query Language**：`sql.query.from('users').where({...}).run()`（AST 双后端） |
+| `ctx.sql.raw\`...\`` | 逃生舱片段（`NOW() - interval '7 days'`——真库透传/内存裁剪） |
+| `pg.transaction(fn)` | 事务（中间件实例；回调收到 callable sql，postgres.js 兼容 begin 语义） |
+| `pg.migrate()` / `markMigrated` / `isMigrated` | 幂等迁移（`_weifuwu_migrations` 表） |
+| `pg.poolStats()` | 连接池摘要（active/idle/waiting/max） |
+| `ctx.sql.close()` / `pg.close()` | 关闭连接池 |
 
 ### 影响行数（affectedRows）
 
@@ -147,14 +137,6 @@ const r = await ctx.sql`UPDATE messages SET read = true WHERE id = ${id}`
 if (r.affectedRows === 0) return new Response('not found', { status: 404 })
 ```
 
-```ts
-// 批量插入：100 行 1 次往返
-await ctx.sql.insertMany('agent_logs', logs, { batchSize: 500 })
-// 语义化更新/删除：WHERE 全参数化 + 返回影响行数
-await ctx.sql.update('users', { role: 'admin' }, { id: userId })
-await ctx.sql.delete('messages', { id: msgId })
-```
-
 ### 条件片段（嵌套过滤）
 
 ```ts
@@ -281,10 +263,11 @@ await ctx.redis.set('user', 1)         // 实际写入 'api:user'
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
+| `url` | `string` | `REDIS_URL` 环境变量（两者都缺 → 构造抛错，禁止静默回退 localhost） | 连接字符串 |
 | `poolSize` | `number` | `5` | 连接池大小 |
 | `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
 | `commandTimeoutMs` | `number` | `0` | 命令超时（阻塞命令 resolve(null)；防挂起。0=禁用） |
+| `onCommand` | `(command, args, durationMs, traceId?) => void` | — | 命令观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
 | `socketTimeoutMs` | `number` | `0` | socket 响应超时（僵尸连接自愈：pending 有命令且超时无数据 → 主动断开重连。0=禁用） |
 
 > **连接健康**：断线自动剔除死连接并重建（池不萎缩）；`CLIENT KILL`/网络抖动后服务自愈，命令不命中死连接。

package/docs/environment.md

@@ -7,7 +7,7 @@
 | 变量 | 用途 | 模块 | 默认 |
 |------|------|------|------|
 | `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres()` | —（必填） |
-| `REDIS_URL` | Redis 连接字符串 | `redis()` | `redis://localhost:6379` |
+| `REDIS_URL` | Redis 连接字符串 | `redis()` | —（必填；缺 env 且未传 `url` 构造抛错，不静默回退 localhost） |
 | `AUTH_SECRET` | userSystem HMAC 签名密钥（≥16 字符） | `userSystem()` | 可传 `options.secret` |
 | `DEEPSEEK_API_KEY` | LLM 对话 provider API key | `ai()` | — |
 | `DEEPSEEK_BASE_URL` | LLM 对话 provider 端点 | `ai()` | `https://api.deepseek.com/v1` |

package/docs/frontend-middleware.md

@@ -1,93 +1,79 @@
 # 前端中间件与工具（weifuwu/ui-dom）
 
-> ⚠️ **`weifuwu/client` 已删除**——中间件（api/auth/ws/i18n）现位于 `weifuwu/ui-dom`，新 API 见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> ⚠️ **`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 官方文档拆分页 · [返回 README](../README.md)
 
-## router + RouteView — 前端路由
+## UIRouter — 前端路由
 
 ```tsx
-import { createApp, router, RouteView } from 'weifuwu/client'
-import type { RouteDef, WfuiContext } from 'weifuwu/client'
-
-const routes: RouteDef[] = [
-  { path: '/', component: Home },
-  { path: '/users', component: UserList },
-  { path: '/users/:id', component: UserDetail },
-]
-
-createApp()
-  .use(router({
-    routes,
-    mode: 'history',  // 或 'hash'
-    notFound: NotFoundPage,
-  }))
-  .mount('#root', () => () => <RouteView />)  // 根组件也要两阶段：外层返回 render 函数
+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）
 ```
 
-### 嵌套布局
+### 嵌套布局（中间件两阶段）
 
 ```tsx
-const routes = [
-  {
-    path: '/dashboard',
-    layout: DashboardLayout,      // 持久布局（包含 RouteView）
-    children: [
-      { path: '/overview', component: Overview },
-      { path: '/settings', component: Settings },
-    ],
-  },
-]
-
-function DashboardLayout(_props: {}, ctx: WfuiContext) {
-  return (props) => (
-    <div style="display:flex">
-      <aside>导航菜单</aside>
-      <main><RouteView /></main>  {/* 渲染子路由 */}
-    </div>
-  )
+const DashboardLayout: UIMiddleware = async (_loc, ctx, children) => {
+  const $ = ctx.ui.$()
+  $.open = true
+  return async (loc, c) => {
+    const child = await children(loc, c)   // 子路由/嵌套路由内容
+    return h('div', { class: 'wf-row' },
+      h('aside', {}, '导航菜单'),
+      h('main', {}, child),
+    )
+  }
 }
+app.use(DashboardLayout)
 ```
 
 ### 编程式导航
 
 ```tsx
-// 在任意组件中
+// 在任意组件/页面中（uiServe 注入）
 ctx.app?.navigate('/users/123?tab=profile')
 ```
 
 | ctx 注入 | 类型 | 说明 |
 |----------|------|------|
+| `ctx.params` / `ctx.query` | `Record<string, string>` | 路由参数 / URL query（顶层注入） |
 | `ctx.route.path` | `string` | 当前路由路径 |
 | `ctx.route.params` | `Record<string, string>` | URL 参数 |
 | `ctx.route.query` | `Record<string, string>` | 查询参数 |
 | `ctx.app.navigate(path)` | `(string) => void` | 编程式导航 |
 
-| RouterOptions | 类型 | 默认值 | 说明 |
-|---------------|------|--------|------|
-| `routes` | `RouteDef[]` | — | 路由定义 |
-| `mode` | `'history' \| 'hash'` | `'history'` | 路由模式 |
-| `notFound` | `Component` | — | 404 页面 |
+| 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` | 路径（支持 `:param`） |
-| `component` | `Component` | 页面组件 |
-| `layout` | `Component` | 布局组件（内含 `<RouteView />`） |
-| `children` | `RouteDef[]` | 子路由 |
-| `auth` | `boolean` | 是否需要认证（配合 auth 中间件） |
-| `title` | `string` | 页面标题（自动设置 `document.title`） |
+| UIHandler | 类型 | 说明 |
+|-----------|------|------|
+| 签名 | `(location, ctx) => Promise<VNode> \| VNode` | 页面 = 异步组件（`ctx.data.get` 三场景；async 组件无需包装） |
+| 返回值 | `VNode \| null` | 数据结构（落地由 uiServe/ssrPage 决定） |
 
 ---
 
 ## api — HTTP 客户端中间件
 
 ```tsx
-import { createApp, api } from 'weifuwu/client'
+import { UIRouter, api, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(api({ baseURL: '/api' }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(api({ baseURL: '/api' }))
+uiServe(app, { root: '#root' })
 
 // 在组件中使用
 async function loadUsers(ctx: WfuiContext) {
@@ -139,11 +125,11 @@ try {
 ## auth — 认证中间件
 
 ```tsx
-import { createApp, auth } from 'weifuwu/client'
+import { UIRouter, auth, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(auth())
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(auth())
+uiServe(app, { root: '#root' })
 
 // 在组件中
 function Profile(_props: {}, ctx: WfuiContext) {
@@ -191,11 +177,11 @@ await ctx.auth?.refresh()  // → boolean
 ## ws — WebSocket 客户端中间件
 
 ```tsx
-import { createApp, ws } from 'weifuwu/client'
+import { UIRouter, ws, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(ws({ url: '/ws' }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(ws({ url: '/ws' }))
+uiServe(app, { root: '#root' })
 
 // 发送消息
 ctx.ws?.send({ type: 'chat', body: 'hello' })
@@ -231,10 +217,10 @@ unsubscribe?.()
 ## i18n — 国际化中间件
 
 ```tsx
-import { createApp, i18n } from 'weifuwu/client'
+import { UIRouter, i18n, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .use(i18n({
+const app = new UIRouter()
+app.use(i18n({
     locale: 'zh-CN',
     messages: {
       'title': '仪表盘',
@@ -268,7 +254,7 @@ ctx.i18n?.setLocale('en-US')
 内置语言包：
 
 ```ts
-import { zhCN, enUS } from 'weifuwu/client'
+import { zhCN, enUS } from 'weifuwu/ui-dom'
 ```
 
 - `zh-CN`：默认中文
@@ -283,7 +269,7 @@ import { zhCN, enUS } from 'weifuwu/client'
 ## ErrorBoundary — 错误边界
 
 ```tsx
-import { ErrorBoundary } from 'weifuwu/client'
+import { ErrorBoundary } from 'weifuwu/ui-dom'
 
 <ErrorBoundary fallback={<p>出错了，请刷新页面</p>}>
   <UserProfile />
@@ -316,12 +302,12 @@ import { ErrorBoundary } from 'weifuwu/client'
 **① 命令式 `ctx.confirm()`（推荐，操作前询问）**
 
 ```tsx
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 import { confirm } from 'weifuwu/components'
 
-createApp()
-  .use(confirm())
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(confirm())
+uiServe(app, { root: '#root' })
 
 // 任意代码中（组件事件、async 逻辑）
 async function handleDelete(ctx: WfuiContext) {
@@ -372,12 +358,12 @@ import { Confirm } from 'weifuwu/components'
 `ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
 
 ```tsx
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 import { toast } from 'weifuwu/components'
 
-createApp()
-  .use(toast({ position: 'top-right', duration: 3000, max: 3 }))
-  .mount('#root', App)
+const app = new UIRouter()
+app.use(toast({ position: 'top-right', duration: 3000, max: 3 }))
+uiServe(app, { root: '#root' })
 
 // 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
 ctx.toast?.('保存成功', 'success')
@@ -400,8 +386,8 @@ ctx.toast?.('普通消息')          // 默认 type = 'info'
 ## ScrollLock / FocusTrap
 
 ```tsx
-import { lockScroll, unlockScroll } from 'weifuwu/client'
-import { trapFocus } from 'weifuwu/client'
+import { lockScroll, unlockScroll } from 'weifuwu/ui-dom'
+import { trapFocus } from 'weifuwu/ui-dom'
 
 // 锁定/解锁滚动（支持嵌套计数）
 lockScroll()
@@ -423,7 +409,7 @@ cleanup()  // 恢复之前的焦点
 ## extendCtx — 上下文扩展
 
 ```tsx
-import { extendCtx } from 'weifuwu/client'
+import { extendCtx } from 'weifuwu/ui-dom'
 
 // 在 AppMiddleware 中创建新 ctx，原 ctx getter 通过原型链继承
 function myMw(ctx: WfuiContext): WfuiContext {

package/docs/frontend-ui-dom.md

@@ -3,7 +3,7 @@
 > **weifuwu 前端唯一运行时**（`weifuwu/ui-dom`，随 npm 包发布）：
 > **UIRouter（纯路由 + ctx 注入链）+ uiServe（渲染运行时）+ ssrPage/hydration**，
 > 复用 `weifuwu/components`（VNode 契约唯一来源，组件零修改）。
-> 已取代 `weifuwu/client`（createApp/router 已删除）。
+> 已取代 `weifuwu/client`——前端运行时唯一入口（createApp/router 旧 API 已删除）。
 >
 > 概念对齐：**req = window.location**，**res = VNode**（数据结构），
 > **uiServe = VDOM**（落地机制），**params/query 在 ctx**（对齐后端 `ctx.params`）。
@@ -161,5 +161,7 @@ uiServe(app, { root: '#root', hydrate: true })
 ## demo
 
 `apps/ui-router-demo`：UIRouter + uiServe + components（Button/Input/Tag/Dropdown）
-+ toast 注入 + 嵌套路由 + SSR/hydrate 端到端。
++ toast 注入 + 嵌套路由 + SSR/hydrate 端到端（原生 async 组件页 `/async` 验证
+占位补全 + `__DATA__` 三场景）。server 用 weifuwu serve + `ui()` 中间件
+（`ctx.ui.js` 编译前端 / `ctx.ui.css` 组件样式 / `/*` → ssrPage）。
 启动：`node apps/ui-router-demo/server.ts` → http://localhost:3100