weifuwu 0.17.26 → 0.18.1

package/README.md

@@ -88,45 +88,89 @@ app.get('/admin', mw, handler)       // route-level
 
 ## Module Patterns
 
-All modules follow one of 5 patterns. The pattern letter is marked in each module's heading.
+All modules follow one of **2 patterns** — learn these and you know every module.
 
 | Pattern | How to mount | Example |
 |---------|-------------|---------|
-| `[A]` | `app.use(mod())` | `compress()`, `preferences()` |
-| `[B]` | `app.use(mod())` + call `.stop()` / `.close()` etc. | `rateLimit({...})` |
-| `[C]` | `app.use(mod.middleware())` + `app.use('/', mod.router())` | `analytics()`, `user()` |
-| `[D]` | `app.use(mod().handler())` | `health()`, `seo()` |
-| `[E]` | `app.use('/', g.router().handler())` | `graphql(handler)` |
+| `[α]` | `app.use(mod())` | `compress()`, `preferences()`, `postgres()` |
+| `[β]` | `app.use('/path', mod())` | `health()`, `graphql(handler)`, `user()` |
+
+### Pattern α — Middleware
+
+```ts
+app.use(compress())           // basic
+const pg = postgres()         // with extras: .sql, .table, .migrate(), .close()
+app.use(pg)
+app.use(rateLimit({ max: 100 }))  // with .stop()
+```
+
+### Pattern β — Router
+
+```ts
+app.use('/health', health())                                    // no extras
+app.use('/graphql', graphql(handler))
+app.use('/logs', logdb({ pg }))                                 // with .log(), .migrate()
+app.use('/auth', user({ pg, jwtSecret }))                       // with .middleware(), .register()
+app.ws('/ws', messager({ pg }).wsHandler())
+```
+
+β modules that need **separate middleware** use `.middleware()`:
+```ts
+const a = analytics()
+app.use(a.middleware())   // tracking
+app.use('/', a)           // dashboard
+```
 
 ---
 
 ## Module Reference
 
-### agent [C]
+### agent [β]
 
 ```ts
-const a = agent({ pg })
+const a = agent({ pg, model: openai('gpt-4o'), embeddingModel: openai.embedding('text-embedding-3-small') })
 await a.migrate()
-app.use('/api', a.router())
-await a.addKnowledge(agentId, 'Title', 'docs')
-a.run(agentId, { task: 'summarize' })
+app.use('/api', a)
+await a.addKnowledge(agentId, 'Title', 'some knowledge content')
+a.run(agentId, { input: 'summarize the data', stream: true })
 ```
 
-### aiStream [E]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `model` | `object` | — | AI model (e.g. `openai('gpt-4o')`) |
+| `embeddingModel` | `object` | — | Embedding model for knowledge search |
+| `embeddingDimension` | `number` | `1536` | Embedding vector dimension |
+| `tools` | `object[]` | — | Custom tool definitions |
+
+| Method | Description |
+|--------|-------------|
+| `.run(agentId, { input, stream?, messages? })` | Execute agent with input |
+| `.addKnowledge(agentId, title, content)` | Add knowledge document |
+| `.migrate()` | DB setup |
+| `.close()` | Cleanup |
+
+### aiStream [β]
+
+Creates an AI streaming chat endpoint using the Vercel AI SDK.
 
 ```ts
 const chat = await aiStream(async (req) => ({ model: openai('gpt-4o'), messages: (await req.json()).messages }))
-app.use('/chat', chat.router().handler())
+app.use('/chat', chat)
 ```
 
-### analytics [C]
+| Param | Type | Description |
+|-------|------|-------------|
+| `handler` | `(req, ctx) => AIStreamOptions \| Promise<AIStreamOptions>` | Returns AI SDK options (model, messages, schema, etc.) |
+
+### analytics [β]
 
 In-memory or PostgreSQL page view tracking with built-in dashboard.
 
 ```ts
 const a = analytics()
 app.use(a.middleware())
-app.use('/', a.router())       // GET /__analytics (dashboard), GET /__analytics/data?days=7 (JSON)
+app.use('/', a)       // GET /__analytics (dashboard), GET /__analytics/data?days=7 (JSON)
 ```
 
 | Option | Type | Default | Description |
@@ -139,26 +183,38 @@ app.use('/', a.router())       // GET /__analytics (dashboard), GET /__analytics
 const a = analytics({ pg })
 await a.migrate()
 app.use(a.middleware())
-app.use('/', a.router())
+app.use('/', a)            // dashboard routes
 ```
 
-### auth [A]
+### auth [α]
 
 ```ts
 app.use(auth({ token: 'sk-123' }))                              // static token
 app.use(auth({ header: 'X-API-Key', token: 'my-key' }))         // custom header
-app.use(auth({ verify: async (token) => ({ sub: 'abc' }) }))    // custom verify
+app.use(auth({ verify: async (token, req) => ({ sub: 'abc' }) })) // custom verify → sets ctx.user
 app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
 ```
 
-### compress [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `string` | — | Static token to match |
+| `header` | `string` | `'Authorization'` | Header name |
+| `verify` | `(token, req) => object\|null` | — | Verify function, return value sets `ctx.user` |
+| `proxy` | `string` | — | Auth service URL to proxy requests to |
+
+### compress [α]
 
 ```ts
-app.use(compress())                         // brotli > gzip > deflate
-app.use(compress({ threshold: 2048 }))      // only > 2KB
+app.use(compress())                         // brotli > gzip > deflate (min 1KB)
+app.use(compress({ threshold: 2048, level: 4 }))      // custom threshold and level
 ```
 
-### cors [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number` | `1024` | Minimum byte size to compress |
+| `level` | `number` | `6` | Compression level (zlib) |
+
+### cors [α]
 
 ```ts
 app.use(cors())                                            // allow all
@@ -167,18 +223,28 @@ app.use(cors({ origin: (o) => o.endsWith('.trusted.com') && o }))
 app.use(cors({ credentials: true, maxAge: 3600 }))
 ```
 
-### csrf [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `origin` | `string\|string[]\|function` | `'*'` | Allowed origins |
+| `methods` | `string[]` | `['GET','POST','PUT','DELETE','PATCH','HEAD','OPTIONS']` | Allowed methods |
+| `allowedHeaders` | `string[]` | — | Custom allowed headers |
+| `exposedHeaders` | `string[]` | — | Response headers exposed to client |
+| `credentials` | `boolean` | `false` | Allow cookies/credentials |
+| `maxAge` | `number` | — | Preflight cache duration (seconds) |
+
+### csrf [α]
 
 ```ts
 app.use(csrf())
-// ctx.csrfToken available in handlers
-// Auto-validates X-CSRF-Token header on POST/PUT/DELETE/PATCH
+// ctx.csrfToken — 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
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `cookie` | `'_csrf'` | Cookie name |
-| `header` | `'x-csrf-token'` | Header name |
+| `header` | `'x-csrf-token'` | Header name (also accepts `x-xsrf-token`) |
 | `key` | `'_csrf'` | Body field fallback |
 | `excludeMethods` | `['GET','HEAD','OPTIONS']` | Skip validation |
 
@@ -186,31 +252,59 @@ app.use(csrf())
 
 ```ts
 import { deploy, defineConfig } from 'weifuwu'
-const config = defineConfig({ apps: [{ name: 'api', dir: './api', domain: 'api.example.com', port: 3001 }] })
-await deploy(config)
+const config = defineConfig({
+  domain: 'example.com',
+  apps: {
+    api: { repo: 'git@github.com:user/api.git', entry: 'app.ts', port: 3001, subdomain: 'api' },
+  },
+})
+const server = await deploy(config)
+// server.close(), server.ready, server.url
+// server.apps.list(), server.apps.status(name), server.apps.deploy(name)
 ```
 
-### health [D]
+### health [β]
 
 ```ts
-app.use(health())                         // GET /health → 200
-app.use(health({ checks: { db: async () => { await pg.sql`SELECT 1`; return { ok: true } } } }))
+app.use('/health', health())
+// Returns 200 on success, 503 when check throws
 ```
 
-### helmet [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | `'/health'` | Health check endpoint |
+| `check` | `() => Promise<void>` | — | Async function; throws → 503 |
 
-13 security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
+### helmet [α]
+
+15 security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
 
 ```ts
 app.use(helmet())
 app.use(helmet({ contentSecurityPolicy: "default-src 'self'", xFrameOptions: 'DENY' }))
 ```
 
-### iii [C] — Worker / Function / Trigger
+| Option | Default | Description |
+|--------|---------|-------------|
+| `contentSecurityPolicy` | `"default-src 'self'"` | CSP policy |
+| `xFrameOptions` | `'SAMEORIGIN'` | Frame-embedding policy |
+| `strictTransportSecurity` | `'max-age=15552000; includeSubDomains'` | HSTS |
+| `referrerPolicy` | `'no-referrer'` | Referrer header |
+| `xContentTypeOptions` | `'nosniff'` | MIME sniffing protection |
+| `permissionsPolicy` | — | Feature permissions policy |
+| `crossOriginEmbedderPolicy` | — | COEP header |
+| `crossOriginOpenerPolicy` | — | COOP header |
+| `crossOriginResourcePolicy` | — | CORP header |
+
+### iii [β] — Worker / Function / Trigger
+
+Distributed function execution with WebSocket workers, triggers, and Redis streams.
 
 ```ts
+import { createWorker } from 'weifuwu'
 const engine = iii({ pg, redis })
-app.use('/iii', engine.router())
+app.use('/iii', engine)
+app.ws('/iii', engine.wsHandler())
 
 const w = createWorker('orders')
 w.registerFunction('orders::create', async (payload) => db.query('INSERT INTO orders ...', [payload.items]))
@@ -218,73 +312,138 @@ engine.addWorker(w)
 await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'] } })
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client for persistent triggers |
+| `redis` | `object` | — | Redis client for streams |
+| `streamTTL` | `number` | `3600` | Redis stream key TTL (seconds, 0 = no expiry) |
+
 | Method | Description |
 |--------|-------------|
 | `.addWorker(w)` | Register a worker |
-| `.trigger({ function_id, payload, action? })` | Invoke a function (sync or void) |
-| `.router()` | REST + WS API |
+| `.removeWorker(w)` | Remove a worker |
+| `.trigger({ function_id, payload, action?, timeout_ms? })` | Invoke a function |
+| `.listWorkers()` | List registered workers |
+| `.listFunctions()` | List registered functions |
+| `.listTriggers()` | List registered triggers |
+| `.wsHandler()` | WebSocket handler |
+| `.migrate()` | DB setup |
+| `.shutdown()` | Clean shutdown |
 
-### logdb [C]
+### logdb [β]
 
 PostgreSQL structured event logging with monthly partitioning.
 
 ```ts
 const logger = logdb({ pg })
 await logger.migrate()
-app.use('/logs', logger.router())
+app.use('/logs', logger)
 await logger.clean(12)   // drop partitions older than 12 months
-await logger.log({ level: 'info', source: 'app', message: 'hello' })
+await logger.log({ level: 'info', source: 'app', message: 'hello', metadata: { userId: 1 } })
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `table` | `string` | `'_log_entries'` | Table name |
+
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/` | Create log entry |
 | GET | `/` | Query (`?level=`, `?source=`, `?after=`, `?before=`, `?meta.*=`) |
 | GET | `/:id` | Get single entry |
 
-### logger [A]
+### logger [α]
 
 ```ts
 app.use(logger())                             // GET /hello 200 5ms
 app.use(logger({ format: 'combined' }))       // with query params
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | `'short' \| 'combined'` | `'short'` | Log format: path only, or path + query params |
+
 ### mailer
 
 ```ts
-const mail = mailer({ host: 'smtp.example.com', port: 587, auth: { user, pass } })
-await mail.send({ to: 'user@test.com', subject: 'Hello', text: 'Body', html: '<p>Body</p>' })
+const mail = mailer({ from: 'noreply@example.com', transport: 'smtp://user:pass@smtp.example.com:587' })
+await mail.send({ to: 'user@test.com', subject: 'Hello', text: 'Body', html: '<p>Body</p>', cc: 'admin@test.com' })
 ```
 
-### messager [C]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `transport` | `string\|object` | — | Nodemailer transport config or connection string |
+| `from` | `string` | — | Default sender address |
+| `send` | `function` | — | Custom send function (alternative to transport) |
+
+### messager [β]
 
 Real-time chat with channels, WebSocket, agent routing.
 
 ```ts
 const msg = messager({ pg, agents, redis: redis() })
 await msg.migrate()
-app.ws('/ws', u.middleware(), msg.wsHandler())
-await msg.send(channelId, 'System message', { sender_type: 'system' })
+app.use('/api', msg)
+app.ws('/ws', msg.wsHandler())
+await msg.send(channelId, 'System message', { sender_type: 'system', sender_id: 'bot' })
 ```
 
-### opencode [C]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `agents` | `AgentModule` | — | Agent module for routing |
+| `webhookTimeout` | `number` | — | Webhook timeout |
+| `redis` | `object` | — | Redis client |
+
+| Method | Description |
+|--------|-------------|
+| `.wsHandler()` | WebSocket handler (channels, typing, read receipts) |
+| `.send(channel, content, opts?)` | Send message to channel |
+| `.close()` | Cleanup |
+
+### opencode [β]
 
 AI programming assistant.
 
 ```ts
-const oc = await opencode({ pg, permissions: { bash: { allow: true }, write: { allow: false } } })
+const oc = await opencode({
+  pg,
+  model: openai('gpt-4o'),
+  workspace: '/home/user/project',
+  permissions: { bash: { allow: true }, write: { allow: false } },
+})
 await oc.migrate()
-app.use('/opencode', await oc.router())
+app.use('/opencode', oc)
 app.ws('/opencode', oc.wsHandler())
 ```
 
-### postgres [B]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `model` | `string` | — | AI model name (e.g. `'gpt-4o'`, `'deepseek-v4-flash'`) |
+| `baseURL` | `string` | — | OpenAI-compatible API base URL |
+| `apiKey` | `string` | — | API key for the model |
+| `workspace` | `string` | — | Project directory |
+| `systemPrompt` | `string` | — | Custom system prompt |
+| `skills` | `object[]` | — | Custom skill definitions |
+| `permissions` | `object` | — | Tool permission rules |
+
+### postgres [α]
 
 ```ts
 const pg = postgres()          // reads DATABASE_URL
 app.use(pg)                    // injects ctx.sql
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connection` | `string` | `DATABASE_URL` env | PostgreSQL connection string |
+| `max` | `number` | `10` | Max pool connections |
+| `ssl` | `boolean\|object` | — | SSL options |
+| `idle_timeout` | `number` | `30` | Idle timeout (seconds) |
+| `connect_timeout` | `number` | `30` | Connection timeout |
+
 ```ts
 // Type-safe DDL
 const users = pgTable('_users', { id: serial('id').primaryKey(), name: text('name').notNull(), email: text('email').unique().notNull(), active: boolean('active').default(true), ...timestamps() })
@@ -301,13 +460,14 @@ await pg.transaction(async (tx) => { const users = pg.table('_users', { ... }).w
 
 Where helpers: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `isNull`, `isNotNull`, `like`, `contains`, `in_`, `and`, `or`, `not`.
 
-### preferences [A]
+### preferences [α]
 
 Locale detection + theme + translations. `/__lang/:locale` and `/__theme/:theme` auto-routed.
 
 ```ts
 app.use(preferences({ dir: './locales', locale: { default: 'en' }, theme: { default: 'system' } }))
 // ctx.prefs.locale, ctx.prefs.theme, ctx.t('key'), ctx.setPref('locale', 'zh')
+// ctx.setPref() returns a 302 Response with Set-Cookie — return it from your handler
 // GET /__lang/zh → 302 + Set-Cookie  (or JSON if Accept: application/json)
 // GET /__theme/dark → same pattern
 ```
@@ -331,48 +491,92 @@ const { theme, resolvedTheme, setTheme } = useTheme()
 // resolvedTheme resolves 'system' → 'dark'|'light' based on prefers-color-scheme
 ```
 
-### queue [B]
+### queue [α]
 
 ```ts
 const q = queue({ redis })
+app.use(q)                     // injects ctx.queue
 await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
 ```
 
-### rateLimit [B]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `redis` | `object` | — | Redis client |
+| `url` | `string` | — | Redis URL (alternative to client) |
+| `prefix` | `string` | `'queue:'` | Redis key prefix |
+| `pollInterval` | `number` | `1000` | Poll interval (ms) |
+
+| Method | Description |
+|--------|-------------|
+| `.add(name, data, opts?)` | Add job to queue |
+| `.process(handler)` | Register job processor |
+| `.run()` | Start processing |
+| `.stop()` | Stop processing |
+| `.close()` | Cleanup |
+
+### rateLimit [α]
 
 ```ts
 app.use(rateLimit({ max: 100, window: 60_000 }))            // 100 req/min
 app.get('/api', rateLimit({ max: 10 }), handler)            // per-route
 app.use(rateLimit({ key: (req) => req.headers.get('x-api-key') ?? 'anonymous' }))
+// Sets X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After headers
 // m.stop() — clear interval
 ```
 
-### redis [B]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max` | `number` | `100` | Max requests per window |
+| `window` | `number` | `60_000` | Window duration (ms) |
+| `key` | `(req) => string` | IP-based | Key function |
+| `message` | `string` | `'Too Many Requests'` | 429 response body |
+
+### redis [α]
 
 ```ts
-const r = redis()        // reads REDIS_URL
-app.use(r)               // injects ctx.redis
+const r = redis()          // reads REDIS_URL
+app.use(r)                 // injects ctx.redis
 await ctx.redis.set('key', 'value')
 // r.close() — cleanup
 ```
 
-### requestId [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | `REDIS_URL` env | Redis connection string |
+| (all ioredis options) | — | — | Passed directly to ioredis |
+
+### requestId [α]
 
 ```ts
 app.use(requestId())
+app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID() }))
 // Sets X-Request-ID header on responses, available as ctx.requestId
 ```
 
-### seo [D] + seoMiddleware [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `header` | `string` | `'X-Request-ID'` | Header name to read/write |
+| `generator` | `() => string` | `crypto.randomUUID()` | ID generator |
+
+### seo [β] + seoMiddleware [α]
 
 ```ts
-app.use(seo({ baseUrl: 'https://example.com', robots: [{ userAgent: '*', allow: '/' }], sitemap: { urls: [{ loc: '/' }] } }))
+app.use('/', seo({ baseUrl: 'https://example.com', robots: [{ userAgent: '*', allow: '/' }], sitemap: { urls: [{ loc: '/' }] } }))
 // GET /robots.txt, GET /sitemap.xml
 
 app.use(seoMiddleware({ headers: { 'X-Robots-Tag': (path) => path.startsWith('/admin') ? 'noindex' : undefined } }))
 ```
 
-### tenant [C]
+Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML string.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | — | Base URL for sitemap URLs |
+| `robots` | `RobotsRule[]` | `[{ userAgent: '*', allow: '/' }]` | Robots.txt rules |
+| `sitemap` | `SitemapConfig` | — | Sitemap configuration (urls, resolve, cacheTTL) |
+| `headers` | `SeoHeadersConfig` | — | Response headers (e.g. `X-Robots-Tag`) |
+
+### tenant [β]
 
 Multi-tenant BaaS with dynamic table API and GraphQL.
 
@@ -380,36 +584,69 @@ Multi-tenant BaaS with dynamic table API and GraphQL.
 const t = tenant({ pg, usersTable: '_users' })
 await t.migrate()
 app.use('/api', t.middleware())   // → ctx.tenant
-app.use('/api', t.router())      // dynamic CRUD
+app.use('/api', t)      // dynamic CRUD
 app.use('/graphql', t.graphql()) // dynamic GraphQL
 ```
 
-### upload [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `usersTable` | `string` | — | Users table name for tenant membership lookup |
+
+### upload [α]
 
 ```ts
-app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760 }), (req, ctx) => {
-  // ctx.parsed.files.avatar → { name, type, size, path }
+app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760, allowedTypes: ['image/jpeg', 'image/png'] }), (req, ctx) => {
+  // ctx.parsed.files.avatar → { name, type, size, path } or { name, type, size, buffer } (when no dir)
+  // Multiple files with same field name → array
   // ctx.parsed.fields.title → 'hello'
 })
 ```
 
-### user [C]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dir` | `string` | — | Write files to disk (omit for in-memory) |
+| `maxFileSize` | `number` | — | Max bytes per file |
+| `allowedTypes` | `string[]` | — | Allowed MIME types |
+
+### user [β]
+
+Authentication: register, login, JWT, OAuth2.
 
 ```ts
 const auth = user({ pg, jwtSecret: process.env.JWT_SECRET! })
 await auth.migrate()
-app.use('/auth', auth.router())               // POST /register, POST /login
+app.use('/auth', auth)               // POST /register, POST /login, OAuth2 routes
 app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 ```
 
-### validate [A]
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `jwtSecret` | `string` | — | JWT signing secret |
+| `table` | `string` | `'_users'` | Users table name |
+| `expiresIn` | `string` | `'7d'` | JWT expiration |
+| `oauth2` | `object` | — | OAuth2 client config (PKCE flow) |
+
+| Method | Description |
+|--------|-------------|
+| `.register(data)` | Register a new user programmatically |
+| `.login(data)` | Log in programmatically |
+| `.verify(token)` | Verify JWT token |
+| `.middleware()` | JWT verify middleware — sets `ctx.user` |
+
+### validate [α]
 
 ```ts
 import { z } from 'zod'
 const CreateUser = z.object({ name: z.string().min(1), email: z.string().email() })
-app.post('/users', validate({ body: CreateUser }), (req, ctx) => {
+app.post('/users', validate({ body: CreateUser, query: z.object({ ref: z.string().optional() }) }), (req, ctx) => {
   // ctx.parsed.body — typed & validated
+  // ctx.parsed.query — typed & validated
+  // ctx.parsed.params — typed & validated (for dynamic routes)
+  // ctx.parsed.headers — typed & validated
 })
+// Validation failure: returns 400 with { error: 'Validation failed', issues: [...] }
 ```
 
 ---
@@ -481,17 +718,27 @@ const loading = useNavigating()              // reactive loading state
 
 ```tsx
 import { useWebsocket, useAction, useFetch, useQueryState, createStore, Head } from 'weifuwu/react'
-import { useLocale, useTheme, applyTheme, addInterceptor, useLoaderData } from 'weifuwu/react'
+import { useLocale, useTheme, applyTheme, addInterceptor, useLoaderData, useFlashMessage } from 'weifuwu/react'
 
 // WebSocket — auto-reconnecting
-const { send, lastMessage, readyState } = useWebsocket('/ws/chat', { onMessage: (d) => console.log(d), reconnect: { maxRetries: 10, delay: 3000 } })
+const { send, lastMessage, readyState, close, reconnect } = useWebsocket('/ws/chat', {
+  onMessage: (d) => console.log(d),
+  reconnect: { maxRetries: 10, delay: 3000 },
+  protocols: [],          // optional sub-protocols
+  enabled: true,          // pause/resume connection
+})
 
 // Form action
-const { submit, data, error, pending } = useAction('/api/feedback', { method: 'POST' })
-// Auto-reads _csrf cookie, sends as X-CSRF-Token
+const { submit, data, error, pending, reset } = useAction('/api/feedback', {
+  method: 'POST',
+  headers: { 'X-Custom': 'value' },
+  onSuccess: (data) => console.log(data),
+  onError: (err) => console.error(err),
+})
+// Auto-reads _csrf cookie, sends as x-csrf-token or x-xsrf-token
 
 // Data fetching — cache + dedup + mutate
-const { data, error, loading, mutate } = useFetch('/api/posts', { fallback: loadData })
+const { data, error, loading, mutate } = useFetch('/api/posts', { fallback: loadData, ttl: 30_000 })
 
 // URL query state
 const [q, setQ] = useQueryState('q', '')
@@ -503,9 +750,10 @@ const count = useStore(s => s.count)
 
 // Per-page meta tags
 <Head><title>Page Title</title><meta name="description" content="..." /></Head>
-
 ```
 
+**`TsxContext`** — React context holding page data (`params`, `query`, `user`, `parsed`, `prefs`, `env`). Used internally by hooks; rarely needed directly.
+
 ### Locale & Theme
 
 ```tsx
@@ -520,7 +768,7 @@ function LangSwitch() {
 |--------|-------------|
 | `locale` | Current locale string (from `ctx.prefs.locale`) |
 | `setLocale(locale)` | Switch locale (calls `navigate('/__lang/' + locale)`) |
-| `t` | Translation function (same as `useCtx().t`) |
+| `t` | Translate a key using loaded locale messages |
 
 ```tsx
 import { useTheme } from 'weifuwu/react'
@@ -571,11 +819,19 @@ addInterceptor(async (url) => {
 ### Flash messages
 
 ```ts
-// Server
+// Server — set flash cookie on redirect, auto-cleared after first read
 return ctx.setPref('flash', JSON.stringify({ type: 'success', message: 'Done' }))  // 302 + Set-Cookie
+```
+
+```tsx
+// Client
+import { useFlashMessage } from 'weifuwu/react'
 
-// Client (tsx)
-function Toast() { const { prefs } = useCtx(); const flash = prefs?.flash ? JSON.parse(prefs.flash) : null; ... }
+function Toast() {
+  const flash = useFlashMessage<{ type: string; message: string }>()
+  if (!flash) return null
+  return <div className={`toast toast-${flash.type}`}>{flash.message}</div>
+}
 ```
 
 ### Dev mode
@@ -591,21 +847,7 @@ import { openai, streamText, generateText, streamObject, generateObject, tool, e
 import { runWorkflow } from 'weifuwu'
 ```
 
-### Streaming
-
-```ts
-const chat = await aiStream(async (req) => ({ model: openai('gpt-4o'), messages: (await req.json()).messages }))
-app.use('/chat', chat.router().handler())
-```
-
-### Agents
-
-```ts
-const agents = agent({ pg })
-await agents.migrate()
-app.use('/api', agents.router())
-await agents.addKnowledge(agentId, 'Title', 'content')
-```
+For AI streaming endpoints see [`aiStream`](#aistream-β). For AI agent APIs see [`agent`](#agent-β).
 
 ### DAG Workflow