npm - weifuwu - Versions diffs - 0.36.0 → 0.36.1 - Mend

weifuwu 0.36.0 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +352 -600
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,45 +1,33 @@
 # weifuwu
-**全栈框架 — 后端 `(req, ctx) => Response` + 前端 `(props, ctx) => JSX`**
+**全栈框架 — 后端 `(req, ctx) => Response` + 前端 `(props, ctx) => VNode` + 纯 CSS 布局系统**
 ```bash
 npm install weifuwu
 ```
-一个包，无上游依赖。后端提供 HTTP 路由、数据库、中间件；前端提供 VDOM + Proxy 驱动的前端框架。
+一个包，零上游依赖。后端提供 HTTP 路由、数据库、中间件；前端提供 VDOM + Proxy 驱动的前端框架；布局提供纯 CSS 原语 + 主题 Token。
 ---
 ## 模块总览
-| 模块 | 导出 | 用途 | 依赖 |
-|------|------|------|------|
-| **Router** | `Router` | HTTP 路由 + 中间件链 + WebSocket + GraphQL | — |
-| **serve** | `serve` | HTTP 服务器 | `Router` |
-| **cors** | `cors` | CORS 跨域中间件 | `Router` |
-| **serveStatic** | `serveStatic` | 静态文件服务 | `Router` |
-| **postgres** | `postgres` | PostgreSQL 客户端 → `ctx.sql` | `Router` |
-| **redis** | `redis` | Redis 客户端 → `ctx.redis` | `Router` |
-| **ui** | `ui` | SSR 渲染 + 动态 JS 编译 → `ctx.ui.html/css/js` | `Router` |
-| **graphql** | `router.graphql()` | GraphQL 端点 | `Router` |
-| **client** | — | 前端 VDOM + Proxy 框架 | — |
-| **layout** | — | 纯 CSS 布局原语 + 主题 Token 系统 | — |
-**前端 `weifuwu/client` 模块总览：**
-| 类别 | 导出 | 用途 |
-|------|------|------|
-| **渲染引擎** | `VNode`, `Component` | 虚拟 DOM 节点与组件类型 | — |
-| **JSX 运行时** | `jsx`/`jsxs`/`jsxDEV`, `Fragment` | TSX 编译目标 | — |
-| **应用** | `createApp` | 中间件链 + 挂载 | — |
-| **路由** | `router`, `RouteView` | 嵌套布局路由 | — |
-| **中间件** | `ws`, `api`, `auth` | WebSocket / HTTP 客户端 / 认证状态 | — |
-| **工具** | `extendCtx` | ctx 扩展 | — |
-| **类型** | `WfuiContext`, `AppMiddleware`, `RouteDef`, `VNodeType`, `Component`, `ApiClient`, `AuthClient` | — | — |
+| 模块 | 导入路径 | 用途 | 依赖 |
+|------|---------|------|------|
+| **Router** | `weifuwu` | HTTP 路由 + 中间件链 + WebSocket + GraphQL | — |
+| **serve** | `weifuwu` | HTTP 服务器 | `Router` |
+| **cors** | `weifuwu` | CORS 跨域中间件 | `Router` |
+| **serveStatic** | `weifuwu` | 静态文件服务 | `Router` |
+| **postgres** | `weifuwu` | PostgreSQL 客户端 → `ctx.sql` | `Router` |
+| **redis** | `weifuwu` | Redis 客户端 → `ctx.redis` | `Router` |
+| **ui** | `weifuwu` | SSR 渲染 + 动态 JS/CSS 编译 → `ctx.ui` | `Router` |
+| **graphql** | `weifuwu` | GraphQL 端点 | `Router` |
+| **client** | `weifuwu/client` | 前端 VDOM + Proxy 框架 | — |
+| **layout** | `weifuwu/layout` | 纯 CSS 布局原语 + 主题 Token | — |
 ---
-## 核心理念：`ctx`
+## 核心理念
 前后端共享同一模式：**中间件向 `ctx` 注入字段，handler/组件从 `ctx` 读取。**
@@ -55,80 +43,44 @@ npm install weifuwu
 ---
-## 快速开始 — 全栈应用
+## 快速开始 —— 全栈应用
 ```ts
-// server.ts — 同一个 npm 包
-import { serve, Router, cors, ui } from 'weifuwu'
+import { serve, Router, ui } from 'weifuwu'
 const app = new Router()
-app.use(cors())
 app.use(ui())
-// REST API
-app.get('/api/posts', async (req, ctx) => {
-  const posts = [{ id: 1, title: 'Hello' }]
-  return Response.json(posts)
-})
+// 前端 TSX → JS bundle（动态编译，零构建步骤）
+app.get('/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
-// WebSocket
-app.ws('/ws', {
-  open(ws) { ws.send(JSON.stringify({ type: 'system', body: 'connected' })) },
-  message(ws, ctx, data) {
-    const msg = JSON.parse(data.toString())
-    ws.send(JSON.stringify({ type: 'echo', body: msg.body }))
-  },
-})
+// CSS（PostCSS + Tailwind 编译）
+app.get('/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
-// SPA 入口 — 动态编译前端（零构建步骤）
+// SPA 入口
 app.get('/', async (req, ctx) => ctx.ui.html`
   <!DOCTYPE html>
-  <html><body><div id="root"></div>
-  <script src="/static/app.js"></script></body></html>
+  <html>
+  <head><link rel="stylesheet" href="/style.css"></head>
+  <body><div id="root"></div><script src="/app.js"></script></body>
+  </html>
 `)
-app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
 serve(app, { port: 3000 })
 ```
 ```tsx
-// src/main.tsx — 前端
-import { createApp, router, RouteView, ws, api, auth } from 'weifuwu/client'
+// src/main.tsx —— 前端
+import { createApp, router, RouteView } from 'weifuwu/client'
 import type { WfuiContext, RouteDef } from 'weifuwu/client'
-// 组件 = (props, ctx) => VNode
 function Home(_props: {}, ctx: WfuiContext) {
-  const $ = ctx.ui.$
-  if (!ctx.ui.ready) { $.items = [{ id: 1, text: 'hello' }] }
-  return <div>{$.items.map((i: any) => <div key={i.id}>{i.text}</div>)}</div>
+  return <h1>Hello weifuwu</h1>
 }
-const app = createApp()
-app.use(api({ baseURL: '' }))
-app.use(auth())
-app.use(ws())
-app.use(router({
-  routes: [
-    { path: '/', component: Home },
-    {
-      path: '/dashboard',
-      layout: DashboardLayout,
-      ],
-    },
-  ],
-  mode: 'hash',
-  scrollRestoration: true,
-}))
-app.mount('#root', AppShell)
-function AppShell(_props: {}, ctx: WfuiContext) {
-  return (
-    <div>
-      <nav>{/* ... */}</nav>
-      <main><RouteView /></main>
-    </div>
-  )
-}
+createApp()
+  .use(router({ routes: [{ path: '/', component: Home }], mode: 'history' }))
+  .mount('#root', () => <Home />)
 ```
 ---
@@ -138,110 +90,134 @@ function AppShell(_props: {}, ctx: WfuiContext) {
 ### Router
 ```ts
+import { Router } from 'weifuwu'
 const app = new Router()
-// HTTP 方法
-app.get(path, ...handlers)
-app.post / put / delete / patch / head / options(path, ...handlers)
-app.all(path, ...handlers)
+// 中间件
+app.use(cors())
-// WebSocket / GraphQL
-app.ws(path, handler)
-app.graphql('/graphql', handler)
+// 路由
+app.get('/api/users', async (req: Request, ctx: Context) => {
+  return Response.json(users)
+})
-// 中间件
-app.use(middleware)
-app.mount(prefix, subRouter)
-app.onError(handler)
+app.post('/api/users', async (req: Request, ctx: Context) => {
+  const body = await req.json()
+  return Response.json({ id: 1, ...body }, { status: 201 })
+})
-// 调试
-app.routes()  // 列出所有路由
+// URL 参数
+app.get('/users/:id', async (req: Request, ctx: Context) => {
+  const id = ctx.params.id
+  return Response.json({ id, name: 'User ' + id })
+})
 ```
-| 方法 | 参数 | 说明 |
+| 方法 | 路由 | 说明 |
 |------|------|------|
-| `get/post/put/delete/patch/head/options` | `(path, ...handlers)` | 注册 HTTP 路由 |
-| `all` | `(path, ...handlers)` | 匹配所有方法 |
-| `ws` | `(path, handler)` | WebSocket 端点 |
-| `graphql` | `('/path', handler)` | GraphQL 端点 |
-| `use` | `(middleware)` | 全局中间件 |
-| `mount` | `(prefix, subRouter)` | 子路由挂载 |
-| `onError` | `(handler)` | 全局错误处理 |
-| `routes` | `()` | 返回路由列表数组 |
-### serve — HTTP 服务器
+| `app.get(path, handler)` | 任意 | GET 请求 |
+| `app.post(path, handler)` | 任意 | POST 请求 |
+| `app.put(path, handler)` | 任意 | PUT 请求 |
+| `app.patch(path, handler)` | 任意 | PATCH 请求 |
+| `app.delete(path, handler)` | 任意 | DELETE 请求 |
+| `app.use(middleware)` | 全路由 | 中间件 |
+| `app.ws(path, handler)` | 任意 | WebSocket |
+| `app.graphql(options)` | 自动 | GraphQL 端点 |
+| `app.onError(handler)` | 全局 | 错误处理 |
+### serve —— HTTP 服务器
 ```ts
-const srv = serve(app, { port: 3000 })
-await srv.stop()   // 程序化停止
-// Ctrl+C / SIGTERM — 自动关闭所有连接后退出
+import { serve, Router } from 'weifuwu'
+const router = new Router()
+serve(router, { port: 3000 })
 ```
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `port` | `0` | 监听端口 |
-| `hostname` | `'0.0.0.0'` | 监听地址 |
-| `maxBodySize` | `10MB` | 请求体上限 |
-| `timeout` | `30000` | Socket 超时 (ms) |
-| `shutdown` | `true` | 是否注册 SIGTERM/SIGINT 处理 |
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `port` | `number` | `0`（随机端口） | 监听端口 |
+| `hostname` | `string` | `'0.0.0.0'` | 监听地址 |
+| `timeout` | `number` | `30000` | 连接超时（ms）|
+| `maxBodySize` | `number` | `10MB` | 请求体上限 |
+| `shutdown` | `boolean` | `true` | 自动注册 SIGTERM/SIGINT |
-### cors — CORS 中间件
+### cors —— CORS 中间件
 ```ts
+app.use(cors())
 app.use(cors({
-  origin: ['https://example.com'],
-  credentials: true,
+  origin: ['https://app.example.com'],
+  methods: ['GET', 'POST'],
 }))
 ```
-### serveStatic — 静态文件
+| 参数 | 默认值 |
+|------|--------|
+| `origin` | `*` |
+| `methods` | `GET, POST, PUT, PATCH, DELETE, OPTIONS` |
+| `allowedHeaders` | `Content-Type, Authorization` |
+### serveStatic —— 静态文件
 ```ts
-app.use(serveStatic('./public', { prefix: '/assets' }))
-```
+import { serveStatic } from 'weifuwu'
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `prefix` | `''` | URL 前缀 |
-| `index` | `'index.html'` | 默认首页 |
+// 单一路径
+app.get('/static/*', serveStatic('./public'))
+// 多目录
+app.get('/uploads/*', serveStatic('./uploads'))
+```
-### postgres — PostgreSQL
+### postgres —— PostgreSQL
 ```ts
+import { postgres } from 'weifuwu'
 app.use(postgres())
-// → ctx.sql`SELECT * FROM users`
-app.use(postgres({ url: 'postgres://user:pass@host:5432/db' }))
-// 默认读取 DATABASE_URL 环境变量
+// 然后在 handler 中使用 ctx.sql
+app.get('/users', async (req, ctx) => {
+  const users = await ctx.sql`SELECT * FROM users`
+  return Response.json(users)
+})
 ```
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `url` | `DATABASE_URL` | 连接字符串 |
-| `migrations` | `'./migrations'` | 迁移文件目录 |
-依赖：需要 `postgres` npm 包。实现 `close(): Promise<void>`。
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `url` | `string` | `DATABASE_URL` 环境变量 | 连接字符串 |
+| `max` | `number` | `10` | 连接池大小 |
-### redis — Redis
+### redis —— Redis
 ```ts
+import { redis } from 'weifuwu'
 app.use(redis())
-// → ctx.redis.get('key')
-// → ctx.redis.set('key', 'value')
-// 默认读取 REDIS_URL 环境变量
+// 使用 ctx.redis
+app.get('/cache', async (req, ctx) => {
+  const cached = await ctx.redis.get('key')
+  return Response.json({ cached })
+})
 ```
-依赖：需要 `ioredis` npm 包。实现 `close(): Promise<void>`。
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
-### ui — SSR + SPA 渲染
+### ui —— SSR + SPA 渲染
 ```ts
 app.use(ui())
 // SSR 页面
-app.get('/blog/:slug', async (req, ctx) => ctx.ui.html`
-  <!DOCTYPE html>
-  <html><body><h1>${post.title}</h1></body></html>
+app.get('/page', async (req, ctx) => ctx.ui.html`
+  <h1>${title}</h1>
+  <p>${body}</p>
 `)
 // 动态 JS 编译（esbuild，零构建步骤）
@@ -255,17 +231,17 @@ app.get('/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
 |------|------|
 | `ctx.ui.html\`...\`` | 渲染 HTML 模板（转义变量防 XSS） |
 | `ctx.ui.html.unsafe(str)` | 插入原始 HTML |
-| `ctx.ui.js(entryPath)` | 动态编译 TSX → JS bundle |
-| `ctx.ui.css(entryPath)` | 编译 CSS (PostCSS + Tailwind) |
+| `ctx.ui.js(entryPath)` | 编译 TSX → JS bundle |
+| `ctx.ui.css(entryPath)` | 编译 CSS（PostCSS + Tailwind） |
-### graphql — GraphQL
+### graphql —— GraphQL
 ```ts
-app.graphql(async (req, ctx) => ({
+app.graphql({
   schema: `type Query { hello: String }`,
   resolvers: { Query: { hello: () => 'world' } },
   graphiql: true,
-}))
+})
 ```
 ### WebSocket
@@ -295,7 +271,6 @@ app.onError((err, req, ctx) => {
 |---------|------|
 | `HttpError` | HTTP 错误 `new HttpError(msg, status)` |
 | `DEFAULT_MAX_BODY` | 默认请求体上限 10MB |
-| `MIGRATIONS_TABLE` | Postgres 迁移表名 |
 ### 后端类型
@@ -305,9 +280,10 @@ app.onError((err, req, ctx) => {
 ## 前端 (`weifuwu/client`)
-**2750 行源码，28 个运行时导出 + 19 个类型，零外部依赖。**
+零外部依赖。组件模型：**纯函数 `(props, ctx) => VNode`**。
 构建配置（esbuild）：
 ```js
 esbuild.build({
   jsx: 'automatic',
@@ -316,428 +292,239 @@ esbuild.build({
 })
 ```
-### 状态管理 — 深度 Proxy
-`ctx.ui.$` 是**深度 Proxy**：任何属性/数组/对象层面的写入自动触发渲染，无需手动调用。
+### 组件
 ```tsx
-const $ = ctx.ui.$
-// 顶层属性赋值
-$.count = 0                                // → 自动渲染
-$.user = { name: 'alice' }                 // → 新值自动深度包装
-// 数组突变
-$.items.push(newItem)                      // → 自动渲染
-$.items.pop()                              // → 自动渲染
-$.items.splice(i, 1)                       // → 自动渲染
-// 对象属性突变（数组内部也支持）
-$.items[0].done = true                     // → 自动渲染
-$.msgs[idx].content += event.text          // → 自动渲染
+// 组件 = 纯函数 (props, ctx) => VNode
+function Greeting(props: { name: string }, _ctx: WfuiContext) {
+  return <div>Hello, {props.name}!</div>
+}
-// 不可变更新（同样支持）
-$.items = [...$.items, newItem]
+// 使用
+<Greeting name="world" />
 ```
-| API | 说明 |
-|------|------|
-| `ctx.ui.$` | 深度 Proxy 对象，所有写入自动触发渲染 |
-| `ctx.ui.dirty()` | ⚠ 极少需要 — 仅当绕过 Proxy 直接操作底层对象时 |
+### 状态 —— 深度 Proxy
-### JSX 运行时
+`ctx.ui.$` 是**深度 Proxy**：任何属性/数组/对象写入自动触发渲染，无需手动调用。
 ```tsx
-// 自动由 esbuild 调用（无需手动导入）
-<div class="foo">hello</div>
-<Fragment>...</Fragment>
+function Counter(_props: {}, ctx: WfuiContext) {
+  const $ = ctx.ui.$
+  if (!ctx.ui.ready) $.count = 0
+  return (
+    <div>
+      <span>{$.count}</span>
+      <button onClick={() => $.count++}>+</button>
+    </div>
+  )
+}
 ```
-| 导出 | 说明 |
+| API | 说明 |
 |------|------|
-| `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
-| `Fragment` | `<></>` 片段组件 |
-**Signal 属性自动绑定：** `<input value={signalVal} />` — 信号变化时只更新对应 DOM 属性。
+| `ctx.ui.$` | 深度 Proxy，所有写入自动触发渲染 |
+| `$.x = val` | 顶层属性赋值 → 自动渲染 |
+| `$.items.push(val)` | 数组突变 → 自动渲染 |
+| `$.items[0].x = val` | 对象属性突变 → 自动渲染 |
+| `ctx.ui.dirty()` | 仅当绕过 Proxy 直接操作底层对象时使用 |
 ### 条件与列表
-使用原生 JS 表达式，不需要框架 API：
+使用原生 JS 控制流：
 ```tsx
 // 条件
-{$.loading && <Loading />}
-{$.error ? <Error msg={$.error} /> : <Content />}
+{cond ? <A /> : <B />}
+{cond && <A />}
 // 列表
-{$.items.map(item => (
-  <div key={item.id}>{item.name}</div>
-))}
+{items.map(item => <div key={item.id}>{item.name}</div>)}
 ```
-| 模式 | 说明 |
-|------|------|
-| `{cond && <A/>}` | 条件渲染（cond 为 true 时渲染 A） |
-| `{cond ? <A/> : <B/>}` | 二选一 |
-| `{arr.map(x => <div key={x.id}/>)}` | 列表渲染，必须加 `key` |
-### 生命周期
-使用 `ref` 回调替代生命周期钩子：
+### 生命周期 —— ref 回调
 ```tsx
-<div ref={el => {
-  if (el) {
-    // 挂载：el 是 DOM 元素
-    fetchData()
-    el.addEventListener('scroll', handler)
+function MyComponent(_props: {}, ctx: WfuiContext) {
+  function onRef(el: HTMLElement | null) {
+    if (el) {
+      // mount: 加事件监听等
+      el.addEventListener('scroll', handler)
+    } else {
+      // unmount: 清理
+    }
   }
-  if (!el) {
-    // 卸载：el 为 null
-    cleanup()
-  }
-}} />
-```
-`ref` 在挂载时传入 DOM 元素，卸载时传入 `null`。一个回调覆盖 mount/unmount 两个场景。
+  return <div ref={onRef} />
+}
+```
-### 应用
+### 应用 —— createApp
 ```tsx
+import { createApp } from 'weifuwu/client'
 const app = createApp()
 app.use(middleware1)
 app.use(middleware2)
-await app.mount('#root', AppShell)
+app.mount('#root', RootComponent)
+app.destroy()
 ```
-| 方法 | 说明 |
-|------|------|
-| `use(mw)` | 注册中间件，返回 `this` 支持链式 |
-| `mount(selector, RootComponent)` | 挂载到 DOM |
-| `hydrate(selector, Component, props?)` | 在 SSR 内容上附加组件 |
-| `ctx` | 当前上下文 |
-### 路由
+### 路由 —— router + RouteView
 ```tsx
-// 路由定义
-const routes: RouteDef[] = [
-  { path: '/', component: HomePage },
+import { router, RouteView } from 'weifuwu/client'
+createApp()
+  .use(router({
+    routes: [
+      { path: '/', component: Home },
+      { path: '/users', component: UserList },
+      { path: '/users/:id', component: UserDetail },
+    ],
+    notFound: NotFound,
+    mode: 'history',  // 或 'hash'
+  }))
+  .mount('#root', AppShell)
+// 嵌套布局
+const routes = [
   {
     path: '/dashboard',
-    layout: DashboardLayout,    // 嵌套布局
+    layout: DashboardLayout,  // 持久布局
     children: [
-      { path: '/overview', component: Overview },  // 子路由
+      { path: '/overview', component: Overview },
       { path: '/settings', component: Settings },
     ],
   },
-  { path: '/user/:id', component: UserPage, title: '用户' },
 ]
-// 注册路由中间件
-app.use(router({
-  routes,
-  notFound: NotFound,
-  mode: 'hash',                // 'hash' | 'history'
-  scrollRestoration: true,
-}))
-// 路由出口 — 根层级和嵌套层级用同一个组件
-function AppShell() {
-  return <main><RouteView /></main>   // 根出口
-}
-function DashboardLayout() {
+// 在 layout 中放置 RouteView 渲染子路由
+function DashboardLayout(_props: {}, ctx: WfuiContext) {
   return (
-    <div class="flex">
-      <Sidebar />
-      <main><RouteView /></main>      // 嵌套出口（同一组件）
+    <div class="wf-split">
+      <aside>sidebar</aside>
+      <main><RouteView /></main>
     </div>
   )
 }
 ```
-| RouteDef 字段 | 类型 | 说明 |
-|---------------|------|------|
-| `path` | `string` | 路由路径，支持 `/:param` |
-| `component` | `Component` | 路由组件 |
-| `layout` | `Component` | 嵌套布局（渲染 `<RouteView />` 显示子路由）|
-| `children` | `RouteDef[]` | 子路由（与 layout 配合使用）|
-| `auth` | `boolean` | 是否需要登录 |
-| `title` | `string` | 页面标题（自动设置 `document.title`）|
-| `loader` | `(ctx) => Promise<data>` | 数据预取 → `ctx.route.data` |
-| `transition` | `string` | 页面切换过渡动画 CSS class 前缀 |
-| RouterOptions | 默认 | 说明 |
-|---------------|------|------|
-| `mode` | `'hash'` | 路由模式 |
-| `notFound` | — | 404 组件 |
-| `scrollRestoration` | `true` | 历史模式时恢复滚动位置 |
-| `transition` | — | 全局过渡动画 |
-**`ctx.route` 注入：**
-```tsx
-ctx.route.path       // '/user/42'
-ctx.route.params     // { id: '42' }
-ctx.route.query      // { tab: 'profile' }
-ctx.route.component  // 当前路由组件
-ctx.route.data       // loader 返回的数据
-ctx.route.loading    // loader 是否加载中
-ctx.app.navigate('/path')
-```
-### 代码分割
-```tsx
-const AdminPage = lazy(() => import('./pages/AdminPage'), {
-  fallback: () => <div>加载中...</div>,
-})
-const routes = [
-  { path: '/admin', component: AdminPage },
-]
-```
-需 esbuild `splitting: true` + `outdir`。
+| API | 说明 |
+|------|------|
+| `ctx.route.path` | 当前路由路径 |
+| `ctx.route.params` | URL 参数（如 `:id`）|
+| `ctx.route.query` | 查询参数对象 |
+| `ctx.app.navigate(path)` | 编程式导航 |
 ### 中间件
-#### ws — WebSocket 客户端
+**ws —— WebSocket 客户端**
 ```tsx
-app.use(ws({ url: '/ws' }))
+app.use(ws())
-// 组件中：
-const unsub = ctx.ws?.onMessage((data) => { ... })
-// 清理在 ref 中处理
+// 发送消息
 ctx.ws?.send({ type: 'chat', body: 'hello' })
-{ctx.ws?.isConnected && <span>🟢 已连接</span>}
-```
-| `ctx.ws` | 类型 | 说明 |
-|----------|------|------|
-| `send` | `(data: unknown) => void` | 发送消息 |
-| `onMessage` | `(handler) => dispose()` | 注册消息监听 |
-| `isConnected` | `Signal<boolean>` | 连接状态信号 |
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `url` | `'/ws'` | WebSocket 地址 |
-| `reconnectInterval` | `3000` | 重连间隔 (ms) |
-| `maxReconnect` | `10` | 最大重连次数 |
+// 接收消息
+ctx.ws?.onMessage((msg) => { console.log(msg) })
+```
-#### api — HTTP 客户端
+**api —— HTTP 客户端**
 ```tsx
 app.use(api({ baseURL: '/api' }))
-// 组件中：
-await ctx.api.get<User[]>('/users')
-await ctx.api.post<User>('/users', body)
-await ctx.api.put<User>('/users/1', body)
-await ctx.api.patch<User>('/users/1', body)
-await ctx.api.delete('/users/1')
+// 自动携带 Authorization header
+const user = await ctx.api?.get('/users/1')
+const res = await ctx.api?.post('/users', { name: 'Alice' })
 ```
-| `ctx.api` | 签名 | 说明 |
-|-----------|------|------|
-| `get` | `<T>(url, opts?) => Promise<T>` | GET 请求 |
-| `post` | `<T>(url, body?, opts?) => Promise<T>` | POST 请求 |
-| `put` | `<T>(url, body?, opts?) => Promise<T>` | PUT 请求 |
-| `patch` | `<T>(url, body?, opts?) => Promise<T>` | PATCH 请求 |
-| `delete` | `<T>(url, opts?) => Promise<T>` | DELETE 请求 |
-| 选项 | 说明 |
+| 方法 | 说明 |
 |------|------|
-| `baseURL` | API 基础路径 |
-| `headers` | 默认请求头 |
-| `onRequest` | 请求拦截器 `({url, init}) => {url, init}` |
-| `onResponse` | 响应拦截器 `(res) => Promise<T>` |
-错误类型：`ApiError` — 包含 `status` 和 `body`。
+| `ctx.api.get(url, opts?)` | GET |
+| `ctx.api.post(url, body?, opts?)` | POST |
+| `ctx.api.put(url, body?, opts?)` | PUT |
+| `ctx.api.patch(url, body?, opts?)` | PATCH |
+| `ctx.api.delete(url, opts?)` | DELETE |
-#### auth — 认证状态管理
+**auth —— 认证状态管理**
 ```tsx
 app.use(auth())
-// 组件中：
-{ctx.auth?.isLoggedIn ? (
-  <div>
-    <span>{ctx.auth?.user?.name}</span>
-    <button onClick={() => ctx.auth?.logout()}>退出</button>
-  </div>
-) : (
-  <Login />
-)}
 // 登录
-ctx.auth.login('jwt-token', { id: 1, name: 'Alice' })
-// 退出
-ctx.auth.logout()
-```
-| `ctx.auth` | 类型 | 说明 |
-|-----------|------|------|
-| `token` | `Signal<string \| null>` | 当前 token |
-| `user` | `Signal<AuthUser \| null>` | 当前用户 |
-| `isLoggedIn` | `Signal<boolean>` | 是否已登录（computed）|
-| `login` | `(token, user) => void` | 存储 token + 用户到 localStorage |
-| `logout` | `() => void` | 清除 token + 用户 |
-| `setUser` | `(user) => void` | 更新用户信息 |
-| `authorizationHeader` | `Signal<string \| null>` | `'Bearer xxx'` 或 `null` |
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `storage` | `localStorage` | 存储方式 |
-| `tokenKey` | `'weifuwu_token'` | token 存储 key |
-| `userKey` | `'weifuwu_user'` | 用户信息存储 key |
+ctx.auth?.login(token, user)
-### 工具
-#### useForm — 表单管理
-```tsx
-const form = useForm({
-  initial: { name: '', email: '' },
-  validate: {
-    name: (v) => !v ? '请输入姓名' : null,
-    email: [
-      (v) => !v ? '请输入邮箱' : null,
-      (v) => !v.includes('@') ? '邮箱格式错误' : null,
-    ],
-  },
-  onSubmit: async (values) => {
-    await ctx.api.post('/users', values)
-  },
-})
+// 登出
+ctx.auth?.logout()
-// JSX：
-<form onSubmit={form.handleSubmit}>
-  <input {...form.field('name')} />
-  <span>{form.errors.value.name}</span>
-  <button disabled={form.submitting}>提交</button>
-</form>
+// 状态
+if (ctx.auth?.isLoggedIn) { ... }
 ```
-| 返回值 | 类型 | 说明 |
-|--------|------|------|
-| `values` | `Signal<T>` | 表单值 |
-| `errors` | `Signal<Partial<Record<keyof T, string\|null>>>` | 验证错误 |
-| `submitting` | `Signal<boolean>` | 提交状态 |
-| `touched` | `Signal<Partial<Record<keyof T, boolean>>>` | 触碰字段 |
-| `handleSubmit` | `(e: Event) => void` | 提交处理（绑定到 `<form>`）|
-| `field` | `(name) => { value, onInput, error }` | 字段绑定对象 |
-| `setValue` | `(name, value) => void` | 设字段值 |
-| `reset` | `() => void` | 重置表单 |
-| `validateAll` | `() => boolean` | 触发全部验证 |
+| API | 说明 |
+|------|------|
+| `ctx.auth.token` | JWT token |
+| `ctx.auth.user` | 用户对象 |
+| `ctx.auth.isLoggedIn` | 是否已登录 |
+| `ctx.auth.login(token, user, refreshToken?)` | 登录 |
+| `ctx.auth.logout()` | 登出 |
-#### createResource — 异步数据
+### ErrorBoundary
 ```tsx
-const [data, { loading, error, refetch }] = createResource(
-  () => fetch('/api/posts').then(r => r.json()),
-  { initialValue: [] }
-)
-// JSX：
-<Show when={loading}><p>加载中...</p></Show>
-<Show when={error}><p>错误: {error.value?.message}</p></Show>
-<Show when={computed(() => !loading.value && !error.value)}>
-  <For each={data}>{(item) => <div>{item.title}</div>}</For>
-</Show>
-```
+import { ErrorBoundary } from 'weifuwu/client'
-| 返回值 | 类型 | 说明 |
-|--------|------|------|
-| `data` (元组第一项) | `Signal<T \| undefined>` | 数据信号 |
-| `loading` | `Signal<boolean>` | 加载状态 |
-| `error` | `Signal<Error \| undefined>` | 错误信号 |
-| `refetch` | `() => void` | 手动重新加载 |
-#### ErrorBoundary — 错误捕获
-```tsx
-<ErrorBoundary
-  fallback={(e) => <p>出错了: {e.message}</p>}
-  onError={(e) => console.error(e)}
->
-  {() => <Dashboard />}   {/* 必须用 thunk */}
+<ErrorBoundary fallback={<p>出错了</p>}>
+  <UserProfile />
 </ErrorBoundary>
 ```
-#### createPortal — 渲染到指定位置
-```tsx
-<Show when={showModal}>
-  {createPortal(<Modal />, document.body)}
-</Show>
-```
-#### wrap — 封装三方库为组件
-```tsx
-const Chart = wrap('div', (el, props: { data: any }, ctx) => {
-  const chart = echarts.init(el)
-  chart.setOption(props.data)
-  effect(() => chart.setOption(props.data))
-  return () => chart.dispose()  // 卸载时自动清理
-})
-// 使用：
-<Chart data={salesData} />
-```
-#### createContext / extendCtx — 上下文扩展
-```tsx
-// 类型安全的 provide/inject
-const ThemeCtx = createContext<string>('theme')
-ThemeCtx.provide(ctx, 'dark')
-const theme = ThemeCtx.inject(ctx)  // 'dark' | null
-// 中间件注入
-function myMiddleware(): AppMiddleware {
-  return (ctx) => extendCtx(ctx, { myField: 'hello' })
-}
-```
-### React 对照表
+### 工具
-| React | weifuwu/client |
-|-------|----------------|
-| `useState(0)` | `$.count = 0` |
-| `useMemo(() => a*2, [a])` | `const doubled = a * 2`（render 时计算） |
-| `useEffect(() => f, [])` | `if (!ctx.ui.ready) { f() }` |
-| `{cond && <X/>}` | 相同 |
-| `{arr.map(i => <X/>)}` | 相同，加 `key` |
-| `Suspense` | `{$.loading && <Loading/>}` |
-| `useNavigate()` | `ctx.app?.navigate()` |
-| `useParams()` | `ctx.route?.params` |
-| `axios.get()` | `ctx.api?.get()` |
+| 函数 | 用途 |
+|------|------|
+| `extendCtx(ctx, fields)` | 创建新 ctx，继承原 ctx 的 getter |
 ### 前端类型
-`VNode`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `AuthClient`
+`VNode`, `VNodeType`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `ApiOptions`, `ApiRequestOptions`, `ApiError`, `AuthClient`, `AuthOptions`, `ErrorBoundaryProps`
 ---
 ## 布局 & 主题 (`weifuwu/layout`)
-纯 CSS 布局原语 + 主题 Token 系统，不绑定任何 JS 框架。
-```bash
-npm install weifuwu  # 已包含
-```
+纯 CSS 布局原语 + 主题 Token。不绑定任何 JS 框架。
 ```ts
-// 服务端编译 CSS
-app.get('/weifuwu.css', async (req, ctx) => ctx.ui.css('./node_modules/weifuwu/dist/layout/weifuwu-layout.css'))
+// 服务端编译
+app.get('/layout.css', async (req, ctx) => ctx.ui.css('./node_modules/weifuwu/dist/layout/weifuwu-layout.css'))
 ```
 ```html
 <!-- 或直接引入 -->
-<link rel="stylesheet" href="/weifuwu.css">
+<link rel="stylesheet" href="/layout.css">
+```
+### 使用示例
+```html
+<div class="wf-stack" style="--wf-gap: 24px">
+  <div class="wf-split">
+    <h2 style="color: var(--wf-color-text)">仪表盘</h2>
+    <button style="background: var(--wf-color-primary); color: #fff; border-radius: var(--wf-radius)">+ 新建</button>
+  </div>
+  <div class="wf-row" style="--wf-gap: 16px">
+    <div class="wf-fill wf-surface wf-stack" style="padding: 20px; background: var(--wf-color-bg); --wf-gap: 4px">
+      <span style="color: var(--wf-color-text-secondary)">总用户</span>
+      <span style="font-size: var(--wf-font-size-4xl); font-weight: var(--wf-font-weight-bold); color: var(--wf-color-text)">1,234</span>
+    </div>
+  </div>
+</div>
 ```
 ### 33 个布局原语
@@ -745,7 +532,7 @@ app.get('/weifuwu.css', async (req, ctx) => ctx.ui.css('./node_modules/weifuwu/d
 | 类别 | 原语 | 含义 | CSS 实现 |
 |------|------|------|---------|
 | **排列** | `wf-stack` | 纵向堆叠 | `flex-direction: column + gap` |
-| | `wf-stack-reverse` | 反向堆叠 | `flex-direction: column-reverse + gap` |
+| | `wf-stack-reverse` | 反向堆叠 | `flex-direction: column-reverse` |
 | | `wf-row` | 横向排列 | `flex + flex-wrap + gap` |
 | | `wf-row-reverse` | 反向排列 | `flex-direction: row-reverse` |
 | | `wf-nowrap` | 不换行 | `flex-wrap: nowrap` |
@@ -758,20 +545,20 @@ app.get('/weifuwu.css', async (req, ctx) => ctx.ui.css('./node_modules/weifuwu/d
 | **对齐** | `wf-top` | 顶部 | `align-items: flex-start` |
 | | `wf-bottom` | 底部 | `align-items: flex-end` |
 | | `wf-stretch` | 拉伸 | `align-items: stretch` |
-| **弹性** | `wf-fill` | 撑满 | `flex: 1 + min-width: 0` |
-| | `wf-fixed` | 固定 | `flex: none` |
-| | `wf-auto` | 按内容 | `flex: auto` |
-| | `wf-shrink` | 可收缩 | `min-width: 0 / min-height: 0` |
+| **弹性** | `wf-fill` | 撑满剩余空间 | `flex: 1 + min-width: 0` |
+| | `wf-fixed` | 固定不伸缩 | `flex: none` |
+| | `wf-auto` | 按内容撑满 | `flex: auto` |
+| | `wf-shrink` | 可收缩 | `min-width: 0 + min-height: 0` |
 | **Z轴** | `wf-cover` | 全屏覆盖 | `position: fixed + inset: 0` |
 | | `wf-pop` | 浮动层 | `position: absolute` |
 | | `wf-anchor` | 锚点容器 | `position: relative` |
 | | `wf-layer` | 层级控制 | `position: relative + z-index` |
-| | `wf-sticky` | 粘性 | `position: sticky` |
+| | `wf-sticky` | 粘性定位 | `position: sticky` |
 | **容器** | `wf-surface` | 基础面 | `border-radius + box-shadow + bg` |
-| | `wf-grid` | 网格 | `display: grid + --wf-cols` |
+| | `wf-grid` | 二维网格 | `display: grid + --wf-cols` |
 | | `wf-container` | 宽度约束 | `max-width + margin: auto` |
-| | `wf-scroll` | 滚动 | `overflow: auto` |
-| | `wf-clip` | 裁剪 | `overflow: hidden` |
+| | `wf-scroll` | 可滚动 | `overflow: auto` |
+| | `wf-clip` | 溢出裁剪 | `overflow: hidden` |
 | **显隐** | `wf-hidden` | 隐藏 | `display: none` |
 | | `wf-block` | 块级 | `display: block` |
 | | `wf-inline` | 行内 | `display: inline` |
@@ -780,151 +567,116 @@ app.get('/weifuwu.css', async (req, ctx) => ctx.ui.css('./node_modules/weifuwu/d
 ### 72 个主题 Token
-| 类别 | Token 示例 | 含义 |
-|------|-----------|------|
-| 品牌色 | `--wf-color-primary`, `--wf-color-primary-bg` | 品牌色、Hover、背景 |
-| 语义色 | `--wf-color-success`, `--wf-color-warning`, `--wf-color-error`, `--wf-color-info` | 状态语义色 |
-| 中性色 | `--wf-color-text`, `--wf-color-bg`, `--wf-color-border` | 文字/背景/边框 |
+| 类别 | Token 示例 | 值/层级 |
+|------|-----------|---------|
+| 品牌色 | `--wf-color-primary`, `--wf-color-primary-bg` | 品牌色 + Hover + 背景 |
+| 语义色 | `--wf-color-success/warning/error/info` | 各带 `-bg` 背景变体 |
+| 中性色 | `--wf-color-text/text-secondary/text-tertiary/text-disabled` | 4 级文字色 |
+| | `--wf-color-bg/bg-secondary/bg-tertiary` | 3 级背景色 |
+| | `--wf-color-border/border-light/border-dark` | 3 级边框色 |
 | 字体 | `--wf-font-sans`, `--wf-font-mono` | 字体族 |
-| 字号 | `--wf-font-size-xs` ~ `--wf-font-size-5xl`（9 级）| 字号层级 |
-| 字重 | `--wf-font-weight-normal` ~ `bold`（4 级）| 字重 |
-| 行高 | `--wf-line-height-tight`, `--wf-line-height`, `--wf-line-height-relaxed` | 行高 |
-| 字距 | `--wf-letter-spacing`, `--wf-letter-spacing-wide`, `--wf-letter-spacing-wider` | 字符间距 |
-| 间距 | `--wf-space-xs` ~ `--wf-space-2xl`（8 级）| margin / padding |
-| 间隔 | `--wf-gap-xs` ~ `--wf-gap-2xl`（6 级）| flex / grid gap |
-| 圆角 | `--wf-radius-sm` ~ `--wf-radius-xl`（5 级）| border-radius |
-| 阴影 | `--wf-shadow-sm` ~ `--wf-shadow-lg`（4 级）| box-shadow |
+| 字号 | `--wf-font-size-xs/sm/base/lg/xl/2xl/3xl/4xl/5xl` | 9 级字号 |
+| 字重 | `--wf-font-weight-normal/medium/semibold/bold` | 4 级字重 |
+| 行高 | `--wf-line-height-tight/normal/relaxed` | 3 级行高 |
+| 字距 | `--wf-letter-spacing/wide/wider` | 3 级字符间距 |
+| 间距 | `--wf-space-xs/sm/md/lg/xl/2xl` | 8 级 margin/padding |
+| 间隔 | `--wf-gap-xs/sm/md/lg/xl/2xl` | 6 级 flex/grid gap |
+| 圆角 | `--wf-radius-sm/md/lg/xl` | 5 级 border-radius |
+| 阴影 | `--wf-shadow-sm/md/lg` | 4 级 box-shadow |
 | 边框 | `--wf-border-width` | 边框宽度 |
-| 聚焦 | `--wf-focus-ring` | 聚焦环 |
-| 动效 | `--wf-transition-duration`, `--wf-transition-timing` | 过渡时长/曲线 |
-| 表单 | `--wf-accent-color`, `--wf-caret-color` | 表单控件主题色 |
-| 透明 | `--wf-opacity-disabled`, `--wf-opacity-overlay` | 禁用态/遮罩透明度 |
-| 层级 | `--wf-pop-z`, `--wf-cover-z` | z-index |
+| 聚焦 | `--wf-focus-ring` | 聚焦环（box-shadow）|
+| 动效 | `--wf-transition-duration/timing` | 过渡时长 + 曲线 |
+| 表单 | `--wf-accent-color`, `--wf-caret-color` | 控件主题色 + 光标色 |
+| 透明 | `--wf-opacity-disabled`, `--wf-opacity-overlay` | 禁用态 + 遮罩透明度 |
+| 层级 | `--wf-pop-z`, `--wf-cover-z` | z-index 层 |
 ### 暗色模式
-切换 `html` 标签的 `data-theme` 属性即可自动切换全部主题色：
+切换 `html` 的 `data-theme` 属性即可自动切换全部主题色：
 ```ts
-// weifuwu/client
-function toggleTheme() {
-  const dark = document.documentElement.getAttribute('data-theme') === 'dark'
-  document.documentElement.setAttribute('data-theme', dark ? 'light' : 'dark')
-}
+document.documentElement.setAttribute('data-theme', 'dark')
+// → 全部引用 var(--wf-*) 的元素自动变色
 ```
 ### 基础元素默认样式
-引入 `weifuwu/layout` 后，以下 HTML 元素自动绑定主题 Token，无需额外样式：
+引入 weifuwu/layout 后，以下 HTML 元素自动绑定主题 Token：
 `body`, `h1`~`h6`, `p`, `a`, `label`, `small`, `input`, `textarea`, `select`, `button`, `table`, `th`, `td`, `hr`, `pre`, `code`
 ---
-## 全栈模式
-### 认证流程
-```ts
-// 后端
-app.post('/api/login', async (req, ctx) => {
-  const { email } = await req.json()
-  return Response.json({
-    token: 'jwt_' + Math.random().toString(36),
-    user: { id: 1, name: email.split('@')[0], email },
-  })
-})
-// 前端
-app.use(api({ baseURL: '' }))
-app.use(auth())
+## 环境变量
-// 登录
-const res = await ctx.api.post('/api/login', { email, password })
-ctx.auth.login(res.token, res.user)
-```
+| 变量 | 用途 | 默认值 |
+|------|------|--------|
+| `DATABASE_URL` | PostgreSQL 连接字符串 | — |
+| `REDIS_URL` | Redis 连接字符串 | — |
-### 异步数据 + SSR
+---
-```ts
-// 后端 — 同路径既支持 SSR 也支持 API
-app.get('/api/posts', async (req, ctx) => {
-  return Response.json(posts)
-})
+## 项目结构
-// 前端 — 客户端获取
-const [posts, { loading }] = createResource(
-  () => ctx.api.get('/api/posts')
-)
 ```
-### 嵌套布局 + 代码分割
-```tsx
-const routes = [
-  {
-    path: '/dashboard',
-    layout: DashboardLayout,   // 侧边栏等 UI 保持挂载
-    children: [
-      { path: '/overview', component: lazy(() => import('./Overview')) },
-      { path: '/settings', component: lazy(() => import('./Settings')) },
-    ],
-  },
-]
+src/
+├── index.ts               # 统一导出
+├── types.ts               # 后端类型
+├── request.ts             # 请求解析
+├── response.ts            # 响应工具
+├── core/
+│   ├── router.ts          # HTTP 路由
+│   ├── serve.ts           # HTTP 服务器
+│   └── ws.ts              # WebSocket
+├── middleware/
+│   ├── cors.ts
+│   └── static.ts
+├── postgres/
+├── redis/
+├── graphql.ts
+├── ui/                    # SSR + JS/CSS 编译
+├── client/                # 前端 VDOM 框架
+│   ├── index.ts
+│   ├── vnode.ts
+│   ├── app.ts
+│   ├── render.ts
+│   ├── router.ts
+│   ├── types.ts
+│   ├── error-boundary.ts
+│   └── middleware/
+│       ├── api.ts
+│       ├── auth.ts
+│       └── ws.ts
+└── layout/                # 纯 CSS 布局 + 主题
+    ├── weifuwu-layout.css
+    ├── _tokens.css
+    ├── _dark.css
+    ├── _base.css
+    └── _*.css             # 33 个原语
 ```
 ---
-## 环境变量
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `DATABASE_URL` | `postgres://root:123456@localhost:5432/demo` | Postgres 连接字符串 |
-| `REDIS_URL` | `redis://localhost:6379` | Redis 连接字符串 |
----
-## Demo
+## 开发
 ```bash
-cd apps/demo
-node server.ts
-# http://localhost:3000
-```
+# 构建
+npm run build
-Demo 包含：嵌套布局、ctx.ui.$ 待办列表、手动表单、async fetch 数据请求、api + auth 认证、WebSocket 实时通信。
+# 类型检查
+npm run typecheck
----
-## 项目结构
+# 测试
+npm test
-```
-src/
-├── index.ts             入口，导出所有后端模块
-├── types.ts             Context, Handler, Middleware 等类型
-├── core/                Router, serve, WebSocket upgrade
-├── middleware/           cors, serveStatic
-├── postgres/            PostgreSQL 客户端
-├── redis/               Redis 客户端
-├── ui/                  SSR 渲染 + 动态编译
-├── graphql.ts           GraphQL
-├── client/
-│   ├── index.ts         前端导出入口
-│   ├── vnode.ts         VNode 类型 + JSX 工厂
-│   ├── render.ts        VDOM 渲染器（render + patchValue）
-│   ├── router.ts        路由中间件 + RouteView
-│   ├── app.ts           createApp 应用实例
-│   ├── types.ts         前端类型
-│   └── middleware/
-│       ├── ws.ts        WebSocket 客户端
-│       ├── api.ts       HTTP 客户端
-│       └── auth.ts      认证状态管理
-├── test/                测试
-apps/demo/               全栈 demo
+# 发布
+node scripts/release.mjs <version>
 ```
-```bash
-npm run build       # esbuild → dist/
-npm run typecheck   # tsc --noEmit
-npm test            # 运行所有测试
-```
+## 设计原则
+- **后端为工具箱** —— 提供 HTTP 路由、数据库、中间件原语，不捆绑业务模块
+- **全栈单包** —— `npm install weifuwu` = 后端 + 前端 + 布局
+- **Web 标准优先** —— 所有 handler 使用 `(req: Request, ctx: Context) => Response`
+- **零外部依赖** —— 前端和布局没有任何 npm 运行时依赖
+- **LLM 友好** —— 模块总览表 + 一致格式 + 清晰依赖链

package/package.json CHANGED Viewed

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