weifuwu 0.22.2 → 0.23.0

package/README.md

@@ -60,10 +60,20 @@ await server.ready
 | `shutdown` | `boolean` | `true` | Auto SIGTERM/SIGINT |
 
 ```ts
-interface Server { stop: () => Promise<void>; readonly port: number; readonly hostname: string; ready: Promise<void> }
+interface Server {
+  stop: (timeoutMs?: number) => Promise<void>  // graceful: waits for in-flight, force-closes after timeoutMs (default 10s)
+  readonly port: number
+  readonly hostname: string
+  ready: Promise<void>
+}
 const { server, url } = await createTestServer(handler)
 ```
 
+`server.stop()` performs a graceful shutdown: stops accepting new connections,
+closes idle keep-alive sockets, then waits for in-flight requests to complete.
+If they don't finish within `timeoutMs` (default 10 seconds), remaining connections
+are forcibly closed. SIGTERM/SIGINT use the same graceful pattern.
+
 ### Router
 
 ```ts
@@ -113,7 +123,7 @@ Request → serve() → app.handler() → global middleware × N → path middle
 
 1. `serve()` receives HTTP request
 2. `app.handler()` creates `ctx = { params, query }` and routes to the matching trie node
-3. **Global middleware** runs in `use()` order (e.g. `preferences()`, `postgres()`, `cors()`)
+3. **Global middleware** runs in `use()` order (e.g. `theme()`, `i18n()`, `postgres()`, `cors()`) 
 4. **Path‑scoped middleware** runs for matching paths (e.g. `app.use('/admin', authMW)`)
 5. **Route‑level middleware** runs (e.g. `app.get('/admin', validate(...), handler)`)
 6. **Route handler** returns `Response` — middleware chain unwinds
@@ -142,22 +152,23 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `csrfToken` | `csrf()` | `string` | CSRF token |
 | `requestId` | `requestId()` | `string` | Request ID |
 | `session` | `session()` | `Session` | Session data object |
-| `sessionId` | `session()` | `string` | Session ID |
 | `sql` | `postgres()` | `Sql<{}>` | PostgreSQL tagged-template client |
 | `redis` | `redis()` | `Redis` | Redis client |
+| `ai` | `aiProvider()` | `AIProvider` | AI model & embedding |
 | `queue` | `queue()` | `Queue` | Job queue |
-| `prefs` | `preferences()` | `{ locale, theme }` | User preferences (locale, theme) |
-| `deploy` | `deploy()` | `{ appName? }` | Deploy gateway info |
+| `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 |
+| `i18n` | `i18n()` | `{ locale, t, set }` | Locale, translation, switcher |
+| `flash` | `flash()` | `{ value, set }` | Flash message + setter |
+| `tailwind` | `tailwindContext()` | `{ css, url }` | Compiled Tailwind CSS |
+| `tenant` | `tenant()` | `TenantContext` | Current tenant info |
+| `parsed` | `validate()` / `upload()` | `{ body, files }` | Validated/parsed request data |
 | `layoutStack` | `ssr()` internal | `LayoutEntry[]` | React layout component stack |
 | `loaderData` | User middleware | `Record<string, unknown>` | SSR data passed to client |
-| `user` | `auth()` / `user().middleware()` | `{ id?: string }` | Authenticated user |
-| `parsed` | `validate()` / `upload()` | `{ body, query, params, headers, files }` | Validated/parsed request data |
-| `t` | `preferences()` | `(key) => string` | Translation function |
-| `setPref` | `preferences()` | `(key, val) => Response` | Set preference cookie + redirect |
-| `compiledTailwindCss` | `ssr()` internal | `string` | Compiled CSS content (internal) |
-| `tailwindCssUrl` | `ssr()` internal | `string` | Compiled CSS route URL (internal) |
-| `session` | `session()` | `Session` | Session data object |
-| `sessionId` | `session()` | `string` | Session ID |
+| `mountPath` | `Router` | `string` | Sub-router mount path |
+| `deploy` | `deploy()` | `{ appName? }` | Deploy gateway info |
 
 ### Type-Safe Context
 
@@ -186,7 +197,7 @@ All modules follow one of **2 patterns** — learn these and you know every modu
 
 | Pattern | How to mount | Example |
 |---------|-------------|---------|
-| `[α]` | `app.use(mod())` | `compress()`, `preferences()`, `postgres()` |
+| `[α]` | `app.use(mod())` | `compress()`, `theme()`, `postgres()` |
 | `[β]` | `app.use('/path', mod())` | `health()`, `ssr({dir})`, `graphql(handler)`, `user()` |
 
 ### Pattern α — Middleware
@@ -339,7 +350,8 @@ Uses `TEST_DATABASE_URL` or `DATABASE_URL`. Automatically skipped in CI if unset
 ### agent [β]
 
 ```ts
-const a = agent({ pg, model: openai('gpt-4o'), embeddingModel: openai.embedding('text-embedding-3-small') })
+const provider = aiProvider()
+const a = agent({ pg, provider })
 await a.migrate()
 app.use('/api', a)
 await a.addKnowledge(agentId, 'Title', 'some knowledge content')
@@ -349,9 +361,10 @@ a.run(agentId, { input: 'summarize the data', stream: true })
 | 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 |
+| `provider` | `AIProvider` | `aiProvider()` (from env) | AI provider for model & embedding resolution |
+| `model` | `object` | — | Explicit AI model (overrides provider) |
+| `embeddingModel` | `object` | — | Explicit embedding model (overrides provider) |
+| `embeddingDimension` | `number` | `provider.dimension` | Embedding vector dimension |
 | `tools` | `object[]` | — | Custom tool definitions |
 
 | Method | Description |
@@ -366,13 +379,15 @@ a.run(agentId, { input: 'summarize the data', stream: true })
 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 }))
+const provider = aiProvider()
+const chat = await aiStream(async (req) => ({ messages: (await req.json()).messages }), provider)
 app.use('/chat', chat)
 ```
 
 | Param | Type | Description |
 |-------|------|-------------|
 | `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 [β]
 
@@ -404,6 +419,16 @@ 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, req) => ({ sub: 'abc' }) })) // custom verify → sets ctx.user
 app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
+
+// Session-based auth (must be placed after session() middleware)
+app.use(session())
+app.use(auth({
+  session: true,
+  resolveUser: async (userId) => {          // load user from DB
+    const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`
+    return user ?? null                      // null → destroy stale session
+  },
+}))
 ```
 
 | Option | Type | Default | Description |
@@ -412,6 +437,13 @@ app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
 | `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 |
+| `session` | `boolean` | `false` | Enable session-based auth. Checks `ctx.session.userId` first |
+| `resolveUser` | `(userId) => object\|null` | — | Load user from userId (called when `session: true`). Return falsy to reject + auto-destroy stale session |
+
+When `session: true`, auth checks `ctx.session.userId` before the
+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 [α]
 
@@ -699,6 +731,60 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 
 
 
+### knowledgeBase [β] — RAG with pgvector
+
+```ts
+import { knowledgeBase, aiProvider } from 'weifuwu'
+
+const kb = knowledgeBase({
+  pg: postgres(),
+  provider: aiProvider(),
+  table: 'my_docs',
+})
+
+// Create table + HNSW index (safe to call multiple times)
+await kb.migrate()
+
+// Ingest a document (auto chunk → embed → store)
+await kb.ingest('docs/intro.md', `# Welcome\n\nThis is the introduction...`, {
+  title: 'Introduction',
+  metadata: { source: 'docs', author: 'alice' },
+})
+
+// Semantic search
+const results = await kb.search('how to get started?', { limit: 5 })
+// → [{ key, title, content, score: 0.92, metadata }, ...]
+
+// Delete
+await kb.delete('docs/outdated.md')
+
+// List all documents
+const entries = await kb.list()
+// → [{ key, title, chunks: 3 }, ...]
+
+// Use as middleware (injects ctx.kb.search)
+app.use(kb.middleware())
+app.get('/search', async (req, ctx) => {
+  const results = await ctx.kb.search(ctx.query.q)
+  return Response.json(results)
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `PostgresClient` | — | **Required.** PostgreSQL client |
+| `provider` | `AIProvider` | — | **Required.** AI provider for embedding |
+| `table` | `string` | `'_kb_docs'` | Database table name |
+| `chunkSize` | `number` | `512` | Max characters per chunk |
+| `chunkOverlap` | `number` | `64` | Overlap between chunks |
+| `searchLimit` | `number` | `5` | Default search result count |
+| `searchThreshold` | `number` | `0` | Minimum similarity (0–1) |
+
+Documents are split on paragraph boundaries (`\n\n`). Re-ingesting the same key
+replaces old chunks. Provider's `embed()` is used automatically.
+The HNSW index enables fast approximate nearest-neighbor search (cosine distance).
+
+
 ### logdb [β]
 
 PostgreSQL structured event logging with monthly partitioning.
@@ -746,6 +832,72 @@ await mail.send({ to: 'user@test.com', subject: 'Hello', text: 'Body', html: '<p
 | `from` | `string` | — | Default sender address |
 | `send` | `function` | — | Custom send function (alternative to transport) |
 
+
+
+### oauthClient [β] — Social login (OAuth 2.0 client)
+
+```ts
+import { oauthClient } from 'weifuwu'
+
+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
+  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,
+    },
+  },
+}))
+```
+
+**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).
+
+Supports custom providers via `authUrl`, `tokenUrl`, `userUrl`, and `parseUser`:
+
+```ts
+app.use('/auth', oauthClient({
+  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`
+          : '',
+      }),
+    },
+  },
+}))
+```
+
+| Option | 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`.
+
+
 ### messager [β]
 
 Real-time chat with channels, WebSocket, agent routing.
@@ -976,56 +1128,110 @@ await fts.dropIndex(pg.sql, articles)
 
 Search options: `fields`, `limit` (20), `offset` (0), `headline` (false), `language` ('english'), `minRank`.
 
-### preferences [α]
+### theme [α]
+
+```ts
+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
+```
 
-Locale detection + theme + translations. `/__lang/:locale` and `/__theme/:theme` auto-routed.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `default` | `string` | `'system'` | Default theme |
+| `cookie` | `string` | `'theme'` | Cookie name (empty to disable) |
 
 ```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
+// Server-side switching
+app.post('/settings', async (req, ctx) => {
+  const { theme } = await req.json()
+  return ctx.theme.set(theme, '/settings')
+})
 ```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `dir` | — | Translation JSON directory |
-| `locale.default` | `'en'` | Fallback locale |
-| `locale.cookie` | `'locale'` | Cookie name |
-| `locale.fromAcceptLanguage` | `true` | Detect from header |
-| `theme.default` | `'system'` | `'light'` \| `'dark'` \| `'system'` |
-| `theme.cookie` | `'theme'` | Cookie name |
+See [`useTheme()`](#usetheme) for client-side usage.
 
-```tsx
-// Client-side no-refresh switching — import enables it automatically
-import { useLocale, useTheme } from 'weifuwu/react'
+### i18n [α]
 
-<Link href="/__lang/zh">中文</Link>         // <Link> handles it via interceptor
-<button onClick={() => setLocale('en')}>EN</button>  // or programmatic
-const { theme, resolvedTheme, setTheme } = useTheme()
-// resolvedTheme resolves 'system' → 'dark'|'light' based on prefers-color-scheme
+```ts
+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)
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `default` | `string` | `'en'` | Default locale |
+| `dir` | `string` | — | Directory with `{locale}.json` files |
+| `messages` | `object` | — | Inline translations: `{ zh: { welcome: '欢迎' } }` |
+| `cookie` | `string` | `'locale'` | Cookie name (empty to disable) |
+| `fromAcceptLanguage` | `boolean` | `true` | Detect from Accept-Language header |
+
+```ts
+// Handler
+app.get('/greet', async (req, ctx) => {
+  const greeting = ctx.i18n?.t('welcome', { name: 'Alice' })
+  return Response.json({ greeting, locale: ctx.i18n?.locale })
+})
+```
+
+**Client-side:** import `useLocale` from `weifuwu/react`, `useTheme` from `weifuwu/react`.
+
 ### queue [α]
 
+Async job queue. Supports immediate, delayed, and recurring (cron) tasks with three backends:
+
+- `{ store: 'memory' }` — in-memory, zero dependency, suitable for dev & cron-like tasks
+- `{ store: 'pg', pg }` — PostgreSQL-backed, persistent, multi-instance safe via `FOR UPDATE SKIP LOCKED`
+- `{ store: 'redis', redis }` — Redis-backed, production-grade, distributed
+
 ```ts
-const q = queue({ redis })
-app.use(q)                     // injects ctx.queue
-await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
+// Create queue
+const q = queue({ store: 'memory' })
+// const q = queue({ store: 'pg', pg })
+// const q = queue({ store: 'redis', redis })
+
+// Register cron job (uses the same backend for persistence)
+q.cron('*/5 * * * *', async () => { await cleanCache() })
+
+// Or use process/add for full queue semantics
+q.process('send-email', async (job) => {
+  await sendMail(job.payload)
+})
+
+// Immediate
+q.add('send-email', { to: 'user@test.com' })
+
+// Delayed
+q.add('send-email', { to: 'user@test.com' }, { delay: 60_000 })
+
+// Scheduled (cron) — re-queues automatically
+q.add('weekly-report', {}, { schedule: '0 9 * * 1' })
+
+q.run()
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `redis` | `object` | — | Redis client |
+| `store` | `'memory' \| 'pg' \| 'redis'` | `'memory'` | Backend store |
+| `redis` | `object` | — | Redis client (required when `store: 'redis'`) |
 | `url` | `string` | — | Redis URL (alternative to client) |
-| `prefix` | `string` | `'queue:'` | Redis key prefix |
-| `pollInterval` | `number` | `1000` | Poll interval (ms) |
+| `pg` | `object` | — | PostgreSQL client (required when `store: 'pg'`) |
+| `prefix` | `string` | `'queue'` | Key/table prefix |
+| `pollInterval` | `number` | `200` | Poll interval (ms) |
 
 | Method | Description |
 |--------|-------------|
-| `.add(name, data, opts?)` | Add job to queue |
-| `.process(handler)` | Register job processor |
+| `.cron(pattern, handler)` | Register a cron job (uses process + add internally) |
+| `.add(type, payload, opts?)` | Add job (opts: `delay`, `schedule`) |
+| `.process(type, handler)` | Register job processor |
 | `.run()` | Start processing |
 | `.stop()` | Stop processing |
 | `.jobs(limit?)` | List pending jobs |
@@ -1035,6 +1241,18 @@ await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
 | `.dashboard()` | Returns a Router with management endpoints |
 | `.close()` | Cleanup |
 
+**Schedule (cron) field reference:**
+
+| Field | Range |
+|-------|-------|
+| minute | 0–59 |
+| hour | 0–23 |
+| day of month | 1–31 |
+| month | 1–12 |
+| day of week | 0–6 (0=Sunday) |
+
+Supported cron syntax: `*` (any), `*/n` (every n), `n-m` (range), `n,m,o` (list), `n` (exact).
+
 **Dashboard endpoints** (mount via `app.use('/__queue', q.dashboard())`):
 
 | Method | Path | Description |
@@ -1099,6 +1317,85 @@ app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID()
 
 
 
+### s3 [α] — S3-compatible object storage
+
+```ts
+import { s3 } from 'weifuwu'
+
+app.use(s3({
+  bucket: 'my-app',
+  region: 'us-east-1',
+  endpoint: process.env.S3_URL,              // MinIO / R2 / AWS
+  forcePathStyle: true,                       // required for MinIO
+  credentials: {
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY,
+  },
+  publicUrl: 'https://cdn.example.com',       // for unsigned public URLs
+}))
+```
+
+Injects `ctx.s3` with methods for S3-compatible object storage.
+
+```ts
+// Upload
+await ctx.s3.put('images/logo.png', buffer, { contentType: 'image/png' })
+
+// Download
+const buf = await ctx.s3.get('images/logo.png')  // Buffer | null
+
+// Delete
+await ctx.s3.delete('images/logo.png')
+
+// Check existence
+if (await ctx.s3.exists('images/logo.png')) { ... }
+
+// Signed URL (expires in 1 hour by default)
+const url = await ctx.s3.url('images/logo.png')
+const shortUrl = await ctx.s3.url('images/logo.png', { expiresIn: 60 })
+
+// Public URL (requires publicUrl in options)
+const publicUrl = await ctx.s3.url('images/logo.png', { expiresIn: 0 })
+
+// List objects under a prefix
+const keys = await ctx.s3.list('images/')
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bucket` | `string` | — | **Required.** S3 bucket name |
+| `region` | `string` | `'us-east-1'` | AWS region |
+| `endpoint` | `string` | — | Custom endpoint (MinIO, R2, B2) |
+| `forcePathStyle` | `boolean` | `false` | Path-style addressing (required for MinIO) |
+| `credentials` | `{ accessKeyId, secretAccessKey }` | — | Falls back to AWS env vars / IAM role |
+| `publicUrl` | `string` | — | Base URL for unsigned public URLs via `url(key, { expiresIn: 0 })` |
+
+Credentials can be omitted to use AWS environment variables (`AWS_ACCESS_KEY_ID`,
+`AWS_SECRET_ACCESS_KEY`) or IAM roles (EC2, ECS, Lambda).
+
+The module can also be used standalone without the middleware:
+
+```ts
+const storage = s3({ bucket: 'my-app', endpoint: '...' })
+await storage.put('key', body)
+const data = await storage.get('key')
+```
+
+Requires MinIO or another S3-compatible service for local development.
+Add to `docker-compose.yml`:
+
+```yml
+minio:
+  image: minio/minio
+  ports:
+    - '9000:9000'
+  environment:
+    MINIO_ROOT_USER: minioadmin
+    MINIO_ROOT_PASSWORD: minioadmin
+  command: server /data
+```
+
+
 ### seo [β] + seoMiddleware [α]
 
 ```ts
@@ -1155,6 +1452,16 @@ app.get('/logout', async (req, ctx) => {
 | `cookie.sameSite` | `string` | `'lax'` | SameSite policy |
 | `cookie.path` | `string` | `'/'` | Cookie path |
 | `cookie.domain` | `string` | — | Cookie domain |
+| `secret` | `string` | — | HMAC-SHA256 sign the session cookie (`uuid.signature`). Prevents tampering **strongly recommended in production** |
+| `rotateInterval` | `number` | `900000` (15min) | Auto-rotate session ID to prevent fixation attacks. Set `0` to disable |
+
+When `secret` is set, the cookie value is signed with HMAC-SHA256:
+`uuid.base64url(hmac)`. Tampered cookies are rejected and treated as new
+sessions (no error message, no data leak).
+
+Session ID auto-rotation copies data to a new ID and deletes the old one
+from the store. Rotation happens transparently on the next request after
+`rotateInterval` has elapsed.
 
 **Stores** are also exported for standalone use:
 
@@ -1171,7 +1478,7 @@ await redis.destroy('sid')
 
 ### ssr({ dir }) [β]
 
-One-stop Server-Side Rendering. Accepts a directory and returns a Router that handles all SSR routes, tailwind CSS, hydration bundles, and livereload — using Next.js-style file conventions.
+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.
 
 ```ts
 import { Router, ssr } from 'weifuwu'
@@ -1209,13 +1516,18 @@ app.use('/', ssr({ dir: './ui' }))
 | `app/error.tsx` | Error boundary for that subtree |
 | `app/globals.css` | Tailwind CSS entry (compiled via `@tailwindcss/postcss`) |
 
-**How it works:**
+**How hydration works:**
 
 - Each page is lazy-resolved on first request — only the `page.tsx` and its layout chain are compiled
-- Hydration bundle generated per-page at `/__ssr/{hash}.js`
+- An inline `<script type="module">` in the HTML handles hydration
+- It imports `{ setCtx, TsxContext }` from the vendor bundle (`/__wfw/v/bundle`) via importmap
+- Then dynamically imports the page component: `await import('/__ssr/[hash].js')`
+- 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`
 - Tailwind CSS served at `/__wfw/style/{hash}.css` (cached, content-hashed)
-- Dev mode: vendor bundle, HMR WebSocket, file watcher — all automatic
-- Page components and layouts are compiled via esbuild at runtime — no build step needed
+- Dev mode extras: HMR WebSocket, file watcher, hot component replacement
 
 ```ts
 // Multiple independent SSR directories
@@ -1263,13 +1575,23 @@ app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760, allowedT
 
 ### user [β]
 
-Authentication: register, login, JWT, OAuth2.
+Authentication: register, login, JWT, OAuth2 服务端, 社会化登录.
 
 ```ts
-const auth = user({ pg, jwtSecret: process.env.JWT_SECRET! })
-await auth.migrate()
-app.use('/auth', auth)               // POST /register, POST /login, OAuth2 routes
-app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
+const u = user({
+  pg,
+  jwtSecret: process.env.JWT_SECRET!,
+  oauthLogin: {                                          // 可选 — 社会化登录
+    providers: {
+      github: { clientId: '...', clientSecret: '...' },
+      google: { clientId: '...', clientSecret: '...' },
+    },
+  },
+})
+await u.migrate()
+app.use(u)                              // POST /register, POST /login
+app.use(u.middleware())                  // ctx.user
+// GET /auth/github, GET /auth/github/callback  (如配置 oauthLogin)
 ```
 
 | Option | Type | Default | Description |
@@ -1277,8 +1599,9 @@ app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 | `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) |
+| `expiresIn` | `string` | `'24h'` | JWT expiration |
+| `oauth2` | `object` | — | OAuth2 服务端 config (PKCE flow) |
+| `oauthLogin` | `object` | — | 社会化登录: `{ providers: Record<string, OAuthProviderConfig>, redirectUrl? }` |
 
 | Method | Description |
 |--------|-------------|
@@ -1287,6 +1610,54 @@ app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 | `.verify(token)` | Verify JWT token |
 | `.middleware()` | JWT verify middleware — sets `ctx.user` |
 
+### permissions [α] — RBAC
+
+Role-based access control.
+
+```ts
+const perm = permissions({ pg })
+await perm.migrate()
+
+// Assign roles & permissions
+await perm.assignRole(userId, 'admin')
+await perm.grantPermission('admin', 'posts:create')
+await perm.grantPermission('admin', 'posts:edit')
+await perm.grantPermission('admin', '*')         // wildcard — all permissions
+
+// Use as middleware
+app.use((req, ctx, next) => { ctx.user = { id: userId }; return next(req, ctx) })
+app.use(perm)                                     // → ctx.roles, ctx.permissions
+
+// Route guards
+app.get('/admin', perm.requireRole('admin'), adminHandler)
+app.post('/posts', perm.requirePermission('posts:create'), createHandler)
+
+// Handler-level check
+app.get('/posts/:id', async (req, ctx) => {
+  if (!ctx.permissions.has('posts:read')) {
+    return Response.json({ error: 'forbidden' }, { status: 403 })
+  }
+  return Response.json(post)
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `prefix` | `string` | `''` | Table prefix (e.g. `'myapp'` → `myapp_roles`) |
+
+| Method | Description |
+|--------|-------------|
+| `.assignRole(userId, role)` | Assign role to user (creates role if missing) |
+| `.removeRole(userId, role)` | Remove role from user |
+| `.grantPermission(role, permission)` | Grant permission to role |
+| `.revokePermission(role, permission)` | Revoke permission from role |
+| `.getUserRoles(userId)` | List user's roles |
+| `.getUserPermissions(userId)` | List user's permissions (union of all roles) |
+| `.requireRole(...roles)` | Middleware — rejects if user lacks any of the roles |
+| `.requirePermission(...perms)` | Middleware — rejects if user lacks any permission |
+| `.migrate()` | Create tables |
+
 ### validate [α]
 
 ```ts
@@ -1412,7 +1783,7 @@ const count = useStore(s => s.count)
 <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.
+**`TsxContext`** — React context holding page data (`params`, `query`, `user`, `parsed`, `theme`, `i18n`, `flash`, `loaderData`, `env`). Used internally by hooks; rarely needed directly.
 
 ### Locale & Theme
 
@@ -1426,7 +1797,7 @@ function LangSwitch() {
 
 | Return | Description |
 |--------|-------------|
-| `locale` | Current locale string (from `ctx.prefs.locale`) |
+| `locale` | Current locale string (from `ctx.i18n.locale`) |
 | `setLocale(locale)` | Switch locale (calls `navigate('/__lang/' + locale)`) |
 | `t` | Translate a key using loaded locale messages |
 
@@ -1465,7 +1836,7 @@ function Page() {
 }
 ```
 
-On the server, data flows from middleware → `ctx` → `ctx.loaderData` (serialized). On the client, it's restored from `window.__WEIFUWU_CTX`. Under the hood, `useLoaderData()` uses `AsyncLocalStorage` on the server and `window.__WEIFUWU_CTX` on the client — 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 store (`globalThis.__WEIFUWU_CTX_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.
 
@@ -1481,8 +1852,21 @@ addInterceptor(async (url) => {
 ### Flash messages
 
 ```ts
-// Server — set flash cookie on redirect, auto-cleared after first read
-return ctx.setPref('flash', JSON.stringify({ type: 'success', message: 'Done' }))  // 302 + Set-Cookie
+import { flash } from 'weifuwu'
+
+app.use(flash())
+
+// Read flash
+app.get('/', (req, ctx) => {
+  const msg = ctx.flash.value  // { type: 'success', text: 'Saved!' }
+})
+
+// Set flash + redirect
+app.post('/save', async (req, ctx) => {
+  await saveArticle()
+  return ctx.flash.set({ type: 'success', text: '已保存' }, '/articles')
+  // → 302 /articles + Set-Cookie flash=...
+})
 ```
 
 ```tsx
@@ -1490,36 +1874,91 @@ return ctx.setPref('flash', JSON.stringify({ type: 'success', message: 'Done' })
 import { useFlashMessage } from 'weifuwu/react'
 
 function Toast() {
-  const flash = useFlashMessage<{ type: string; message: string }>()
+  const flash = useFlashMessage<{ type: string; text: string }>()
   if (!flash) return null
-  return <div className={`toast toast-${flash.type}`}>{flash.message}</div>
+  return <div className={`toast toast-${flash.type}`}>{flash.text}</div>
 }
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | `'flash'` | Cookie name |
+
 ### Dev mode
 
-Auto-detected when `NODE_ENV !== 'production'`. `ssr({dir})` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
+Auto-detected when `NODE_ENV === 'development'`. `ssr({dir})` automatically registers importmap, vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
 
-When a `.tsx` or `.css` file changes under the `ssr` dir, the browser hot-updates without refreshing — `useState` values are preserved. Layout changes trigger a full page reload.
+- 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
+- Tailwind CSS hot-reloads without page refresh
+- Layout changes trigger a full page reload
 
 ---
 
 ## AI
 
 ```ts
-import { openai, streamText, generateText, streamObject, generateObject, tool, embed, embedMany } from 'weifuwu'
+import { openai, streamText, generateText, streamObject, generateObject, tool, embed, embedMany, aiProvider } from 'weifuwu'
 import { runWorkflow } from 'weifuwu'
+
+const provider = aiProvider()
 ```
 
 For AI streaming endpoints see [`aiStream`](#aistream-β). For AI agent APIs see [`agent`](#agent-β).
 
+### aiProvider [α] — AI model & embedding configuration
+
+```ts
+const provider = aiProvider()                 // auto from env
+app.use(provider)                              // → ctx.ai
+
+// Handler
+app.post('/ask', async (req, ctx) => {
+  const { text } = await ctx.ai.generateText({ prompt: 'hello' })
+  const vec = await ctx.ai.embed('some text')
+  const stream = ctx.ai.streamText({ system: 'assistant', messages: [...] })
+  return stream.toTextStreamResponse()
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseURL` | `string` | `OPENAI_BASE_URL` env or `http://localhost:11434/v1` | API base URL |
+| `apiKey` | `string` | `OPENAI_API_KEY` env or `'ollama'` | API key |
+| `model` | `string` | `OPENAI_MODEL` env or `'qwen3:0.6b'` | Chat model name |
+| `embeddingModel` | `string` | `OPENAI_EMBEDDING_MODEL` env or `'qwen3-embedding:0.6b'` | Embedding model name |
+| `embeddingDimension` | `number` | `EMBEDDING_DIMENSION` env or `1024` | Vector dimension |
+
+| Method | Description |
+|--------|-------------|
+| `.model(name?)` | Get `LanguageModel` instance |
+| `.embeddingModel(name?)` | Get `EmbeddingModel` instance |
+| `.embed(text)` | Embed single text → `Promise<number[]>` |
+| `.embedMany(texts)` | Batch embed → `Promise<number[][]>` |
+| `.generateText(params)` | Generate text (model auto-injected) |
+| `.streamText(params)` | Stream text (model auto-injected) |
+| `.dimension` | Configured embedding dimension |
+
 ### DAG Workflow
 
 ```ts
 const tools = { queryUser: tool({ ... }) }
-const wf = runWorkflow({ tools })
+
+// Via provider:
+const wf = runWorkflow({ tools, provider })
+
+// Or explicit model:
+const wf = runWorkflow({ tools, model: openai('gpt-4o') })
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tools` | `object` | — | Registered tool definitions |
+| `provider` | `AIProvider` | — | AI provider (uses `provider.model()` for LLM-generated workflow) |
+| `model` | `LanguageModel` | — | Explicit model (overrides provider) |
+| `maxSteps` | `number` | `200` | Max execution steps |
+
 ---
 
 ## Server-Sent Events
@@ -1549,7 +1988,7 @@ currentTraceId, currentTrace, runWithTrace, traceElapsed, TraceContext,
 
 ```ts
 auth, cors, csrf, compress, helmet, logger, rateLimit, requestId, validate, upload,
-preferences, serveStatic, session, MemoryStore, RedisStore, SessionStore,
+theme, i18n, flash, permissions, serveStatic, session, MemoryStore, RedisStore, SessionStore,
 cache, MemoryCache, RedisCache, CacheStore
 ```
 
@@ -1571,7 +2010,7 @@ eq, ne, gt, gte, lt, lte, isNull, isNotNull, like, contains, in_, and, or, not
 ### Client-side (from `'weifuwu/react'`)
 
 ```ts
-TsxContext, useLoaderData,
+TsxContext, setCtx, useCtx, addCtxRebuilder, useLoaderData,
 useWebsocket, useAction, useFetch, useQueryState, createStore,
 Link, useNavigate, useNavigating, addInterceptor,
 useLocale, useTheme, applyTheme, useFlashMessage,
@@ -1580,6 +2019,12 @@ Head
 ```
 export type { UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState } from 'weifuwu/react'
 
+### AI Provider (framework abstraction)
+
+```ts
+aiProvider, AIProvider, AIProviderOptions
+```
+
 ### AI SDK (re-exported from `ai`)
 
 ```ts
@@ -1591,8 +2036,8 @@ openai, createOpenAI
 ### Other modules
 
 ```ts
-preferences, health, analytics, seo, seoMiddleware, seoTags,
-user, mailer, graphql, aiStream, runWorkflow,
+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,