weifuwu 0.74.0 → 0.75.0

package/docs/frontend.md

@@ -1,6 +1,6 @@
 # 前端 API 核心（weifuwu/ui-dom）
 
-> ⚠️ **`weifuwu/client` 已删除**——本页为历史文档。前端运行时唯一入口是 **`weifuwu/ui-dom`**（UIRouter 纯路由 + uiServe 渲染运行时 + SSR/hydration），权威参考见 **[docs/frontend-ui-dom.md](frontend-ui-dom.md)**。本页的 createApp/router/RouteView 用法已失效，对应新 API 为 `uiServe` / `UIRouter`。
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——本页 import 均用 `weifuwu/ui-dom`。前端运行时唯一入口是 **`weifuwu/ui-dom`**（UIRouter 纯路由 + uiServe 渲染运行时 + SSR/hydration），权威参考见 **[docs/frontend-ui-dom.md](frontend-ui-dom.md)**。
 
 > 以下为完整 API 参考，按需查阅。新手建议先阅读 README 的「核心概念」和「快速开始」。
 
@@ -13,40 +13,37 @@
 ```js
 esbuild.build({
   jsx: 'automatic',
-  jsxImportSource: 'weifuwu/client',
+  jsxImportSource: 'weifuwu/ui-dom',
   bundle: true,
 })
 ```
 
 ---
 
-## createApp — 应用引导
+## 应用引导（UIRouter + uiServe）
 
 ```tsx
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 
-const app = createApp()
+const app = new UIRouter()
 
-// 注册中间件
+// 注册中间件（ctx 注入）
 app.use(middleware1)
 app.use(middleware2)
 
-// 挂载到 DOM
-app.mount('#root', RootComponent)
+// 页面路由（handler = 异步组件）
+app.get('/', () => h(Home, {}))
 
-// 获取当前 ctx
-console.log(app.ctx)
-
-// 销毁
-app.destroy()
+// 落地：客户端渲染（hydrate: true 收养 SSR HTML）
+const handle = uiServe(app, { root: '#root' })
 ```
 
-| 方法 | 说明 |
+| API | 说明 |
 |------|------|
-| `createApp()` | 创建应用实例 |
-| `app.use(mw)` | 注册 AppMiddleware |
-| `app.mount(selector, RootComponent)` | 挂载到 DOM |
-| `app.destroy()` | 卸载应用 |
+| `new UIRouter()` | 创建路由实例 |
+| `app.use(mw)` | 注册中间件（AppMiddleware / UIMiddleware） |
+| `app.get(path, handler)` / `use(prefix, sub)` / `notFound(handler)` | 页面路由 / 子路由树 / 404 |
+| `uiServe(app, { root, hydrate })` | 客户端落地（返回 handle，`handle.close()` 卸载） |
 | `app.ctx` | 当前 WfuiContext |
 
 ---
@@ -54,7 +51,7 @@ app.destroy()
 ## 组件模型
 
 ```tsx
-import type { Component, WfuiContext } from 'weifuwu/client'
+import type { Component, WfuiContext } from 'weifuwu/ui-dom'
 
 // 两阶段组件：mount（只一次）→ render（每次 dirty/props 变化）
 const Counter: Component = (_init, ctx) => {
@@ -74,8 +71,8 @@ const Badge: Component = () =>
 ### 类型流（props 泛型 + ctx 注入）
 
 ```tsx
-import type { Component } from 'weifuwu/client'
-import type { ApiInjected, RouteInjected } from 'weifuwu/client'
+import type { Component } from 'weifuwu/ui-dom'
+import type { ApiInjected, RouteInjected } from 'weifuwu/ui-dom'
 
 // ① props 泛型：JSX 使用时自动类型检查（传错类型编译期报错）
 interface DeckCardProps { title: string; pages: number }
@@ -92,13 +89,13 @@ const Home: Component<{}, ApiInjected & RouteInjected> = (_init, ctx) => {
 }
 // 未声明的注入字段编译期报错——注入从"文档约定"变成"类型保证"
 
-createApp()
+const app = new UIRouter<{}>()
   .use(api())                    // 注入 ctx.api
-  .use(router({ routes }))       // 注入 ctx.route / ctx.app
-  .mount('#root', Home)          // mount 时类型累积完整
+  .use(toast())                  // 注入 ctx.toast
+uiServe(app, { root: '#root' })  // 类型累积完整（UIRouter<C & O>）
 ```
 
-> 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/client` 导入）。
+> 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/ui-dom` 导入）。
 
 | 规则 | 说明 |
 |------|------|
@@ -113,8 +110,8 @@ createApp()
 ### JSX 工厂
 
 ```tsx
-// 由 esbuild 自动调用（jsxImportSource: 'weifuwu/client'）
-import { h, jsx, jsxs, jsxDEV, Fragment } from 'weifuwu/client'
+// 由 esbuild 自动调用（jsxImportSource: 'weifuwu/ui-dom'）
+import { h, jsx, jsxs, jsxDEV, Fragment } from 'weifuwu/ui-dom'
 
 // h 支持 variadic children
 h('div', { class: 'x' }, child1, child2)
@@ -131,7 +128,7 @@ h('div', { class: 'x' }, child1, child2)
 | `Portal` / `createPortal(children, portalKey?)` | 渲染到 `document.body#__wf_portal` 独立容器（弹层/对话框，脱离父级 overflow 裁剪） |
 
 ```tsx
-import { createPortal } from 'weifuwu/client'
+import { createPortal } from 'weifuwu/ui-dom'
 
 // 内容渲染到 body 下的独立容器（不在父组件的 DOM 树内）
 const Tooltip = (_init, ctx) =>
@@ -754,7 +751,7 @@ const UserProfile: Component = (initProps, ctx) => {
 }
 ```
 
-### async 组件（原生——无需 asyncComponent 包装）
+### async 组件（原生）
 
 组件 = 函数，async 组件 = async 函数：签名与同步组件一致 `(initProps, ctx) => renderFn`，渲染器按「返回值是 Promise」原生判别。数据经闭包注入，渲染无 loading 分支：
 
@@ -771,9 +768,9 @@ const UserProfile = async (initProps, ctx) => {
 }
 ```
 
-- **客户端**：首次渲染占位 → 工厂 resolve 后整树重渲染补全（SPA）；数据经 `ctx.data` 缓存（hydration 时从 `__DATA__` 同步命中，不重跑请求）
+- **客户端**：首次渲染占位（`Placeholder`）→ 工厂 resolve 后整树重渲染补全；`_asyncDef` 按实例缓存（diff 传递继承，补全不重跑工厂）——N 处实例 = N 次工厂调用，数据走 `ctx.data` 则零成本（缓存 + 并发合并）
 - **服务端**：`ctx.ui.ssr()` 直接 await 工厂 → 数据进 HTML（无占位）
-- 工厂缓存绑定页面上下文：路由导航/登录登出时自动失效，工厂以新 ctx 重新执行
+- **占位显示**：无边界 → null；`<Suspense fallback={...}>` 边界 → 子树内占位处显示 fallback（可选）
 - 会变的数据：初始值 seed 自服务端数据（`$.count = data.count`），交互改 `$`；初始状态必须确定性（禁止 `window.innerWidth` 直接初始化 → SSR/hydration mismatch）
 
 ---
@@ -781,15 +778,15 @@ const UserProfile = async (initProps, ctx) => {
 ## 前端类型
 
 ```tsx
-import type { VNode, VNodeType, Component, WfuiContext, AppMiddleware, RouteDef } from 'weifuwu/client'
-import type { ApiClient, ApiOptions, ApiRequestOptions, ApiError } from 'weifuwu/client'
-import type { AuthClient, AuthOptions } from 'weifuwu/client'
-import type { ErrorBoundaryProps } from 'weifuwu/client'
-import type { I18nOptions, I18nState, LocalePackage } from 'weifuwu/client'
-import type { PopupPositionOptions, PopupPosition } from 'weifuwu/client'
+import type { VNode, VNodeType, Component, WfuiContext, AppMiddleware, RouteDef } from 'weifuwu/ui-dom'
+import type { ApiClient, ApiOptions, ApiRequestOptions, ApiError } from 'weifuwu/ui-dom'
+import type { AuthClient, AuthOptions } from 'weifuwu/ui-dom'
+import type { ErrorBoundaryProps } from 'weifuwu/ui-dom'
+import type { I18nOptions, I18nState, LocalePackage } from 'weifuwu/ui-dom'
+import type { PopupPositionOptions, PopupPosition } from 'weifuwu/ui-dom'
 import type { ConfirmProps, ConfirmOptions } from 'weifuwu/components'
 import type { ToastOptions, ToastPosition } from 'weifuwu/components'
-import type { RouterOptions } from 'weifuwu/client'
+import type { RouterOptions } from 'weifuwu/ui-dom'
 ```
 
 | 类型 | 说明 |

package/docs/realtime.md

@@ -70,13 +70,12 @@ app.get('/page', (req, ctx) => ctx.ui.html`
 ```ts
 app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))   // 相对路径
 
-> ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
-app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/client'))   // 或包名
+app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/ui-dom'))   // 或包名（exports map 解析）
 ```
 
 使用 esbuild 编译：
 - `bundle: true`, `format: 'esm'`, `platform: 'browser'`
-- `jsx: 'automatic'`, `jsxImportSource: 'weifuwu/client'`
+- `jsx: 'automatic'`, `jsxImportSource: 'weifuwu/ui-dom'`
 - 带 mtime 缓存验证（开发时编辑文件后自动失效）
 
 ### ctx.ui.css — CSS 编译
@@ -129,10 +128,11 @@ app.get('/blog/:slug', async (req, ctx) => {
 服务端 HTML + `window.__DATA__`（ctx.data 种子）到达客户端后，`mount(..., { hydrate: true })` **收养现有 DOM**（不重建、不闪跳），只接线事件/ref/$：
 
 ```ts
-import { createApp } from 'weifuwu/client'
+import { UIRouter, uiServe } from 'weifuwu/ui-dom'
 
-createApp()
-  .mount('#root', BlogPage, { hydrate: true })   // 容器已有服务端 HTML
+const app = new UIRouter()
+app.get('/blog/:slug', (loc, ctx) => h(BlogPage, { slug: ctx.params.slug }))
+uiServe(app, { root: '#root', hydrate: true })   // 容器已有服务端 HTML → 收养
 ```
 
 - **游标收养**：元素/文本按位置匹配现有 DOM；tag 不匹配 → 局部替换；文本不一致 → 就地修正；服务端多余节点 → 收尾清理
@@ -140,32 +140,27 @@ createApp()
 - hydration 后 `$`/dirty/事件全量可用（与纯 SPA 无差别）
 - 诚实裁剪：Portal 内容就地收养（不移动到 `#__wf_portal`）；渲染期非确定性（Date/random）会导致 mismatch（dev 警告）
 
-### uiSsr — 路由级 SSR（声明即渲染）
+### 路由级 SSR（UIRouter 两端共享）
 
-共享路由定义，前后端同一份声明——后端匹配即自动 SSR，无需手写 handler/模板/序列化：
+同一份 UIRouter 路由定义，后端匹配即自动 SSR，无需手写 handler/模板/序列化：
 
 ```tsx
-// routes.tsx —— 前后端共用
-import type { RouteDef } from 'weifuwu/client'
-import { BlogPage } from './pages/BlogPage.tsx'
-
-export const routes: RouteDef[] = [
-  { path: '/blog/:slug', component: BlogPage, title: '博客' },
-]
-
-// server.ts —— 一行中间件：GET 匹配 → 注入 ctx.route.params → await 组件工厂 → 完整 HTML + __DATA__ + bundle
-import { uiSsr } from 'weifuwu'
-app.use(uiSsr({ routes, bundle: '/static/blog.js' }))
-
-// blog-hydrate.ts —— 客户端：同一份 routes，router() 注入 ctx.route.params（两端同源）
-createApp()
-  .use(router({ routes }))
-  .mount('#root', routes[0].component, { hydrate: true })
+// router.ts —— 前后端共用
+import { UIRouter, h } from 'weifuwu/ui-dom'
+
+export const app = new UIRouter()
+app.get('/blog/:slug', (loc, ctx) => h(BlogPage, { slug: ctx.params.slug }))
+
+// server.ts —— ssrPage 服务端落地：完整 HTML + __DATA__ + styles
+import { ssrPage } from 'weifuwu/ui-dom'
+const { page } = await ssrPage(app, { url: '/blog/hello', styles: ['/components.css'] })
+
+// client.ts —— uiServe 客户端收养（hydrate: true）
+uiServe(app, { root: '#root', hydrate: true })
 ```
 
-- 组件工厂读 `ctx.route.params`（`/blog/:slug` → `ctx.route.params.slug`）——后端 uiSsr / 前端 router **同源注入**
-- 未匹配 → next()（交给 API/静态/404）；非 GET → next()
-- 可自定义 `title` / `template`
+- 组件工厂读 `ctx.params`（`/blog/:slug` → `ctx.params.slug`）——两端同源注入
+- `ssrPage` 选项：`styles`（stylesheet link）/ `title` / `lang` / `rootId`
 
 ### weifuwu/dev — 服务端直接跑 .tsx
 
@@ -180,7 +175,7 @@ Node 原生 TS 只剥离类型（不支持 JSX）。`weifuwu/dev` 注册 esbuild
 }
 ```
 
-- 前后端同一 JSX 运行时（`jsxImportSource: weifuwu/client`）→ 两端 VNode 一致 → hydration 可靠
+- 前后端同一 JSX 运行时（`jsxImportSource: weifuwu/ui-dom`）→ 两端 VNode 一致 → hydration 可靠
 - 与 `ctx.ui.js` 前端动态编译同一理念：无构建、无产物、改代码即生效
 
 ---

package/docs/saas.md

@@ -12,8 +12,9 @@
 ```ts
 import { rateLimit } from 'weifuwu'
 
-app.use(redis())                                        // 依赖 ctx.redis
-app.use(rateLimit({ windowMs: 60_000, max: 100 }))      // 全局限流（默认固定窗口）
+const r = redis()                                      // 注意：REDIS_URL 缺 env 构造抛错
+app.use(r)                                             // 依赖 ctx.redis
+app.use(rateLimit({ redis: r.redis, windowMs: 60_000, max: 100 }))   // redis 必传（模式 A 显式注入）
 
 app.get('/api/search', async (req, ctx) => {
   await ctx.limit('search', { max: 30, windowMs: 60_000 })  // 手动限流，超限抛 429
@@ -77,7 +78,7 @@ app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
 
 
 > ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
-- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/client` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
+- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/ui-dom` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
 - **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
 - **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
 - **多租户感知**：`issueSession` 的 token payload 携带 `tenantId`（来自 `user.tenant`）——中间件自动注入 `ctx.tenantId`，并将会话字段（userId/tenantId/email/name/role）合并到 `ctx.auth`，多租户应用免写 token 解码/租户中间件（数据隔离 SQL 是应用职责）
@@ -117,7 +118,8 @@ ctx.msg.sendTo('u2', { type: 'mention' })       // 用户维度点对点
 ```ts
 import { queue } from 'weifuwu'
 
-const q = queue()              // 默认 REDIS_URL
+const r = redis(); app.use(r)  // Redis 中间件（注入 ctx.redis）
+const q = queue({ redis: r.redis })   // queue 必传 Redis（池命令走轮询连接）
 app.use(q)                     // 注入 ctx.queue
 
 app.post('/api/generate', async (req, ctx) => {
@@ -184,10 +186,10 @@ app.post('/api/approve', async (req, ctx) => {
 })
 ```
 
-前端解码（`weifuwu/client`）：
+前端解码（`weifuwu/ui-dom`）：
 
 ```ts
-import { aiStream } from 'weifuwu/client'
+import { aiStream } from 'weifuwu/ui-dom'
 
 const handle = aiStream('/api/chat', { messages }, {
   onToken: (text) => { /* 增量 append 到消息 */ },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {

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

@@ -1,41 +0,0 @@
-/**
- * uiSsr — 路由级 SSR 中间件：前端路由表驱动的自动服务端渲染
- *
- * 开发者只声明路由（path + component），GET 匹配即自动 SSR：
- *   匹配 → 注入 params → ctx.ui.ssr 渲染组件（async 工厂 await）→ 页面模板 + __DATA__
- *   未匹配 → next()（交给后续 API/静态/404）
- *
- * 与客户端 router() 共用同一份路由定义（route-match.ts），SPA/SSR 一个声明。
- */
-import type { Middleware } from '../types.ts';
-import type { RouteDef } from '../ui-dom/types.ts';
-export interface UiSsrOptions {
-    /** 前端路由定义（与 router() 共享同一份） */
-    routes: RouteDef[];
-    /** 客户端 bundle 路径（自动注入 <script src>，如 '/static/app.js'） */
-    bundle?: string;
-    /** CSS 路径数组（自动注入 <link rel="stylesheet">，如 ['/static/style.css']） */
-    styles?: string[];
-    /** 自定义 title（默认取路由定义 title 或 'weifuwu'） */
-    title?: (ctx: {
-        params: Record<string, string>;
-        def: RouteDef;
-    }) => string;
-    /** 自定义页面模板：返回完整 HTML（默认内置，含 head/root/__DATA__/styles/bundle） */
-    template?: (parts: {
-        html: string;
-        dataScript: string;
-        title: string;
-        bundle?: string;
-        styles?: string[];
-    }) => string;
-}
-/**
- * 路由级 SSR 中间件：
- *
- * ```ts
- * const app = new Router()
- * app.use(uiSsr({ routes, bundle: '/static/app.js' }))
- * ```
- */
-export declare function uiSsr(opts: UiSsrOptions): Middleware;

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

@@ -1,22 +0,0 @@
-/**
- * 路由匹配纯函数 — 客户端 router 与服务端 uiSsr 共用（无 DOM 依赖）
- *
- * 支持路径参数 :id、通配符 *、嵌套路由（children → chain）。
- * 与后端 Router（Trie）独立——本模块服务于"前端路由表驱动的页面"。
- */
-import type { RouteDef } from './types.ts';
-export interface FlattenedRoute {
-    re: RegExp;
-    keys: string[];
-    def: RouteDef;
-    chain: RouteDef[];
-}
-export declare function joinPaths(a: string, b: string): string;
-export declare function compilePath(path: string): {
-    re: RegExp;
-    keys: string[];
-};
-export declare function flattenRoutes(routes: RouteDef[], basePath?: string, chain?: RouteDef[]): FlattenedRoute[];
-export declare function matchRoute(path: string, routes: FlattenedRoute[]): FlattenedRoute | null;
-/** 从匹配结果提取路径参数 */
-export declare function extractParams(path: string, match: FlattenedRoute): Record<string, string>;