weifuwu 0.33.7 → 0.33.9

package/README.md

@@ -6,88 +6,196 @@
 npm install weifuwu
 ```
 
-One package. Backend + frontend. User system, instant messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage, and a reactive frontend framework. Configure environment variables and go.
+One package. Backend + frontend. User system, messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage, reactive frontend. Set env vars and go.
+
+---
+
+## Core Concept: `ctx`
+
+**`ctx` 是整个框架的核心模式。** 后端和前端共享同一个理念：通过中间件向 `ctx` 注入能力，组件/handler 直接从 `ctx` 读取。
+
+```
+后端:                                    前端:
+  Request → 中间件链 → Handler            createApp() → 中间件链 → 组件
+              │                                         │
+              ▼                                         ▼
+          ctx.sql                                  ctx.api
+          ctx.user                                 ctx.socket
+          ctx.kb                                   ctx.route
+          ctx.agent                                ctx.user
+          ctx.redis                                ctx.app.navigate
+          ctx.messager                             ctx.provide/inject
+          ctx.cms
+          ctx.base
+          ctx.queue
+          ctx.ui
+```
+
+**后端每个请求创建一个 ctx：**
+```ts
+// 中间件注入 → handler 直接使用
+app.get('/api/chat', async (req, ctx) => {
+  const user = ctx.user           // 当前用户（auto-resolve from JWT）
+  const result = await ctx.kb.search(query)      // RAG 知识库
+  return ctx.agent.chatStreamResponse({ messages })  // AI 流式响应
+})
+```
+
+**前端每个组件通过第二个参数接收 ctx：**
+```tsx
+function ChatPage(_props: {}, ctx: WfuiContext) {
+  ctx.api.get('/api/posts')       // HTTP 客户端
+  ctx.socket.send(data)           // WebSocket
+  ctx.route.path                  // 当前路由
+  ctx.app.navigate('/about')      // 页面导航
+}
+```
+
+这种模式让开发者**无需 import 任何工具函数**，所有能力在 `ctx` 中一站获取。
+
+---
+
+## Module Overview
+
+### Backend — 每个模块向 ctx 注入什么
+
+| Module | Import | Injects into `ctx` | Depends on | Purpose |
+|--------|--------|-------------------|------------|---------|
+| `postgres()` | `weifuwu` | `ctx.sql` | `DATABASE_URL` | PostgreSQL client |
+| `redis()` | `weifuwu` | `ctx.redis` | `REDIS_URL` | Redis client |
+| `user()` | `weifuwu` | `ctx.user`, `ctx.userModule` | `postgres()`, `JWT_SECRET` | Auth, JWT, roles |
+| `messager()` | `weifuwu` | `ctx.messager` | `postgres()`, `user()` | IM + AI conversation |
+| `kb()` | `weifuwu` | `ctx.kb` | `postgres()`, `DASHSCOPE_API_KEY` | RAG knowledge base |
+| `agent()` | `weifuwu` | `ctx.agent` | — | LLM chat, tools, streaming |
+| `cms()` | `weifuwu` | `ctx.cms` | `postgres()`, `user()` | Blog, docs, changelog |
+| `base()` | `weifuwu` | `ctx.base` | `postgres()`, `user()` | Dynamic data engine |
+| `queue()` | `weifuwu` | `ctx.queue` | `REDIS_URL` | Job queue + cron |
+| `ui()` | `weifuwu` | `ctx.ui.html/js/css` | — | SSR/SPA rendering |
+
+### Backend Middleware
+
+| Middleware | Injects into `ctx` | Purpose |
+|-----------|-------------------|---------|
+| `cors()` | — | CORS headers |
+| `helmet()` | — | Security headers |
+| `compress()` | — | gzip / brotli / deflate |
+| `rateLimit()` | — | Sliding-window rate limiter |
+| `logger()` | — | Request logging |
+| `upload()` | `ctx.upload` | Multipart file upload |
+| `serveStatic()` | — | Static files |
+| `sandbox()` | — | Filesystem isolation |
+
+### Frontend (`weifuwu/client`) — 每个中间件向 ctx 注入什么
+
+| Import | Type | Injects into `ctx` | Purpose |
+|--------|------|-------------------|---------|
+| `signal()` | function | — | Reactive state container |
+| `computed()` | function | — | Derived signals |
+| `effect()` | function | — | Auto-tracked side effects |
+| `batch()` | function | — | Batch multiple signal writes |
+| `untrack()` | function | — | Read signal without subscribing |
+| `onMount()` | function | — | Component mount callback |
+| `onCleanup()` | function | — | Component unmount callback |
+| `api()` | **middleware** | `ctx.api.get/post/...` | HTTP client |
+| `auth()` | **middleware** | `ctx.user/login/logout` | Auth state management |
+| `socket()` | **middleware** | `ctx.socket.send/onMessage/...` | WebSocket client |
+| `router()` | **middleware** | `ctx.route.path/params/query`, `ctx.app.navigate` | Hash/history router |
+| `createApp()` | function | — | App instance |
+| `<RouteView>` | component | — | Route outlet |
+| `<Show>` | component | — | Conditional rendering |
+| `<For>` | component | — | Keyed list rendering |
+| `<Transition>` | component | — | Animated enter/leave |
+| `<ErrorBoundary>` | component | — | Catch render errors |
+| `<Link>` | component | — | SPA navigation link |
+| `<LoginForm>` | component | — | Login/register form |
+| `<Chat>` | component | — | Real-time messaging |
+| `useForm()` | function | — | Form state management |
+| `useModel()` | function | — | Two-way form binding |
+| `reactiveArray()` | function | — | Reactive array with mut methods |
+| `createResource()` | function | — | Async data (loading/error/data) |
+| `createStyles()` | function | — | Scoped CSS |
+| `createContext()` | function | — | Type-safe provide/inject |
+| `createPortal()` | function | — | Render outside parent DOM |
+| `wrap()` | function | — | Third-party lib integration |
+| `enableDevtools()` | function | — | Dev warnings + browser inspector |
 
 ---
 
 ## Quick Start
 
-### Backend
+### 完整全栈示例 — ctx 贯穿前后端
 
+**后端 `server.ts`：**
 ```ts
-import { serve, Router, postgres, user, kb, agent, messager } from 'weifuwu'
+import { serve, Router, postgres, user, agent, kb, messager, ui, cors, logger } from 'weifuwu'
 import { openai } from '@ai-sdk/openai'
 
 const app = new Router()
-app.use(postgres())
-app.use(user())
-app.use(kb())
-app.use(messager())
+app.use(cors())
+app.use(logger())
+app.use(postgres())                    // → ctx.sql
+app.use(user())                        // → ctx.user, ctx.userModule
+app.use(kb())                          // → ctx.kb
 app.use(agent({
   model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
   knowledge: { search: async (q, ctx) => ctx.kb.search(q) },
-}))
+}))                                     // → ctx.agent
+app.use(messager())                    // → ctx.messager
+app.use(ui())                          // → ctx.ui
 
+// 业务 API — ctx 中所有能力可直接使用
 app.post('/api/chat', async (req, ctx) => {
   const { messages } = await req.json()
   return ctx.agent.chatStreamResponse({ messages })
 })
 
+app.post('/api/messages', async (req, ctx) => {
+  const msg = await ctx.messager.sendMessage(ctx.params.conversationId, req.body)
+  return Response.json(msg, { status: 201 })
+})
+
+// 客户端编译（无需本地构建步骤）
+app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
+
 serve(app, { port: 3000 })
 ```
 
-### Frontend
-
+**前端 `src/main.tsx` — ctx 驱动组件：**
 ```tsx
-import { signal, createApp, api, auth, ws, router, RouteView, LoginForm } from 'weifuwu/client'
+import { signal, createApp, api, auth, socket, router, RouteView, LoginForm, Link } from 'weifuwu/client'
 import type { WfuiContext } from 'weifuwu/client'
 
 function AppShell(_props: {}, ctx: WfuiContext) {
   if (!ctx.isAuthenticated) return <LoginForm />
   return (
     <div>
-      <nav><a onClick={() => ctx.app.navigate('/chat')}>聊天</a></nav>
+      <nav><Link to="/chat">Chat</Link></nav>
       <main><RouteView /></main>
     </div>
   )
 }
 
 const app = createApp()
-app.use(api())              // ← ctx.api.get/post
-app.use(auth())             // ← ctx.user / ctx.login / ctx.logout
-app.use(ws())               // ← ctx.ws.send / onMessage
-app.use(router({ routes })) // ← ctx.route / 路由
+app.use(api())                        // → ctx.api.get/post/...
+app.use(auth())                       // → ctx.user/login/logout
+app.use(socket())                     // → ctx.socket.send/onMessage
+app.use(router({ routes }))           // → ctx.route.path/params/query
 app.mount('#root', AppShell)
 ```
 
+**`tsconfig.json`：**
 ```json
-// tsconfig.json
 { "jsx": "react-jsx", "jsxImportSource": "weifuwu/client" }
 ```
 
-```js
-// build.mjs — 传统构建方式（可选）
-// 推荐：使用 ctx.ui.js() 服务端动态编译，无需独立构建脚本
-esbuild.build({
-  entryPoints: ['src/main.tsx'],
-  jsx: 'automatic',
-  jsxImportSource: 'weifuwu/client',
-  bundle: true,
-})
-```
-
-或用服务端动态编译——一行代码，无需构建步骤、无需 watch 模式：
-```ts
-app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
-app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
-```
+---
 
-### Environment Variables
+## Environment Variables
 
 | Variable | Default | Used by |
 |----------|---------|---------|
 | `DATABASE_URL` | `postgres://root:123456@localhost:5432/demo` | `postgres()` |
-| `REDIS_URL` | `redis://localhost:6379` | `redis()` |
+| `REDIS_URL` | `redis://localhost:6379` | `redis()`, `queue()` |
 | `JWT_SECRET` | — | `user()` |
 | `DASHSCOPE_API_KEY` | — | `kb()` (embedding) |
 | `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | `agent()` (LLM) |
@@ -95,572 +203,92 @@ app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
 
 ---
 
-## Modules
-
-### Backend
-
-| Module | Import | Dependency | Purpose |
-|--------|--------|-----------|---------|
-| User | `user()` | `postgres()` | Auth, JWT, roles |
-| Messager | `messager()` | `postgres()`, `user()` | IM + AI conversation layer |
-| KB | `kb()` | `postgres()` | RAG knowledge base |
-| Agent | `agent()` | — | LLM chat, tool calling, streaming |
-| CMS | `cms()` | `postgres()`, `user()` | Blog, docs, changelog |
-| Base | `base()` | `postgres()`, `user()` | Dynamic data engine |
-
-### Middleware
-
-| Import | Purpose |
-|--------|---------|
-| `cors()` | CORS headers |
-| `helmet()` | Security headers |
-| `compress()` | gzip / brotli / deflate |
-| `rateLimit()` | Sliding-window rate limiter |
-| `logger()` | Request logging |
-| `upload()` | Multipart file upload |
-| `serveStatic()` | Static files |
-| `sandbox()` | Filesystem isolation |
-
-### Core
-
-| Import | Purpose |
-|--------|---------|
-| `serve(app, opts?)` | Start HTTP server |
-| `Router` | Trie-based router + WebSocket |
-| `HttpError` | `throw new HttpError(msg, 404)` |
-| `trace()` | Request tracing |
-| `postgres()` | PostgreSQL client (`ctx.sql`) |
-| `redis()` | Redis client (`ctx.redis`) |
-| `queue()` | Job queue + cron |
-| `createHub()` | WebSocket pub/sub |
-| `ui()` | SSR + SPA rendering (`ctx.ui.html`, `ctx.ui.js`, `ctx.ui.css`) |
-
-### Frontend (weifuwu/client)
-
-| Import | Purpose |
-|--------|---------|
-| `signal()` | Reactive state |
-| `computed()` | Derived signals |
-| `effect()` | Auto-tracked side effects |
-| `<Show>` | Conditional rendering |
-| `<For>` | List rendering |
-| `<RouteView>` | Route outlet |
-| `createApp()` | App instance with middleware chain |
-| `router()` | Hash/history router with params + query |
-| `api()` | HTTP client (`ctx.api.get/post`) |
-| `auth()` | Auth state (`ctx.user/login/logout`) |
-| `ws()` | WebSocket (`ctx.ws.send/onMessage`) |
-| `LoginForm` | Login/register form component |
-| `Chat` | Real-time messaging component |
-| `domMount()` | Direct DOM mounting |
-| `wrap()` | Third-party library integration |
-| `useForm()` | Form state management (validation, submit, reset) |
-| `createPortal()` | Render outside parent DOM hierarchy |
-| `<ErrorBoundary>` | Catch render errors, show fallback |
-
-### Utilities
-
-| Import | Purpose |
-|--------|---------|
-| `requireRole('admin')` | Middleware: check `ctx.user.role` |
-
----
-
-## Frontend (weifuwu/client)
-
-**weifuwu/client** is a reactive frontend framework built on Signal + TSX. Zero virtual DOM, zero dependencies, ~600 lines total.
-
-### Concepts
+## Backend Modules
 
+### postgres
 ```ts
-// 1. Signal — reactive data
-const count = signal(0)
-count.value = count.value + 1  // DOM updates automatically
-
-// 2. Computed — derived signals
-const doubled = computed(() => count.value * 2)
-
-// 3. Effect — auto-tracked side effects
-effect(() => console.log('count:', count.value))
-
-// 4. Component — (props, ctx) => JSX
-function MyComponent({ name }: { name: string }, ctx: WfuiContext) {
-  return <div>Hello {name}</div>
-}
-```
-
-### createApp + Middleware
-
-```tsx
-import { createApp, router, RouteView } from 'weifuwu/client'
-import type { WfuiContext, RouteDef } from 'weifuwu/client'
-
-const app = createApp()
-app.use(router({ routes, mode: 'hash' }))
-app.mount('#root', AppShell)
-```
-
-### Router
-
-```tsx
-const routes: RouteDef[] = [
-  { path: '/', component: HomePage, title: '首页' },
-  { path: '/chat/:id', component: ChatPage, title: '聊天' },
-  { path: '/user/:name', component: UserPage, title: '用户' },
-]
-
-app.use(router({
-  routes,
-  notFound: NotFound,
-  mode: 'hash', // or 'history'
-}))
-
-// In layout:
-function AppShell(_, ctx) {
-  return (
-    <div>
-      <nav>
-        <a onClick={() => ctx.app.navigate('/')}>首页</a>
-        <a onClick={() => ctx.app.navigate('/chat/123')}>聊天</a>
-      </nav>
-      <main>
-        <RouteView />  {/* ← renders matched route */}
-      </main>
-    </div>
-  )
-}
-
-// Route params and query:
-ctx.route.path     // "/chat/123"
-ctx.route.params   // { id: "123" }
-ctx.route.query    // { tab: "settings" }
-
-#### Route Loader — 数据预取
-
-```tsx
-const routes: RouteDef[] = [
-  {
-    path: '/post/:id',
-    component: PostPage,
-    loader: async (ctx) => ({
-      post: await ctx.api.get(`/api/posts/${ctx.route.params.id}`),
-    }),
-  },
-]
-
-// In component:
-function PostPage(_, ctx) {
-  const post = ctx.route.data.post
-  if (!post) return <p class="text-gray-400">加载中...</p>
-  return <h1 class="text-2xl font-bold">{post.title}</h1>
-}
-```
-
-组件先渲染（显示 loading），loader 完成后自动重渲染。
-
-### Middleware: api / auth / ws
-
-```tsx
-import { api, auth, ws } from 'weifuwu/client'
-
-app.use(api())    // ctx.api.get/post/put/patch/delete
-app.use(auth())   // ctx.user / ctx.login / ctx.logout / ctx.register
-app.use(ws())     // ctx.ws.send / onMessage / join / leave
-```
-
-`api()` creates a fetch client with automatic token injection.
-`auth()` persists sessions to localStorage, validates tokens on startup.
-`ws()` manages WebSocket connections with auto-reconnect.
-
-### Pre-built Components
-
-```tsx
-import { LoginForm, Chat } from 'weifuwu/client'
-
-// Login / Register form
-function LoginPage(_, ctx) {
-  if (ctx.isAuthenticated) return ctx.app.navigate('/')
-  return <LoginForm />
-}
-
-// Real-time chat
-function ChatPage(_, ctx) {
-  return <Chat conversationId="123" />
-}
+import { postgres } from 'weifuwu'
+const sql = postgres()
+app.use(sql)  // → ctx.sql
+await ctx.sql`SELECT * FROM users WHERE id = ${id}`
+await ctx.sql.begin(async (sql) => { /* transaction */ })
 ```
+| Method | Description |
+|--------|-------------|
+| `ctx.sql\`...\`` | Tagged template SQL |
+| `ctx.sql.begin(fn)` | Transaction |
+| `sql.close()` | Close pool |
 
-### SSR & SPA (ctx.ui.html / ctx.ui.js / ctx.ui.css)
-
+### redis
 ```ts
-import { ui } from 'weifuwu'
-
-app.use(ui())
-
-// SSR page — ctx.ui.html`` returns complete HTML Response
-app.get('/blog/:slug', async (req, ctx) => ctx.ui.html`
-  <!DOCTYPE html>
-  <html>
-  <head>
-    <title>${post.title}</title>
-    <link rel="stylesheet" href="/static/style.css">
-  </head>
-  <body>
-    <div id="root">
-      <h1>${post.title}</h1>
-      <div>${ctx.ui.html.unsafe(post.body)}</div>
-      <div data-hydrate="like"></div>
-    </div>
-    <script>window.__WFUI_PROPS__=${ctx.ui.html.unsafe(JSON.stringify({ post }))}</script>
-    <script src="/static/app.js"></script>
-  </body>
-  </html>
-`)
-
-// Dynamic JS compilation — ctx.ui.js() compiles TSX on demand
-app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
-
-// Dynamic CSS serving — ctx.ui.css() reads and serves CSS
-app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
-
-// Client hydrates interactive sections, skips SSR content
-const app = createApp()
-app.use(api())
-
-const root = document.getElementById('root')
-if (root && root.children.length > 0) {
-  // SSR page — hydrate only interactive areas
-  app.hydrate('[data-hydrate="like"]', LikeButton)
-} else {
-  // SPA page — full mount
-  app.mount('#root', AppShell)
-}
-```
-
-### wrap() — Third-party Library Integration
-
-```tsx
-import { wrap, effect } from 'weifuwu/client'
-import * as echarts from 'echarts'
-
-// wrap(tagName, setup) creates a component:
-// - Creates a <div> container
-// - Calls setup(el, props, ctx) when element enters the document
-// - Runs cleanup when element is removed
-const PieChart = wrap('div', (el, props: { data: any[] }, ctx) => {
-  const chart = echarts.init(el)
-  chart.setOption({ series: [{ type: 'pie', data: props.data }] })
-  effect(() => chart.setOption({ series: [{ type: 'pie', data: props.data }] }))
-  return () => chart.dispose()
-})
-
-// Use in JSX like any component
-<Dashboard>
-  <PieChart data={salesData} />
-</Dashboard>
-```
-
-### useForm() — 表单状态管理
-
-```tsx
-import { useForm } from 'weifuwu/client'
-
-const form = useForm({
-  initial: { email: '', password: '' },
-  validate: {
-    email: (v) => !v.includes('@') && '请输入有效邮箱',
-    password: (v) => v.length < 6 && '至少 6 位',
-  },
-})
-
-// 绑定到 input：{...form.field('name')} 自动设置 value + onInput
-<input {...form.field('email')} placeholder="邮箱" />
-{form.errors.email && <span class="text-red-500">{form.errors.email}</span>}
-
-// 提交时自动验证所有字段
-<button onClick={() => form.submit((data) => ctx.login(data.email, data.password))}>
-  登录
-</button>
-
-// 重置
-<button onClick={form.reset}>重置</button>
-
-// 编程设置
-form.setValue('email', 'a@b.com')
-form.setValues({ email: 'a@b.com', password: '123' })
-```
-
-### createPortal() — 渲染到父容器外
-
-适用于 Modal、Dropdown、Tooltip 等需突破 `overflow: hidden` 或 z-index 层级的情况。
-
-```tsx
-import { createPortal, Show } from 'weifuwu/client'
-
-function Modal({ show, title, children }) {
-  return <Show when={show}>
-    {createPortal(
-      <div class="fixed inset-0 bg-black/50 flex items-center justify-center">
-        <div class="bg-white rounded-xl p-6 min-w-[400px]">
-          <h2 class="text-lg font-bold mb-4">{title}</h2>
-          {children}
-        </div>
-      </div>,
-      document.body
-    )}
-  </Show>
-}
-```
-
-### ErrorBoundary — 错误边界
-
-子组件渲染异常时捕获，显示 fallback 而非白屏。children 必须是 thunk（延迟执行）。
-
-```tsx
-import { ErrorBoundary } from 'weifuwu/client'
-
-function AppShell(_, ctx) {
-  return (
-    <div>
-      <nav>...</nav>
-      <main>
-        <ErrorBoundary fallback={(e) => <p>出错了: {e.message}</p>}>
-          {() => <RouteView />}
-        </ErrorBoundary>
-      </main>
-    </div>
-  )
-}
-```
-
-### Show / For
-
-```tsx
-// Conditional rendering (supports Signal)
-<Show when={isLoggedIn} fallback={<LoginPage />}>
-  <Dashboard />
-</Show>
-
-// List rendering (supports Signal)
-<For each={filteredItems}>
-  {(item) => <div>{item.name}</div>}
-</For>
+import { redis } from 'weifuwu'
+const r = redis()
+app.use(r)  // → ctx.redis
+await ctx.redis.set('key', 'value')
+await ctx.redis.get('key')
+redis.close()
 ```
+Reads `REDIS_URL` env (default: `redis://localhost:6379`).
 
----
-
-## user
-
-Auth, registration, JWT, password management, roles.
-
+### user
 ```ts
 import { user, requireRole } from 'weifuwu'
-
 app.use(postgres())
 app.use(user({ secret: process.env.JWT_SECRET }))
+// → ctx.user (UserRecord | undefined), ctx.userModule
 
-// Register
-app.post('/api/register', async (req, ctx) => {
-  const result = await ctx.userModule.register(await req.json())
-  return Response.json(result)
-})
-// Login
-app.post('/api/login', async (req, ctx) => {
-  const { email, password } = await req.json()
-  const result = await ctx.userModule.login(email, password)
-  if (!result) return new Response('Unauthorized', { status: 401 })
-  return Response.json(result)
-})
-// Current user
+// ctx.user 由 Authorization Bearer token 或 token cookie 自动解析
 app.get('/api/me', async (req, ctx) => {
   if (!ctx.user) return new Response('Unauthorized', { status: 401 })
-  return Response.json(ctx.user)
-})
-// Admin only
-app.get('/api/admin/users', requireRole('admin'), async (req, ctx) => {
-  return Response.json(await ctx.userModule.listUsers())
+  return Response.json(ctx.user)  // ctx.user.name / .email / .role
 })
 ```
-
-### ctx.userModule API
-
-| Method | Returns | Description |
-|--------|---------|-------------|
+| `ctx.userModule.*` | Returns | Description |
+|--------------------|---------|-------------|
 | `register(input)` | `{ user, token }` | Register |
 | `login(email, pw)` | `{ user, token } \| null` | Login |
 | `getUserById(id)` | `UserRecord \| null` | Get by ID |
-| `getUserByEmail(email)` | `UserRecord \| null` | Get by email |
 | `updateUser(id, input)` | `UserRecord \| null` | Update |
 | `changePassword(id, oldPw, newPw)` | `boolean` | Change password |
 | `deleteUser(id)` | `boolean` | Soft delete |
 | `listUsers(inactive?)` | `UserRecord[]` | List users |
-| `generateToken(user)` | `string` | Issue JWT |
 | `verifyToken(token)` | `TokenPayload \| null` | Verify JWT |
-| `refreshToken(token)` | `string \| null` | Refresh JWT |
-
-### ctx.user
-
-Auto-resolved from `Authorization: Bearer` or `token` cookie.
-
-```ts
-interface User {
-  id: string
-  name: string
-  email: string
-  role: string
-  [key: string]: unknown
-}
-```
-
-### requireRole
-
-```ts
-app.get('/admin', requireRole('admin'), handler)
-// No auth → 401, wrong role → 403
-```
-
-### Security
 
-- Password: scrypt + 32-byte random salt
-- Token: HMAC SHA-256, 7 day expiry
-
----
-
-## messager
-
-Instant messaging + AI conversation layer. Direct/group chat, message persistence, WebSocket push.
+`requireRole('admin')` — guard middleware. No auth → 401, wrong role → 403.
 
+### messager
 ```ts
 import { messager } from 'weifuwu'
-
 app.use(postgres())
 app.use(user())
-app.use(messager())
-
-// WebSocket — auto-join all user conversations
-app.ws('/ws', {
-  async open(ws, ctx) {
-    for (const c of await ctx.messager.getConversations()) {
-      ctx.ws.join(`conversation:${c.id}`)
-    }
-  },
-})
-
-// REST API
-app.post('/api/messages', async (req, ctx) => {
-  const { conversationId, body } = await req.json()
-  const msg = await ctx.messager.sendMessage(conversationId, body)
-  return Response.json(msg, { status: 201 })
-})
-
-app.get('/api/conversations/:id/messages', async (req, ctx) => {
-  const url = new URL(req.url)
-  return Response.json(await ctx.messager.getMessages(ctx.params.id, {
-    before: url.searchParams.get('before') || undefined,
-    limit: parseInt(url.searchParams.get('limit') || '50'),
-  }))
-})
+app.use(messager())  // → ctx.messager
 ```
-
-### ctx.messager API
-
-| Method | Returns | Description |
-|--------|---------|-------------|
+| `ctx.messager.*` | Returns | Description |
+|------------------|---------|-------------|
+| `sendMessage(convId, body)` | `Message` | Send + WebSocket broadcast |
+| `getMessages(convId, opts?)` | `Message[]` | Cursor pagination |
+| `getConversations()` | `Conversation[]` | List with unread |
 | `createDirectConversation(userId)` | `Conversation` | Create/reuse DM |
 | `createGroupConversation(title, userIds)` | `Conversation` | Create group |
-| `sendMessage(convId, body)` | `Message` | Send, auto-broadcast to `conversation:{id}` room |
-| `getMessages(convId, opts?)` | `Message[]` | Cursor pagination |
-| `editMessage(msgId, body)` | `Message \| null` | Edit (24h window) |
+| `editMessage(msgId, body)` | `Message \| null` | Edit (24h) |
 | `deleteMessage(msgId)` | `boolean` | Soft delete |
-| `getConversations()` | `Conversation[]` | List with unread + last message |
-| `getConversation(id)` | `Conversation \| null` | Get detail |
 | `markRead(convId)` | `void` | Mark as read |
-| `getUnreadCount()` | `{ total, byConversation }` | Unread stats |
-| `addParticipants(convId, userIds)` | `void` | Add members |
-| `removeParticipant(convId, userId?)` | `boolean` | Leave / kick |
-
-### Storage
-
-3 tables: `conversations` / `participants` / `messages`. Auto-migration.
-
-### AI Conversations
-
-messager + agent = ChatGPT foundation. Messager handles sessions + push, agent handles LLM generation.
-
----
-
-## kb
-
-RAG knowledge base. Import docs → auto-chunk → DashScope embedding → pgvector storage → semantic search.
 
+### kb — Knowledge Base
 ```ts
 import { kb } from 'weifuwu'
-
 app.use(postgres())
-app.use(kb())
-
-// Import
-app.post('/api/kb/import', async (req, ctx) => {
-  const { title, content } = await req.json()
-  const result = await ctx.kb.importText(title, content)
-  return Response.json(result, { status: 201 })
-})
-
-// Search
-app.post('/api/kb/search', async (req, ctx) => {
-  const { query } = await req.json()
-  return Response.json(await ctx.kb.search(query, { limit: 5 }))
-})
+app.use(kb())  // → ctx.kb
 ```
-
-### ctx.kb API
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `importText(title, text, opts?)` | `{ document, chunks }` | Import → chunk → embed → store |
-| `importDocuments(docs)` | `Document[]` | Batch import |
-| `search(query, opts?)` | `SearchResult[]` | Semantic search (cosine) |
+| `ctx.kb.*` | Returns | Description |
+|------------|---------|-------------|
+| `importText(title, text)` | `{ document, chunks }` | Import → chunk → embed |
+| `search(query, opts?)` | `SearchResult[]` | Semantic search |
 | `list()` | `Document[]` | List documents |
 | `get(id)` | `Document \| null` | Get document |
-| `getChunks(documentId)` | `Chunk[]` | Get chunks |
 | `delete(id)` | `boolean` | Delete + cascade chunks |
 
-### Configuration
-
-```ts
-// Default: DashScope text-embedding-v4 (env: DASHSCOPE_API_KEY)
-app.use(kb())
-
-// Custom embedding
-app.use(kb({
-  embed: async (text) => { /* return number[] */ },
-  dimensions: 1536,
-  chunkSize: 512,    // tokens
-  chunkOverlap: 64,
-}))
-```
-
-### Integration with Agent
-
-```ts
-app.use(agent({
-  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
-  knowledge: {
-    search: async (query, ctx) => ctx.kb.search(query),
-  },
-}))
-```
-
-### Storage
-
-- `kb_documents` — document metadata
-- `kb_chunks` — chunk content + VECTOR(1536) + TSVECTOR GIN index
-
----
-
-## agent
-
-AI Agent — LLM chat, tool calling, RAG, streaming.
-
+### agent
 ```ts
 import { agent } from 'weifuwu'
 import { openai } from '@ai-sdk/openai'
@@ -670,9 +298,7 @@ import { z } from 'zod'
 app.use(agent({
   model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
   system: 'You are a helpful assistant.',
-  knowledge: {
-    search: async (query, ctx) => ctx.kb.search(query),
-  },
+  knowledge: { search: async (q, ctx) => ctx.kb.search(q) },
   tools: {
     getWeather: tool({
       description: 'Get weather for a city',
@@ -681,260 +307,268 @@ app.use(agent({
     }),
   },
   maxSteps: 5,
-}))
-
-// Streaming
-app.post('/api/chat', async (req, ctx) => {
-  const { messages } = await req.json()
-  return ctx.agent.chatStreamResponse({ messages })
-})
-
-// Non-streaming
-app.post('/api/chat/sync', async (req, ctx) => {
-  const { prompt } = await req.json()
-  const text = await ctx.agent.chat(prompt)
-  return Response.json({ text })
-})
+}))  // → ctx.agent
 ```
-
-### ctx.agent API
-
-| Method | Description |
-|-------------|-------------|
+| `ctx.agent.*` | Description |
+|--------------|-------------|
 | `chat(prompt, opts?)` | Non-streaming, returns text |
-| `chatStreamResponse({ messages })` | SSE stream (compatible with `useChat`) |
+| `chatStreamResponse({ messages })` | SSE stream (useChat compatible) |
 
-### Default Model
+### cms
+```ts
+import { cms, requireRole } from 'weifuwu'
+app.use(postgres())
+app.use(user())
+app.use(cms())  // → ctx.cms
+```
+| `ctx.cms.*` | Returns | Description |
+|-------------|---------|-------------|
+| `create(input)` | `Content` | Create (admin) |
+| `get(slug)` | `Content \| null` | Get by slug |
+| `list(opts?)` | `Content[]` | List with filters |
+| `publish(id)` / `unpublish(id)` | `Content \| null` | Toggle status |
 
-- LLM: DeepSeek-V4-Flash (via `@ai-sdk/openai` + `baseURL: 'https://api.deepseek.com/v1'`)
-- Override with `DEEPSEEK_MODEL` env
-- API key via `DEEPSEEK_API_KEY` or `OPENAI_API_KEY` env
+### base — Dynamic Data Engine
+```ts
+app.use(base())  // → ctx.base
+ctx.base.create({ name, tables })
+ctx.base.insert(baseId, table, data)
+ctx.base.query(baseId, table, { filter, limit })
+```
 
-### Features
+### queue
+```ts
+const q = queue()
+app.use(q)
+q.process('email', async (job) => { ... })
+q.cron('cleanup', '0 3 * * *', () => ...)
+await q.add('email', { to: 'user@example.com' })
+q.run()
+```
 
-| Feature | Description |
-|---------|-------------|
-| `knowledge.search` | RAG callback, auto-injected into system prompt |
-| `tools` | Tool definitions, auto-loop (maxSteps) |
-| `sandbox: true` | Integrates with `ctx.sandbox` |
-| `store` | Session persistence (save/load) |
-| `agents` | Multi-agent orchestration |
+### ui — SSR & SPA
+```ts
+app.use(ui())  // → ctx.ui
+// SSR page
+app.get('/blog/:slug', async (req, ctx) => ctx.ui.html`<!DOCTYPE html>...`)
+// Dynamic JS compilation (no build step)
+app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
+// CSS with Tailwind v4 support
+app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./public/style.css'))
+```
 
 ---
 
-## cms
+## Frontend — weifuwu/client
 
-Content management — blog, docs, changelog.
+Reactive frontend framework. Zero virtual DOM, zero external dependencies.
 
-```ts
-import { cms, requireRole } from 'weifuwu'
+### Core APIs
 
-app.use(postgres())
-app.use(user())
-app.use(cms())
+```tsx
+// Signal — reactive state
+const count = signal(0)
+const doubled = computed(() => count.value * 2)
+effect(() => console.log('count:', count.value))
 
-// Public
-app.get('/api/posts', async (req, ctx) => {
-  return Response.json(await ctx.cms.list({ type: 'post', status: 'published' }))
-})
-app.get('/api/posts/:slug', async (req, ctx) => {
-  const post = await ctx.cms.get(ctx.params.slug)
-  if (!post) return new Response('Not found', { status: 404 })
-  return Response.json(post)
-})
+// Batch — merge multiple writes
+batch(() => { a.value = 1; b.value = 2 })
 
-// Admin
-app.post('/api/admin/posts', requireRole('admin'), async (req, ctx) => {
-  const post = await ctx.cms.create(await req.json())
-  return Response.json(post, { status: 201 })
-})
-app.patch('/api/admin/posts/:id', requireRole('admin'), async (req, ctx) => {
-  const post = await ctx.cms.update(ctx.params.id, await req.json())
-  if (!post) return new Response('Not found', { status: 404 })
-  return Response.json(post)
-})
+// Untrack — read without subscribing
+effect(() => { console.log(untrack(() => theme.value)) })
+
+// Lifecycle
+onMount(() => { init(); return () => cleanup() })
+onCleanup(() => clearInterval(id))
 ```
 
-### ctx.cms API
+### Reactive Array
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `create(input)` | `Content` | Create (admin) |
-| `get(slug)` | `Content \| null` | Get by slug |
-| `getById(id)` | `Content \| null` | Get by ID |
-| `update(id, input)` | `Content \| null` | Update (admin) |
-| `delete(id)` | `boolean` | Delete (admin) |
-| `list(opts?)` | `Content[]` | List with cursor |
-| `publish(id)` | `Content \| null` | Publish (admin) |
-| `unpublish(id)` | `Content \| null` | Unpublish (admin) |
-| `listTags()` | `TagWithCount[]` | List tags |
-| `createTag(name)` | `Tag` | Create tag |
-
-### Features
-
-- Types: post / page / doc / changelog (any string)
-- Status: draft / published / archived
-- Slug: auto-generated, unique per type
-- Tags: many-to-many, auto-created
-- Tree: parent_id for hierarchy
-- Auth: non-admin users see published only
+```tsx
+const items = reactiveArray([1, 2, 3])
+items.push(4)        // [1, 2, 3, 4]
+items.pop()          // [1, 2, 3]
+items.remove(1)      // [1, 3]
+items.clear()        // []
+items.sort()
+items.reverse()
+```
 
----
+### Control Flow
 
-## base
+```tsx
+// Show — conditional rendering
+<Show when={isLoggedIn} fallback={<LoginPage />}>
+  <Dashboard />
+</Show>
 
-Dynamic data storage engine — let users define their own data structures (like Airtable).
+// For — keyed list rendering
+<For each={todos} keyBy="id">
+  {(todo) => <TodoItem todo={todo} />}
+</For>
 
-```ts
-import { base } from 'weifuwu'
+// Transition — animated enter/leave
+<Transition show={isOpen} name="fade">
+  <Modal />
+</Transition>
 
-app.use(postgres())
-app.use(user())
-app.use(base())
+// ErrorBoundary — catch render errors
+<ErrorBoundary fallback={(e) => <p>{e.message}</p>} onError={reportError}>
+  {() => <Dashboard />}
+</ErrorBoundary>
+```
 
-// Define schema
-app.post('/api/bases', async (req, ctx) => {
-  const b = await ctx.base.create(await req.json())
-  return Response.json(b, { status: 201 })
-})
+### Form Handling
 
-// CRUD
-app.post('/api/bases/:id/:table', async (req, ctx) => {
-  const row = await ctx.base.insert(ctx.params.id, ctx.params.table, await req.json())
-  return Response.json(row, { status: 201 })
+```tsx
+// useForm — validation + submit
+const form = useForm({
+  initial: { email: '', password: '' },
+  validate: { email: (v) => !v && '必填' },
+  validateOnInit: true,
 })
+<input {...form.field('email')} placeholder="邮箱" />
+<button onClick={() => form.submit(data => ctx.login(data))}>登录</button>
 
-app.get('/api/bases/:id/:table', async (req, ctx) => {
-  const url = new URL(req.url)
-  return Response.json(await ctx.base.query(ctx.params.id, ctx.params.table, {
-    filter: url.searchParams.get('filter') ? JSON.parse(url.searchParams.get('filter')!) : undefined,
-    limit: parseInt(url.searchParams.get('limit') || '50'),
-  }))
-})
+// useModel — two-way binding (shorter)
+const name = signal('')
+const agreed = signal(false)
+<input {...useModel(name)} placeholder="姓名" />
+<input type="checkbox" {...useModel(agreed)} /> 同意
 ```
 
-### ctx.base API
+### Async Data
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `create({ name, tables })` | `BaseDef` | Create database |
-| `defineTable(baseId, schema)` | `BaseDef` | Add table |
-| `updateTable(baseId, name, schema)` | `BaseDef \| null` | Update table |
-| `removeTable(baseId, name)` | `BaseDef \| null` | Remove table |
-| `insert(baseId, table, data)` | `Row` | Insert row |
-| `getRow(baseId, table, id)` | `Row \| null` | Get row |
-| `updateRow(baseId, table, id, data)` | `Row \| null` | Update row |
-| `deleteRow(baseId, table, id)` | `boolean` | Delete row |
-| `query(baseId, table, opts?)` | `Row[]` | Query (filter/sort/limit/offset) |
-| `search(baseId, table, field, query)` | `Row[]` | Full-text search |
-| `similaritySearch(baseId, table, field, vector)` | `Row[]` | Vector search |
-| `list()` / `get(id)` / `getBySlug(slug)` / `delete(id)` | — | Manage databases |
-
-### Architecture
-
-Fixed Slot: a single `base_data` table with ~120 physical columns:
+```tsx
+const [posts, { loading, error, refetch }] = createResource(
+  () => ctx.api.get('/api/posts'),
+  { retry: 2, timeout: 5000 },  // optional
+)
 
-| Type | Count | PG Type |
-|------|:-----:|:--------:|
-| text001..064 | 64 | TEXT |
-| number001..032 | 32 | DOUBLE PRECISION |
-| date001..008 | 8 | TIMESTAMPTZ |
-| vector001..004 | 4 | VECTOR(1536) |
-| search001..004 | 4 | TEXT |
-| ext | 1 | JSONB (overflow) |
+<Show when={loading}><Skeleton /></Show>
+<Show when={error}><Error /></Show>
+<For each={posts}>{(post) => <PostCard post={post} />}</For>
+```
 
-Field name → physical column mapping stored in `base_column_map`. Fields beyond the physical columns overflow to ext JSONB.
+### Scoped CSS
 
-pgvector auto-detected (included in docker image).
+```tsx
+const s = createStyles({
+  card: 'background: white; border-radius: 8px; padding: 16px;',
+  title: 'font-size: 18px; color: #333;',
+})
+<div class={s.card}><h2 class={s.title}>...</h2></div>
+```
 
----
+### Type-Safe Context
 
----
+```tsx
+const ThemeCtx = createContext<string>('theme')
+ThemeCtx.provide(ctx, 'dark')     // 提供
+const theme = ThemeCtx.inject(ctx) // string | null
+```
 
-## Router
+### Third-Party Integration
 
-```ts
-const app = new Router()
+```tsx
+const PieChart = wrap('div', (el, props, ctx) => {
+  const chart = echarts.init(el)
+  chart.setOption({ series: [{ type: 'pie', data: props.data }] })
+  effect(() => chart.setOption(...))
+  return () => chart.dispose()
+})
+<Dashboard><PieChart data={salesData} /></Dashboard>
+```
 
-// HTTP
-app.get(path, ...handlers)
-app.post / put / delete / patch / head / options(path, ...handlers)
-app.all(path, ...handlers)
+### Pre-built Components
 
-// WebSocket
-app.ws(path, ...middlewares, handler)
-// handler: { open?, message?, close?, error? }
+```tsx
+import { LoginForm, Chat, Link } from 'weifuwu/client'
 
-// Middleware & mounting
-app.use(middleware)
-app.mount(prefix, router)
-app.plugin(fn)
-app.onError(handler)
-app.routes()  // debug: list all routes
+<LoginForm />       // 登录/注册（自动切换模式）
+<Chat conversationId="123" />  // 实时消息聊天
+<Link to="/about">关于</Link>   // SPA 导航（支持右键新标签页）
 ```
 
----
+### Router
 
-## Middleware
+```tsx
+const routes: RouteDef[] = [
+  { path: '/', component: HomePage, title: 'Home' },
+  { path: '/post/:id', component: PostPage,
+    loader: async (ctx) => ({ post: await ctx.api.get(`/api/posts/${ctx.route.params.id}`) }),
+  },
+]
 
-```ts
-import { cors, helmet, compress, rateLimit, logger, upload, serveStatic, sandbox } from 'weifuwu'
+app.use(router({ routes, notFound: NotFound, mode: 'hash', transition: 'page' }))
+// ctx.route.path / .params / .query / .data / .loading
 
-app.use(cors({ origin: '*' }))
-app.use(helmet())
-app.use(compress())
-app.use(rateLimit({ max: 100 }))
-app.use(logger({ format: 'short' }))
-app.use(upload())
-app.use(serveStatic('./public'))
-app.use(sandbox({ baseDir: '/tmp/workspaces' }))
+// 路由出口
+function AppShell() { return <main><RouteView /></main> }
 ```
 
----
-
-## Postgres
+### DevTools
 
 ```ts
-import { postgres } from 'weifuwu'
-
-const sql = postgres()
-app.use(sql)  // → ctx.sql
+import { enableDevtools } from 'weifuwu/client'
+if (import.meta.env.DEV) enableDevtools()
 
-await sql.sql`SELECT * FROM users WHERE id = ${id}`
-await sql.sql.begin(async (sql) => { /* transaction */ })
+// 浏览器控制台：
+// __wefu__.inspect()     → 查看所有 signal
+// __wefu__.warnings()    → 切换开发警告
 ```
 
-Reads `DATABASE_URL` env. Supports migrations, transactions, connection pool stats.
-
 ---
 
-## Redis
+## From React to weifuwu/client
+
+| React | weifuwu/client |
+|-------|----------------|
+| `useState(0)` | `signal(0)` |
+| `useMemo(() => a * 2, [a])` | `computed(() => a.value * 2)` |
+| `useEffect(() => {...}, [])` | `effect(() => {...})` + `onCleanup(() => {...})` |
+| `{condition && <X/>}` | `<Show when={condition}><X/></Show>` |
+| `{items.map(i => <X/>)}` | `<For each={items}>{(i) => <X/>}</For>` |
+| `className={...}` | `class={...}` |
+| Context Provider | `ctx.provide(key, val)` / `createContext()` |
+| `useNavigate()` | `ctx.app.navigate(path)` |
+| `useParams()` | `ctx.route.params` |
+| `fetch / axios` | `ctx.api.get/post/...` |
+| WebSocket | `ctx.socket.send/onMessage` |
+
+**What you DON'T need:**
+- No hooks rules — no `use` prefix, no rules-of-hooks
+- No virtual DOM — JSX creates real DOM directly
+- No dependency arrays — `effect()` auto-tracks
+- No state management library — signal is the state management
+- No Context.Provider component — just `ctx.provide/inject`
 
-```ts
-import { redis } from 'weifuwu'
+---
 
-const r = redis()
-app.use(r)  // → ctx.redis
-await r.redis.set('key', 'value')
-```
+## Utils
 
-Reads `REDIS_URL` env (default: `redis://localhost:6379`).
+| Import | Purpose |
+|--------|---------|
+| `requireRole('admin')` | Middleware factory: check `ctx.user.role` |
+| `createHub()` | WebSocket pub/sub |
+| `HttpError` | `throw new HttpError(msg, 404)` |
+| `trace()` | Request tracing |
 
 ---
 
-## Queue & Cron
+## Router (Backend)
 
 ```ts
-import { queue } from 'weifuwu'
-
-const q = queue()
-app.use(q)  // → ctx.queue
-
-q.process('email', async (job) => { await sendEmail(job.payload) })
-q.cron('cleanup', '0 3 * * *', () => cleanup())
-await q.add('email', { to: 'user@example.com' })
-await q.add('remind', {}, { delay: 60_000 })
-q.run()
+const app = new Router()
+app.get(path, ...handlers)
+app.post / put / delete / patch / head / options(path, ...handlers)
+app.all(path, ...handlers)
+app.ws(path, ...handler)          // WebSocket
+app.use(middleware)                // Global middleware
+app.mount(prefix, router)         // Sub-router
+app.plugin(fn)                    // Plugin
+app.onError(handler)              // Error handler
+app.routes()                      // Debug: list all routes
 ```
 
 ---
@@ -943,49 +577,53 @@ q.run()
 
 ```
 src/
-├── index.ts             ← Entry, exports all modules
-├── types.ts             ← Context, Handler, Middleware types
-├── core/                ← serve, router, ws, trace, logger
+├── index.ts              ← Entry, exports all modules
+├── types.ts              ← Context, Handler, Middleware types
+├── core/                 ← serve, router, ws, trace, logger
 ├── middleware/           ← cors, helmet, compress, rate-limit, upload, static, sandbox
-├── user/                ← User system (CRUD, JWT, requireRole)
-├── messager/            ← IM + AI conversation layer
-├── kb/                  ← RAG knowledge base (chunking, embedding, vector search)
-├── ai/                  ← AI Agent (LLM, tools, RAG)
-├── cms/                 ← Content management (blog, docs, changelog)
-├── base/                ← Dynamic data engine (Fixed Slot)
-├── postgres/            ← PostgreSQL client
-├── redis/               ← Redis client
-├── queue/               ← Job queue + cron
-├── graphql.ts           ← GraphQL
-├── hub.ts               ← WebSocket hub
-├── ui/                  ← ctx.ui.html / ctx.ui.js / ctx.ui.css
-├── client/              ← Frontend framework
-│   ├── index.ts         ← Entry (exports signal, useForm, wrap, createApp, ...)
-│   ├── signal.ts        ← Signal / effect / computed
-│   ├── jsx-runtime.ts   ← JSX → DOM / Show / For / wrap / ErrorBoundary / createPortal
-│   ├── app.ts           ← createApp / hydrate / middleware chain
-│   ├── router.ts        ← Route matching / RouteView / loader
-│   ├── types.ts         ← WfuiContext / RouteDef
+├── user/                 ← User system (CRUD, JWT, requireRole)
+├── messager/             ← IM + AI conversation layer
+├── kb/                   ← RAG knowledge base
+├── ai/                   ← AI Agent (LLM, tools, RAG)
+├── cms/                  ← Content management
+├── base/                 ← Dynamic data engine
+├── postgres/             ← PostgreSQL client
+├── redis/                ← Redis client
+├── queue/                ← Job queue + cron
+├── graphql.ts            ← GraphQL
+├── hub.ts                ← WebSocket hub
+├── ui/                   ← ctx.ui.html / ctx.ui.js / ctx.ui.css
+├── client/               ← Frontend framework
+│   ├── index.ts          ← Exports all client APIs (33 exports)
+│   ├── signal.ts         ← Signal / effect / computed / batch / untrack
+│   ├── jsx-runtime.ts    ← JSX → DOM + types + Show/For/wrap/ErrorBoundary/Portal/Transition
+│   ├── app.ts            ← createApp / hydrate / middleware chain
+│   ├── router.ts         ← Route matching / RouteView / loader / transition
+│   ├── types.ts          ← WfuiContext / RouteDef / createContext
 │   ├── lib/
-│   │   └── form.ts     ← useForm
+│   │   ├── form.ts       ← useForm (validated forms)
+│   │   ├── model.ts      ← useModel (two-way binding)
+│   │   ├── resource.ts   ← createResource (async data)
+│   │   ├── css.ts        ← createStyles (scoped CSS)
+│   │   └── dev.ts        ← enableDevtools (dev warnings)
 │   ├── middleware/
-│   │   ├── api.ts       ← HTTP client
-│   │   ├── auth.ts      ← Login / logout / token
-│   │   └── ws.ts        ← WebSocket
+│   │   ├── api.ts        ← HTTP client → ctx.api
+│   │   ├── auth.ts       ← Auth → ctx.user/login/logout
+│   │   └── ws.ts         ← WebSocket → ctx.socket
 │   └── components/
-│       ├── LoginForm.ts ← Login / register form
-│       └── Chat.ts      ← Real-time messaging
-└── test/                ← Tests
-
-apps/demo/               ← Full-stack demo
+│       ├── LoginForm.tsx  ← Login/register
+│       ├── Chat.tsx       ← Real-time chat
+│       ├── Link.tsx       ← SPA navigation
+│       └── Transition.tsx ← Animated enter/leave
+└── test/                 ← 66 unit tests + 10 benchmarks
+
+apps/demo/                ← Full-stack demo
+├── server.ts             ← weifuwu server (user, kb, agent, messager 未演示)
 ├── src/main.tsx          ← SPA + SSR hydrate demo pages
-├── server.ts             ← weifuwu server
-├── public/
-│   ├── index.html        ← HTML skeleton with placeholders
-│   └── style.css         ← Demo styles
+├── public/               ← style.css (Tailwind + transition classes)
 └── tsconfig.json
 
-docker-compose.yml       ← postgres (pgvector) + redis
+docker-compose.yml        ← postgres (pgvector) + redis
 ```
 
 ---
@@ -996,5 +634,18 @@ docker-compose.yml       ← postgres (pgvector) + redis
 docker compose up -d         # Start postgres + redis
 npm run build                # esbuild → dist/
 npm run typecheck            # tsc --noEmit
-npm test                     # 281 tests
+npm test                     # Run all tests
 ```
+
+---
+
+## Performance (Client Benchmarks)
+
+| Operation | Throughput |
+|-----------|-----------|
+| Signal creation | ~10,000 ops/ms |
+| Signal read/write | ~9,600 ops/ms |
+| Notify 10,000 effects | ~2,600 ops/ms |
+| batch merge 10,000 writes | ~0.6ms |
+| JSX div creation | ~200 ops/ms |
+| For render 10,000 items | ~109 ops/ms |