weifuwu 0.23.4 → 0.24.1

package/README.md

@@ -27,6 +27,53 @@ npx weifuwu init my-app && cd my-app && npm run dev
 
 ## CLI
 
+### Typical Full App
+
+```ts
+import { serve, Router, postgres, session, user, aiProvider, ssr, flash, i18n, theme, logger, rateLimit } from 'weifuwu'
+
+const app = new Router()
+
+// 1. Observability (order matters — run early)
+app.use(logger())
+
+// 2. UX middleware — single-line auto-registers middleware + routes
+app.use(theme())
+app.use(i18n({ default: 'zh', dir: './locales' }))
+app.use(flash())
+
+// 3. Database
+const pg = postgres()
+app.use(pg)
+
+// 4. Session & Auth
+app.use(session({ store: 'redis', redis: myRedis }))
+const auth = user({ pg, jwtSecret: process.env.JWT_SECRET })
+await auth.migrate()
+app.use(auth)                // auto-registers middleware + /register, /login
+app.use('/auth', auth)       // explicit path mounts for more control
+
+// 5. API protection
+app.use('/api', rateLimit({ max: 60, window: 60_000 }))
+
+// 6. AI
+app.use(aiProvider())  // ctx.ai
+
+// 7. SSR
+app.use('/', ssr({ dir: './ui' }))
+
+// 8. REST API
+app.get('/api/ping', () => Response.json({ ok: true }))
+app.post('/api/chat', async (req, ctx) => {
+  const { prompt } = await req.json()
+  const result = await ctx.ai.generateText({ prompt })
+  return Response.json(result)
+})
+
+// 9. Start
+const server = serve(app.handler(), { port: 3000 })
+```
+
 ```bash
 npx weifuwu init my-app              # Full project (SSR + i18n + theme + WS demo)
 npx weifuwu init my-api --minimal    # Minimal HTTP project (2 files)
@@ -149,14 +196,13 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `query` | Router | `Record<string, string>` | URL query parameters |
 | `mountPath` | Router | `string` | Current sub-router mount prefix |
 | `env` | `loadEnv()` | `Record<string, string>` | Public env vars (`WEIFUWU_PUBLIC_*`) |
-| `csrfToken` | `csrf()` | `string` | CSRF token |
+| `csrf.token` | `csrf()` | `string` | CSRF token (namespace) |
 | `requestId` | `requestId()` | `string` | Request ID |
 | `session` | `session()` | `Session` | Session data object |
 | `sql` | `postgres()` | `Sql<{}>` | PostgreSQL tagged-template client |
 | `redis` | `redis()` | `Redis` | Redis client |
 | `ai` | `aiProvider()` | `AIProvider` | AI model & embedding |
 | `queue` | `queue()` | `Queue` | Job queue |
-| `session` | `session()` | `Session` | Session data object |
 | `user` | `auth()` / `user().middleware()` | `{ id?: string }` | Authenticated user |
 | `permissions` | `permissions()` | `{ roles, permissions }` | RBAC roles & permissions sets |
 | `theme` | `theme()` | `{ value, set }` | Current theme + switcher |
@@ -176,12 +222,12 @@ Middleware-injected properties are **automatically typed** through chained `use(
 
 ```ts
 const app = new Router()
-  .use(csrf())          // → Router<Context & { csrfToken: string }>
-  .use(requestId())     // → Router<Context & { csrfToken, requestId }>
-  .use(postgres())      // → Router<Context & { csrfToken, requestId, sql }>
+  .use(csrf())          // → Router<Context & { csrf: { token: string } }>
+  .use(requestId())     // → Router<Context & { csrf: ..., requestId }>
+  .use(postgres())      // → Router<Context & { csrf: ..., requestId, sql }>
 
 app.get('/me', (_req, ctx) => {
-  ctx.csrfToken   // ✅ string (IDE autocomplete)
+  ctx.csrf.token  // ✅ string (IDE autocomplete)
   ctx.requestId   // ✅ string
   ctx.sql`SELECT 1` // ✅ Sql<{}>
 })
@@ -193,12 +239,14 @@ Each module exports an `XxxInjected` type (e.g. `PostgresInjected`, `UserInjecte
 
 ## Module Patterns
 
-All modules follow one of **2 patterns** — learn these and you know every module.
+All modules follow one of **4 patterns** — learn these and you know every module.
 
 | Pattern | How to mount | Example |
 |---------|-------------|---------|
 | `[α]` | `app.use(mod())` | `compress()`, `theme()`, `postgres()` |
 | `[β]` | `app.use('/path', mod())` | `health()`, `ssr({dir})`, `graphql(handler)`, `user()` |
+| `[γ]` | Import and call directly | `mailer()`, `fts`, `cron-utils` |
+| `[δ]` | `import { useXxx } from 'weifuwu/react'` | `useTheme()`, `useLocale()`, `useWebsocket()` |
 
 ### Pattern α — Middleware
 
@@ -206,7 +254,7 @@ All modules follow one of **2 patterns** — learn these and you know every modu
 app.use(compress())           // basic
 const pg = postgres()         // with extras: .sql, .table, .migrate(), .close()
 app.use(pg)
-app.use(rateLimit({ max: 100 }))  // with .stop()
+app.use(rateLimit({ max: 100 }))  // with .close()
 ```
 
 ### Pattern β — Router
@@ -219,15 +267,136 @@ app.use('/auth', user({ pg, jwtSecret }))                       // with .middlew
 app.ws('/ws', messager({ pg }).wsHandler())
 ```
 
-β modules that need **separate middleware** use `.middleware()`:
+β modules that need **separate middleware** use `.middleware()`. Most can auto-register both middleware and routes in one call:
 ```ts
+app.use(theme())           // auto: middleware + /__theme/:value
+app.use(i18n({ dir: './locales' }))  // auto: middleware + /__lang/:locale
+app.use(analytics({ pg })) // auto: middleware + /__analytics
+app.use(auth)              // auto: middleware + /register, /login (user())
+
+// Explicit form when more control is needed:
 const a = analytics()
-app.use(a.middleware())   // tracking
-app.use('/', a)           // dashboard
+app.use(a.middleware())   // tracking only
+app.use('/', a)           // dashboard at custom path
+```
+
+### Pattern γ — Standalone
+
+Modules that don't intercept requests or serve routes. Import and use directly.
+
+```ts
+import { mailer, cronNext, fts } from 'weifuwu'
+
+const email = mailer({ transport: 'smtp://...', from: 'noreply@example.com' })
+await email.send({ to: 'user@test.com', subject: 'Hello', text: 'Body' })
+
+const next = cronNext('0 9 * * 1-5')  // next weekday at 09:00
+```
+
+### Pattern δ — Client-side
+
+React hooks that self-register via `addInterceptor()`. Import to enable.
+
+```tsx
+import { useTheme, useLocale, useWebsocket } from 'weifuwu/react'
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme()
+  return <button onClick={() => setTheme('dark')}>Dark</button>
+}
 ```
 
 ---
 
+## Module Dependency Map
+
+```mermaid
+graph TD
+    serve --> Router
+    Router --> postgres
+    Router --> redis
+    Router --> aiProvider
+
+    subgraph "DB-Dependent Modules"
+        user --> postgres
+        session --> postgres
+        session -.-> redis
+        queue --> postgres
+        queue -.-> redis
+        permissions --> postgres
+        analytics --> postgres
+        logdb --> postgres
+        tenant --> postgres
+        messager --> postgres
+        messager -.-> redis
+        agent --> postgres
+        kb --> postgres
+        iii --> postgres
+        iii -.-> redis
+    end
+
+    subgraph "AI-Dependent Modules"
+        agent --> aiProvider
+        kb --> aiProvider
+        aiStream --> aiProvider
+        opencode --> aiProvider
+        runWorkflow --> aiProvider
+    end
+```
+
+## Quick Module Selection
+
+| What do you want to do? | Module | Pattern |
+|------------------------|--------|---------|
+| **User registration / login** | `user()` | β |
+| **Simple token/header auth** | `auth()` | α |
+| **JWT verification** | `user().middleware()` | α |
+| **Role-based access control** | `permissions()` | α |
+| **AI chat / generate / stream** | `ctx.ai.generateText()` / `ctx.ai.streamText()` | α (via `aiProvider()`) |
+| **AI agent with knowledge** | `agent()` + `knowledgeBase()` | β |
+| **Send email** | `mailer()` | γ |
+| **File upload** | `upload()` | α |
+| **Object storage (S3/MinIO)** | `s3()` | α |
+| **Rate limiting** | `rateLimit()` | α |
+| **Response caching** | `cache()` | α |
+| **Periodic / delayed jobs** | `queue()` | α |
+| **Page view analytics** | `analytics()` | β |
+| **Structured logging** | `logdb()` | β |
+| **Real-time chat / messager** | `messager()` | β |
+| **Full-text search** | `fts` | γ |
+| **Theme switching** | `theme()` | α |
+| **i18n / localization** | `i18n()` | α |
+| **Flash messages** | `flash()` | α |
+| **Server-Sent Events** | `createSSEStream()` | γ |
+| **GraphQL endpoint** | `graphql()` | β |
+| **Webhook receiver** | `webhook()` | β |
+| **SSR with React** | `ssr()` | β |
+| **Health check** | `health()` | β |
+| **SEO (robots.txt, sitemap)** | `seo()` | β |
+| **Multi-process deploy** | `deploy()` | γ |
+| **Distributed functions (iii)** | `iii()` | β |
+| **Multi-tenant BaaS** | `tenant()` | β |
+| **Client-side routing** | `useNavigate()`, `<Link>` | δ |
+| **WebSocket in React** | `useWebsocket()` | δ |
+| **Compression (brotli/gzip)** | `compress()` | α |
+| **Security headers (CSP, HSTS)** | `helmet()` | α |
+| **CORS** | `cors()` | α |
+| **CSRF protection** | `csrf()` | α |
+| **Request ID tracing** | `requestId()` | α |
+| **Environment variables** | `env()` / `loadEnv()` | α |
+| **Static file serving** | `serveStatic()` | α |
+| **Object storage (S3/MinIO)** | `s3()` | α |
+| **Send email** | `mailer()` | γ |
+| **Scheduled / cron tasks** | `cron-utils` (`cronNext()`) | γ |
+| **Server-Sent Events** | `createSSEStream()` | γ |
+| **Multi-process deploy** | `deploy()` | γ |
+| **Distributed functions (iii)** | `iii()` | β |
+| **Webhook receiver** | `webhook()` | β |
+| **Social login (OAuth)** | `user({ oauthLogin })` | β |
+| **Database migrations** | `pg.migrate()` | — |
+
+---
+
 ## Request Tracing & Logging
 
 Every request gets a **trace ID** via `AsyncLocalStorage`, injected into responses as `X-Trace-Id`. W3C `traceparent` headers are forwarded.
@@ -347,7 +516,13 @@ Uses `TEST_DATABASE_URL` or `DATABASE_URL`. Automatically skipped in CI if unset
 
 ## Module Reference
 
-### agent [β]
+Modules are organized alphabetically. Each module shows its pattern badge (`[α]` Middleware, `[β]` Router, `[γ]` Standalone, `[δ]` Client-side) and category.
+
+**Category key:** AI, API, Clientδ, Database, DevTools, Networking, Security, SSR, UX
+
+---
+
+### agent [β] [AI]
 
 ```ts
 const provider = aiProvider()
@@ -374,7 +549,7 @@ a.run(agentId, { input: 'summarize the data', stream: true })
 | `.migrate()` | DB setup |
 | `.close()` | Cleanup |
 
-### aiStream [β]
+### aiStream [β] [AI]
 
 Creates an AI streaming chat endpoint using the Vercel AI SDK.
 
@@ -389,7 +564,7 @@ app.use('/chat', chat)
 | `handler` | `(req, ctx) => AIStreamOptions \| Promise<AIStreamOptions>` | Returns AI SDK options (model, messages, schema, etc.) |
 | `provider` | `AIProvider` | Optional. If provided and handler omits `model`, `provider.model()` is used as default |
 
-### analytics [β]
+### analytics [β] [API]
 
 In-memory or PostgreSQL page view tracking with built-in dashboard.
 
@@ -412,7 +587,7 @@ app.use(a.middleware())
 app.use('/', a)            // dashboard routes
 ```
 
-### auth [α]
+### auth [α] [Security]
 
 ```ts
 app.use(auth({ token: 'sk-123' }))                              // static token
@@ -445,7 +620,7 @@ Authorization header. This lets logged-in users authenticate via their
 session cookie without sending a token. Falls back to header/token auth
 if no session userId is present.
 
-### compress [α]
+### compress [α] [DevTools]
 
 ```ts
 app.use(compress())                         // brotli > gzip > deflate (min 1KB)
@@ -457,7 +632,7 @@ app.use(compress({ threshold: 2048, level: 4 }))      // custom threshold and le
 | `threshold` | `number` | `1024` | Minimum byte size to compress |
 | `level` | `number` | `6` | Compression level (zlib) |
 
-### cors [α]
+### cors [α] [DevTools]
 
 ```ts
 app.use(cors())                                            // allow all
@@ -475,7 +650,7 @@ app.use(cors({ credentials: true, maxAge: 3600 }))
 | `credentials` | `boolean` | `false` | Allow cookies/credentials |
 | `maxAge` | `number` | — | Preflight cache duration (seconds) |
 
-### flash [α]
+### flash [α] [UX]
 
 Cookie-based flash message. Read from request, write via redirect.
 
@@ -495,7 +670,7 @@ app.post('/save', (req, ctx) => {
 |--------|------|---------|-------------|
 | `name` | `string` | `'flash'` | Cookie name |
 
-### cache [α]
+### cache [α] [DevTools]
 
 Response caching middleware with memory and Redis stores. Caches GET/HEAD responses, with tag-based invalidation.
 
@@ -535,11 +710,11 @@ await mem.set('key', { status: 200, statusText: 'OK', headers: {}, body: '...',
 mem.close()
 ```
 
-### csrf [α]
+### csrf [α] [Security]
 
 ```ts
 app.use(csrf())
-// ctx.csrfToken — set on GET/HEAD/OPTIONS
+// ctx.csrf.token — set on GET/HEAD/OPTIONS
 // Auto-validates x-csrf-token or x-xsrf-token header on POST/PUT/DELETE/PATCH
 // Falls back to body field matching the key name
 ```
@@ -551,7 +726,7 @@ app.use(csrf())
 | `key` | `'_csrf'` | Body field fallback |
 | `excludeMethods` | `['GET','HEAD','OPTIONS']` | Skip validation |
 
-### deploy [β]
+### deploy [β] [Networking]
 
 Multi-process manager with reverse proxy, health checks, auto-restart, and zero-downtime updates. Works identically locally and in production.
 
@@ -657,9 +832,42 @@ Restart=always
 | `buildCommand` | — | Build command |
 | `ports` | — | `[port, port+1]` for blue-green |
 
+### env [α] [DevTools]
 
+Environment variable middleware. Injects `ctx.env` with all `WEIFUWU_PUBLIC_*` variables (prefix stripped).
+Safe to expose to the client.
 
-### graphql [β]
+```ts
+import { env, loadEnv } from 'weifuwu'
+loadEnv()                                // Load .env into process.env
+app.use(env())                           // → ctx.env
+
+app.get('/config', (req, ctx) => {
+  return Response.json({ apiUrl: ctx.env.API_URL })
+})
+```
+
+Helper utilities:
+
+```ts
+import { isDev, isProd, isBundled, getPublicEnv } from 'weifuwu'
+
+isDev()      // NODE_ENV === 'development'
+isProd()     // NODE_ENV === 'production'
+isBundled()  // Running from compiled dist/index.js?
+getPublicEnv()  // { API_URL: '...' } — no middleware needed
+```
+
+| Function | Description |
+|----------|-------------|
+| `loadEnv(path?)` | Load `.env` file into `process.env` (does not override existing) |
+| `env()` | Middleware — injects `ctx.env` with public vars |
+| `getPublicEnv()` | Returns `WEIFUWU_PUBLIC_*` vars with prefix stripped |
+| `isDev()` | `true` when `NODE_ENV === 'development'` |
+| `isProd()` | `true` when `NODE_ENV === 'production'` |
+| `isBundled()` | `true` when running from compiled bundle |
+
+### graphql [β] [API]
 
 ```ts
 const handler: GraphQLHandler = () => ({
@@ -682,7 +890,7 @@ app.use('/graphql', graphql(handler))
 | `maxDepth` | `number` | `10` | Max query nesting depth |
 | `timeout` | `number` | `30_000` | Execution timeout (ms) |
 
-### health [β]
+### health [β] [API]
 
 ```ts
 app.use('/health', health())
@@ -694,7 +902,7 @@ app.use('/health', health())
 | `path` | `string` | `'/health'` | Health check endpoint |
 | `check` | `() => Promise<void>` | — | Async function; throws → 503 |
 
-### helmet [α]
+### helmet [α] [Security]
 
 15 security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
 
@@ -715,7 +923,7 @@ app.use(helmet({ contentSecurityPolicy: "default-src 'self'", xFrameOptions: 'DE
 | `crossOriginOpenerPolicy` | — | COOP header |
 | `crossOriginResourcePolicy` | — | CORP header |
 
-### iii [β] — Worker / Function / Trigger
+### iii [β] — Worker / Function / Trigger [API]
 
 Distributed function execution with WebSocket workers, triggers, and Redis streams.
 
@@ -751,7 +959,7 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 
 
 
-### knowledgeBase [β] — RAG with pgvector
+### knowledgeBase [β] — RAG with pgvector [AI]
 
 ```ts
 import { knowledgeBase, aiProvider } from 'weifuwu'
@@ -805,7 +1013,7 @@ replaces old chunks. Provider's `embed()` is used automatically.
 The HNSW index enables fast approximate nearest-neighbor search (cosine distance).
 
 
-### logdb [β]
+### logdb [β] [API]
 
 PostgreSQL structured event logging with monthly partitioning.
 
@@ -828,7 +1036,7 @@ await logger.log({ level: 'info', source: 'app', message: 'hello', metadata: { u
 | GET | `/` | Query (`?level=`, `?source=`, `?after=`, `?before=`, `?meta.*=`) |
 | GET | `/:id` | Get single entry |
 
-### logger [α]
+### logger [α] [DevTools]
 
 ```ts
 app.use(logger())                             // GET /hello 200 5ms
@@ -837,9 +1045,9 @@ app.use(logger({ format: 'combined' }))       // with query params
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `format` | `'short' \| 'combined'` | `'short'` | Log format: path only, or path + query params |
+| `format` | `'short' \| 'combined' \| 'json'` | `'short'` | Log format: path only, path + query params, or JSON to stderr |
 
-### mailer
+### mailer [γ] [Networking]
 
 ```ts
 const mail = mailer({ from: 'noreply@example.com', transport: 'smtp://user:pass@smtp.example.com:587' })
@@ -854,28 +1062,31 @@ await mail.send({ to: 'user@test.com', subject: 'Hello', text: 'Body', html: '<p
 
 
 
-### oauthClient [β] — Social login (OAuth 2.0 client)
+### oauthLogin (via user()) — Social login (OAuth 2.0 client) [Security]
 
-```ts
-import { oauthClient } from 'weifuwu'
+Social login is built into the [`user()`](#user-β) module via the `oauthLogin` option — no separate import needed.
 
+```ts
 app.use(session())                       // required — stores OAuth state
-app.use(user({ pg, jwtSecret }))         // required — user management
-app.use('/auth', oauthClient({           // mounts /auth/google, /auth/google/callback
+const u = user({
   pg,
-  jwtSecret,
-  redirectUrl: '/dashboard',
-  providers: {
-    google: {
-      clientId: process.env.GOOGLE_CLIENT_ID,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-    },
-    github: {
-      clientId: process.env.GITHUB_CLIENT_ID,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+  jwtSecret: process.env.JWT_SECRET!,
+  oauthLogin: {
+    redirectUrl: '/dashboard',
+    providers: {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      },
+      github: {
+        clientId: process.env.GITHUB_CLIENT_ID,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      },
     },
   },
-}))
+})
+await u.migrate()
+app.use(u)   // POST /register, POST /login, GET /auth/:provider, GET /auth/:provider/callback
 ```
 
 **Flow:** User clicks "Login with Google" → redirected to Google → back to app → user created/linked in database → JWT signed → session created → redirected to `redirectUrl` with `?token=` (or JSON response for API clients).
@@ -883,42 +1094,40 @@ app.use('/auth', oauthClient({           // mounts /auth/google, /auth/google/ca
 Supports custom providers via `authUrl`, `tokenUrl`, `userUrl`, and `parseUser`:
 
 ```ts
-app.use('/auth', oauthClient({
+const u = user({
   pg,
-  jwtSecret,
-  providers: {
-    discord: {
-      clientId: process.env.DISCORD_CLIENT_ID,
-      clientSecret: process.env.DISCORD_CLIENT_SECRET,
-      authUrl: 'https://discord.com/api/oauth2/authorize',
-      tokenUrl: 'https://discord.com/api/oauth2/token',
-      userUrl: 'https://discord.com/api/users/@me',
-      parseUser: (data) => ({
-        id: data.id,
-        email: data.email ?? '',
-        name: data.global_name ?? data.username,
-        avatarUrl: data.avatar
-          ? `https://cdn.discordapp.com/avatars/${data.id}/${data.avatar}.png`
-          : '',
-      }),
+  jwtSecret: process.env.JWT_SECRET!,
+  oauthLogin: {
+    providers: {
+      discord: {
+        clientId: process.env.DISCORD_CLIENT_ID,
+        clientSecret: process.env.DISCORD_CLIENT_SECRET,
+        authUrl: 'https://discord.com/api/oauth2/authorize',
+        tokenUrl: 'https://discord.com/api/oauth2/token',
+        userUrl: 'https://discord.com/api/users/@me',
+        parseUser: (data) => ({
+          id: data.id,
+          email: data.email ?? '',
+          name: data.global_name ?? data.username,
+          avatarUrl: data.avatar
+            ? `https://cdn.discordapp.com/avatars/${data.id}/${data.avatar}.png`
+            : '',
+        }),
+      },
     },
   },
-}))
+})
 ```
 
-| Option | Type | Default | Description |
+| Option (oauthLogin) | Type | Default | Description |
 |--------|------|---------|-------------|
-| `pg` | `PostgresClient` | — | **Required.** Database connection |
-| `jwtSecret` | `string` | — | **Required.** Must match `user()` module's secret |
 | `providers` | `Record<string, OAuthProviderConfig>` | — | **Required.** Provider configs (Google/GitHub built-in, any custom) |
 | `redirectUrl` | `string` | `'/'` | Post-login redirect destination |
-| `expiresIn` | `string \| number` | `'24h'` | JWT expiry |
-| `table` | `string` | `'_auth_providers'` | Provider-user link table name |
 
-The module auto-creates a `_auth_providers` table (`user_id`, `provider`, `provider_id`, `email`, `name`, `avatar_url`) on first request. Built-in providers (Google, GitHub) have preset URLs — you only need to provide `clientId` and `clientSecret`.
+Built-in providers (Google, GitHub) have preset URLs — you only need to provide `clientId` and `clientSecret`. The module auto-creates a `_auth_providers` table on first request.
 
 
-### messager [β]
+### messager [β] [Networking]
 
 Real-time chat with channels, WebSocket, agent routing.
 
@@ -945,7 +1154,7 @@ await msg.send(channelId, 'System message', { sender_type: 'system', sender_id:
 
 
 
-### opencode [β]
+### opencode [β] [AI]
 
 AI programming assistant.
 
@@ -972,7 +1181,7 @@ app.ws('/opencode', oc.wsHandler())
 | `skills` | `object[]` | — | Custom skill definitions |
 | `permissions` | `object` | — | Tool permission rules |
 
-### postgres [α]
+### postgres [α] [Database]
 
 Type-safe PostgreSQL client with schema builder, CRUD, migrations, soft delete, and JSONB/vector support.
 
@@ -1112,7 +1321,7 @@ class MyModule extends PgModule {
 
 Where helpers + `and`/`or`/`not` can be imported from `'weifuwu'` alongside `postgres`. Full column builders and table helpers are in the same barrel.
 
-### cron-utils
+### cron-utils [γ] [DevTools]
 
 Shared cron expression parsing utilities. All functions operate in **local timezone**.
 
@@ -1130,7 +1339,7 @@ console.log(new Date(next))
 | `matches(fields, date)` | Check if a date matches a parsed pattern |
 | `cronNext(expr, from?)` | Calculate next matching timestamp (`from` defaults to now) |
 
-### fts — Full-Text Search (PostgreSQL)
+### fts — Full-Text Search (PostgreSQL) [Database]
 
 Utilities for PostgreSQL full-text search: create GIN indexes, search with ranking, and generate highlighted snippets.
 
@@ -1166,16 +1375,20 @@ await fts.dropIndex(pg.sql, articles)
 
 Search options: `fields`, `limit` (20), `offset` (0), `headline` (false), `language` ('english'), `minRank`.
 
-### theme [α]
+### theme [α] [UX]
 
 ```ts
+// Single line — auto-registers middleware + /__theme/:value route
 app.use(theme({ default: 'dark' }))
-// → ctx.theme = { value: 'dark', set: fn }
-// → ctx.theme.value — 'dark'
-// → ctx.theme.set('light', '/settings') — 302 + Set-Cookie
 
-// Client-side switching (interceptor auto-handles /__theme/:value)
-// → GET /__theme/dark — 302 + Set-Cookie
+// ctx.theme = { value: 'dark', set: fn }
+// ctx.theme.value — 'dark'
+// ctx.theme.set('light', '/settings') — 302 + Set-Cookie
+
+// Explicit form for more control:
+// const t = theme()
+// app.use(t.middleware())
+// app.use('/', t)
 ```
 
 | Option | Type | Default | Description |
@@ -1193,15 +1406,21 @@ app.post('/settings', async (req, ctx) => {
 
 See [`useTheme()`](#usetheme) for client-side usage.
 
-### i18n [α]
+### i18n [α] [UX]
 
 ```ts
+// Single line — auto-registers middleware + /__lang/:locale route
 app.use(i18n({ default: 'zh', dir: './locales' }))
-// → ctx.i18n = { locale: 'zh', t: (key) => string, set: (locale) => Response }
-// → ctx.i18n.t('welcome') → '欢迎'
-// → ctx.i18n.locale → 'zh'
-// → ctx.i18n.set('en', '/settings') — 302 + Set-Cookie
-// → GET /__lang/en — switch locale (client-side interceptor)
+
+// ctx.i18n = { locale: 'zh', t, set }
+// ctx.i18n.t('welcome') → '欢迎'
+// ctx.i18n.locale → 'zh'
+// ctx.i18n.set('en', '/settings') — 302 + Set-Cookie
+
+// Explicit form for more control:
+// const l = i18n()
+// app.use(l.middleware())
+// app.use('/', l)
 ```
 
 | Option | Type | Default | Description |
@@ -1222,7 +1441,7 @@ app.get('/greet', async (req, ctx) => {
 
 **Client-side:** import `useLocale` from `weifuwu/react`, `useTheme` from `weifuwu/react`.
 
-### queue [α]
+### queue [α] [Database]
 
 Async job queue. Supports immediate, delayed, and recurring (cron) tasks with three backends:
 
@@ -1300,7 +1519,7 @@ Supported cron syntax: `*` (any), `*/n` (every n), `n-m` (range), `n,m,o` (list)
 | POST | `/:type/retry` | Retry all failed jobs of a type |
 | POST | `/retry/:id` | Retry a specific failed job by ID |
 
-### rateLimit [α]
+### rateLimit [α] [Security]
 
 ```ts
 app.use(rateLimit({ max: 100, window: 60_000 }))            // 100 req/min, in-memory
@@ -1326,7 +1545,7 @@ app.use(rateLimit({ max: 100, store: 'redis', redis: ctx.redis }))
 
 Redis mode uses `INCR` + `EXPIRE` for atomic counting, enabling accurate rate limiting across multiple server processes. Memory mode is ideal for single-process deployments.
 
-### redis [α]
+### redis [α] [Database]
 
 ```ts
 const r = redis()          // reads REDIS_URL
@@ -1340,7 +1559,7 @@ await ctx.redis.set('key', 'value')
 | `url` | `string` | `REDIS_URL` env | Redis connection string |
 | (all ioredis options) | — | — | Passed directly to ioredis |
 
-### requestId [α]
+### requestId [α] [DevTools]
 
 ```ts
 app.use(requestId())
@@ -1353,16 +1572,35 @@ app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID()
 | `header` | `string` | `'X-Request-ID'` | Header name to read/write |
 | `generator` | `() => string` | `crypto.randomUUID()` | ID generator |
 
-### trace
+### trace [α] [DevTools]
+
+Request-scoped tracing via `AsyncLocalStorage`. Use as middleware to inject `ctx.trace`:
+
+```ts
+import { trace } from 'weifuwu'
+app.use(trace())                             // → ctx.trace
+app.use(trace({ header: 'X-Trace-Id' }))     // custom header
+
+app.get('/', (req, ctx) => {
+  console.log(ctx.trace.requestId)  // 550e8400-e29b-...
+  console.log(ctx.trace.traceId)    // trace UUID
+  console.log(ctx.trace.elapsed())  // ms since request start
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `header` | `string` | `'X-Request-ID'` | Request ID header name |
+| `generator` | `() => string` | `crypto.randomUUID()` | Custom ID generator |
 
-Request-scoped tracing via `AsyncLocalStorage`. Used internally by `serve()`.
+Utility functions (also available standalone):
 
 ```ts
-import { currentTraceId, runWithTrace, traceElapsed } from 'weifuwu'
+import { currentTraceId, runWithTrace, traceElapsed, currentTrace } from 'weifuwu'
 
-// Inside a middleware or handler
 const traceId = currentTraceId()  // UUID or incoming X-Trace-Id
 const elapsed = traceElapsed()    // ms since request started
+runWithTrace(incomingId, () => { ... })  // manual scope
 ```
 
 | Function | Description |
@@ -1372,7 +1610,7 @@ const elapsed = traceElapsed()    // ms since request started
 | `traceElapsed()` | Milliseconds elapsed since the trace started |
 | `runWithTrace(traceId, fn)` | Execute `fn` inside a trace scope |
 
-### s3 [α] — S3-compatible object storage
+### s3 [α] — S3-compatible object storage [Networking]
 
 ```ts
 import { s3 } from 'weifuwu'
@@ -1451,7 +1689,7 @@ minio:
 ```
 
 
-### seo [β] + seoMiddleware [α]
+### seo [β] + seoMiddleware [α] [API]
 
 ```ts
 app.use('/', seo({ baseUrl: 'https://example.com', robots: [{ userAgent: '*', allow: '/' }], sitemap: { urls: [{ loc: '/' }] } }))
@@ -1469,7 +1707,7 @@ Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML st
 | `sitemap` | `SitemapConfig` | — | Sitemap configuration (urls, resolve, cacheTTL) |
 | `headers` | `SeoHeadersConfig` | — | Response headers (e.g. `X-Robots-Tag`) |
 
-### session [α]
+### session [α] [Security]
 
 Cookie-based server-side session management with memory and Redis stores.
 
@@ -1531,7 +1769,7 @@ const redis = new RedisStore(redisClient, 'myapp:session:')
 await redis.destroy('sid')
 ```
 
-### ssr({ dir }) [β]
+### ssr({ dir }) [β] [SSR]
 
 One-stop Server-Side Rendering. Accepts a directory and returns a Router that handles all SSR routes, tailwind CSS, hydration, and livereload — using Next.js-style file conventions.
 
@@ -1580,7 +1818,7 @@ app.use('/', ssr({ dir: './ui' }))
 - The vendor bundle (react + react-dom + weifuwu client libs) is compiled once and cached
 - Page components are pre-compiled to `/__ssr/{hash}.js` — no runtime esbuild after first request
 - **Dev:** `createRoot` + render; **Production:** `hydrateRoot` (reuses SSR DOM)
-- Both the hydration script and the page component share the same store via `globalThis.__WEIFUWU_CTX_STORE`
+- The hydration script and page component share the same SSR context store — data flows seamlessly from server to client
 - Tailwind CSS served at `/__wfw/style/{hash}.css` (cached, content-hashed)
 - Dev mode extras: HMR WebSocket, file watcher, hot component replacement
 
@@ -1595,7 +1833,7 @@ app.get('/api/ping', () => Response.json({ pong: true }))
 
 Layout components receive `{ children }` and wrap from outer to inner:
 
-### tenant [β]
+### tenant [β] [Networking]
 
 Multi-tenant BaaS with dynamic table API and GraphQL.
 
@@ -1612,7 +1850,7 @@ app.use('/graphql', t.graphql()) // dynamic GraphQL
 | `pg` | `object` | — | PostgreSQL client |
 | `usersTable` | `string` | — | Users table name for tenant membership lookup |
 
-### upload [α]
+### upload [α] [DevTools]
 
 ```ts
 app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760, allowedTypes: ['image/jpeg', 'image/png'] }), (req, ctx) => {
@@ -1628,7 +1866,7 @@ app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760, allowedT
 | `maxFileSize` | `number` | — | Max bytes per file |
 | `allowedTypes` | `string[]` | — | Allowed MIME types |
 
-### user [β]
+### user [β] [Security]
 
 Authentication: register, login, JWT, OAuth2 服务端, 社会化登录.
 
@@ -1665,7 +1903,7 @@ app.use(u.middleware())                  // ctx.user
 | `.verify(token)` | Verify JWT token |
 | `.middleware()` | JWT verify middleware — sets `ctx.user` |
 
-### permissions [α] — RBAC
+### permissions [α] — RBAC [Security]
 
 Role-based access control.
 
@@ -1713,7 +1951,7 @@ app.get('/posts/:id', async (req, ctx) => {
 | `.requirePermission(...perms)` | Middleware — rejects if user lacks any permission |
 | `.migrate()` | Create tables |
 
-### validate [α]
+### validate [α] [DevTools]
 
 ```ts
 import { z } from 'zod'
@@ -1747,7 +1985,7 @@ app.post('/contact', validate({ body: z.object({ email: z.string().email() }) })
 | `params` | `ZodSchema` | — | URL params validation schema |
 | `headers` | `ZodSchema` | — | Header validation schema |
 
-### webhook [β]
+### webhook [β] [API]
 
 Webhook receiver with built-in signature verification for Stripe, GitHub, and Slack. Event-based dispatch with replay protection.
 
@@ -1786,21 +2024,22 @@ wh.on('*', (event) => {
 
 Built-in verifiers handle HMAC-SHA256, timestamp validation (Slack's 5-min window), and Stripe's `t=` / `v1=` signature format. Slack URL verification challenges are auto-responded.
 
-### Client-side navigation
+### Client-side navigation [δ] [Client]
 
 ```tsx
-import { Link, useNavigate, useNavigating } from 'weifuwu/react'
+import { Link, navigate, useNavigate, useNavigating } from 'weifuwu/react'
 
 <Link href="/about" prefetch>About</Link>   // client-side nav + prefetch on hover/visible
-const navigate = useNavigate()               // programmatic: navigate('/contact')
+const n = useNavigate()                      // hook: n('/contact')
+navigate('/contact')                         // bare function (no hook needed)
 const loading = useNavigating()              // reactive loading state
 ```
 
-`navigate()` fetches SSR, extracts `__weifuwu_root`, replaces in-place. Middleware runs on server each nav — data is always fresh.
+`navigate()` fetches the SSR page, extracts the root container content, and replaces it in-place. Middleware runs on server each nav — data is always fresh.
 
 **Preference URLs** (`/__lang/`, `/__theme/`) are intercepted by modular interceptors registered via `addInterceptor()` — no page reload needed. Importing `useLocale` or `useTheme` registers the interceptor automatically.
 
-### Client-side hooks
+### Client-side hooks [δ] [Client]
 
 ```tsx
 import { useWebsocket, useAction, useFetch, useQueryState, createStore, Head } from 'weifuwu/react'
@@ -1840,7 +2079,7 @@ const count = useStore(s => s.count)
 
 **`TsxContext`** — React context holding page data (`params`, `query`, `user`, `parsed`, `theme`, `i18n`, `flash`, `loaderData`, `env`). Used internally by hooks; rarely needed directly.
 
-### Locale & Theme
+### Locale & Theme [δ] [Client]
 
 ```tsx
 import { useLocale } from 'weifuwu/react'
@@ -1891,7 +2130,7 @@ function Page() {
 }
 ```
 
-On the server, data flows from middleware → `ctx` → `setCtx(ctxValue)` (serialized via JSON). On the client, the hydration script calls `setCtx(ctxData)` which populates the shared store (`globalThis.__WEIFUWU_CTX_STORE`). `useLoaderData()` reads from the snapshot via `useSyncExternalStore` — no SSR-specific code needed in your components.
+On the server, data flows from middleware → `ctx` → `setCtx(ctxValue)` (serialized via JSON). On the client, the hydration script calls `setCtx(ctxData)` which populates the shared context store. `useLoaderData()` reads from the snapshot via `useSyncExternalStore` — no SSR-specific code needed in your components.
 
 **`addInterceptor(fn)`** — Register a URL interceptor. Interceptors run before SPA navigation; if one returns `true`, `navigate()` skips the fetch-and-swap.
 
@@ -1904,7 +2143,7 @@ addInterceptor(async (url) => {
 })
 ```
 
-### Flash messages
+### Flash messages [δ] [Client]
 
 ```ts
 import { flash } from 'weifuwu'
@@ -1939,13 +2178,13 @@ function Toast() {
 |--------|------|---------|-------------|
 | `name` | `string` | `'flash'` | Cookie name |
 
-### Dev mode
+### Dev mode [δ] [Client]
 
 Auto-detected when `NODE_ENV === 'development'`. `ssr({dir})` automatically registers importmap, vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
 
 - Inline hydration script uses `createRoot` + render (replaces SSR DOM)
 - Vendor bundle served at `/__wfw/v/bundle?h=<hash>` — compiled from source, unminified
-- Hot component replacement: file changes → WebSocket message → browser imports hot bundle → `__WFW_REFRESH(NewComponent)` — `useState` values preserved
+- Hot component replacement: file changes → WebSocket message → browser imports hot bundle → component refreshed in place — `useState` values preserved
 - Tailwind CSS hot-reloads without page refresh
 - Layout changes trigger a full page reload
 
@@ -1962,7 +2201,7 @@ const provider = aiProvider()
 
 For AI streaming endpoints see [`aiStream`](#aistream-β). For AI agent APIs see [`agent`](#agent-β).
 
-### aiProvider [α] — AI model & embedding configuration
+### aiProvider [α] — AI model & embedding configuration [AI]
 
 ```ts
 const provider = aiProvider()                 // auto from env
@@ -1995,7 +2234,7 @@ app.post('/ask', async (req, ctx) => {
 | `.streamText(params)` | Stream text (model auto-injected) |
 | `.dimension` | Configured embedding dimension |
 
-### DAG Workflow
+### DAG Workflow [AI]
 
 ```ts
 const tools = { queryUser: tool({ ... }) }
@@ -2035,16 +2274,24 @@ Every public symbol can be imported from `'weifuwu'`:
 ```ts
 serve, createTestServer, Router, ssr,
 Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
-loadEnv, testApp, TestApp, TestRequest, TestResponse,
-currentTraceId, currentTrace, runWithTrace, traceElapsed, TraceContext,
+loadEnv, env, isDev, isProd, isBundled, getPublicEnv,
+currentTraceId, currentTrace, runWithTrace, traceElapsed, trace, TraceContext,
+testApp, TestApp, TestRequest, TestResponse,
+createTestDb, withTestDb,
+getCookies, setCookie, deleteCookie,
+createSSEStream, formatSSE, formatSSEData, SSEEvent,
+DEFAULT_MAX_BODY, MIGRATIONS_TABLE,
 ```
 
-### Middleware modules
+### Middleware / DevTools
 
 ```ts
-auth, cors, csrf, compress, helmet, logger, rateLimit, requestId, validate, upload,
-theme, i18n, flash, permissions, serveStatic, session, MemoryStore, RedisStore, SessionStore,
-cache, MemoryCache, RedisCache, CacheStore
+logger, cors, compress, helmet,
+rateLimit, requestId, validate, upload,
+csrf, session, MemoryStore, RedisStore, SessionStore,
+cache, MemoryCache, RedisCache, CacheStore,
+flash, permissions,
+serveStatic, s3,
 ```
 
 ### Database
@@ -2054,55 +2301,87 @@ postgres, PostgresOptions, PostgresClient,
 redis, RedisOptions, RedisClient,
 queue, QueueOptions, QueueJob, Queue,
 PostgresInjected, RedisInjected, QueueInjected,
-// Schema helpers — importable alongside postgres:
+// Schema helpers:
 pgTable, SQL, sql,
 ColumnBuilder, serial, uuid, text, integer, boolean, boolean_, timestamptz, jsonb, textArray, vector,
 partitionBy, timestamps, toDDL, PartitionByDef,
 Table, BoundTable, IndexOptions, FindOptions, CreateOptions,
-eq, ne, gt, gte, lt, lte, isNull, isNotNull, like, contains, in_, and, or, not
+eq, ne, gt, gte, lt, lte, isNull, isNotNull, like, contains, in_, and, or, not,
+fts,
 ```
 
-### Client-side (from `'weifuwu/react'`)
+### Security / Auth
 
 ```ts
-TsxContext, setCtx, useCtx, addCtxRebuilder, useLoaderData,
-useWebsocket, useAction, useFetch, useQueryState, createStore,
-Link, useNavigate, useNavigating, addInterceptor,
-useLocale, useTheme, applyTheme, useFlashMessage,
-useAgentStream,
-Head
+auth,
+user, UserModule, UserData, UserOptions, UserInjected, OAuthProviderConfig, OAuth2Client,
+permissions, PermissionsModule, PermissionsOptions,
+csrf, CsrfOptions, CsrfInjected,
+helmet, HelmetOptions,
+session, SessionStore, SessionOptions, SessionData, SessionInjected,
+rateLimit, RateLimitOptions,
 ```
-export type { UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState } from 'weifuwu/react'
 
-### AI Provider (framework abstraction)
+### UX Middleware
 
 ```ts
-aiProvider, AIProvider, AIProviderOptions
+theme, ThemeOptions, ThemeInjected,
+i18n, I18nOptions, I18nInjected,
+flash, FlashOptions, FlashInjected,
 ```
 
-### AI SDK (re-exported from `ai`)
+### AI
 
 ```ts
+aiProvider, AIProvider, AIProviderOptions, AIProviderInjected,
 streamText, generateText, streamObject, generateObject,
 tool, embed, embedMany, smoothStream,
-openai, createOpenAI
+openai, createOpenAI,
+aiStream, AIHandler,
+runWorkflow,
+agent, AgentModule, AgentOptions,
+knowledgeBase, KBModule, KBOptions,
+opencode, OpencodeModule, OpencodeOptions,
 ```
 
-### Other modules
+### API / Routing
 
 ```ts
-theme, i18n, flash, health, analytics, seo, seoMiddleware, seoTags,
-user, mailer, graphql, aiStream, runWorkflow, knowledgeBase, permissions, queue,
-logdb, messager, agent, iii, createWorker, registerWorker,
-opencode, deploy, defineConfig, webhook,
-testApp, TestApp, TestRequest, TestResponse,
-createTestDb, withTestDb,
-getCookies, setCookie, deleteCookie,
-createSSEStream, formatSSE, formatSSEData,
-currentTraceId, currentTrace, runWithTrace, traceElapsed,
-createHub, Hub, HubOptions,
-DEFAULT_MAX_BODY, MIGRATIONS_TABLE,
-fts,
+analytics, AnalyticsModule, AnalyticsOptions,
+health, HealthOptions,
+graphql, GraphQLOptions, GraphQLHandler,
+logdb, LogdbModule, LogdbOptions,
+seo, seoMiddleware, seoTags, SeoOptions,
+webhook, WebhookModule, WebhookOptions,
+iii, createWorker, registerWorker, IIIModule, IIIOptions,
+```
+
+### Networking / Storage
+
+```ts
+s3, S3Options, S3Module, S3Body,
+mailer, MailerOptions, Mailer,
+messager, MessagerModule, MessagerOptions,
+hub, createHub, Hub, HubOptions,
+deploy, defineConfig, DeployConfig, AppConfig,
+tenant, TenantModule, TenantOptions, TenantContext,
+```
+
+### Client-side (from `'weifuwu/react'`)
+
+```ts
+TsxContext, setCtx, useCtx, addCtxRebuilder, useLoaderData,
+useWebsocket, useAction, useFetch, useQueryState, createStore,
+Link, useNavigate, useNavigating, addInterceptor,
+useLocale, useTheme, applyTheme, useFlashMessage,
+useAgentStream,
+Head,
+
+// Types:
+StoreApi,
+UseActionOptions, UseActionReturn,
+UseWebsocketOptions, UseWebsocketReturn,
+UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState,
 ```
 
 ---