weifuwu 0.22.3 → 0.23.0

package/README.md

@@ -123,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
@@ -152,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
 
@@ -196,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
@@ -349,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')
@@ -359,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 |
@@ -376,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 [β]
 
@@ -729,15 +734,12 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 ### knowledgeBase [β] — RAG with pgvector
 
 ```ts
-import { knowledgeBase } from 'weifuwu'
-import { embed } from 'ai'
+import { knowledgeBase, aiProvider } from 'weifuwu'
 
 const kb = knowledgeBase({
-  sql: ctx.sql,
-  embedding: (text) =>
-    embed({ model: openai.embedding('text-embedding-3-small'), value: text })
-      .then(r => r.embedding),
-  dimensions: 1536,
+  pg: postgres(),
+  provider: aiProvider(),
+  table: 'my_docs',
 })
 
 // Create table + HNSW index (safe to call multiple times)
@@ -770,9 +772,8 @@ app.get('/search', async (req, ctx) => {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `sql` | `Sql<{}>` | — | **Required.** Postgres client with pgvector |
-| `embedding` | `(text) => Promise<number[]>` | — | **Required.** Embedding function |
-| `dimensions` | `number` | `1536` | Vector dimensions |
+| `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 |
@@ -780,8 +781,8 @@ app.get('/search', async (req, ctx) => {
 | `searchThreshold` | `number` | `0` | Minimum similarity (0–1) |
 
 Documents are split on paragraph boundaries (`\n\n`). Re-ingesting the same key
-replaces old chunks. The HNSW index enables fast approximate nearest-neighbor
-search (cosine distance).
+replaces old chunks. Provider's `embed()` is used automatically.
+The HNSW index enables fast approximate nearest-neighbor search (cosine distance).
 
 
 ### logdb [β]
@@ -1127,56 +1128,110 @@ await fts.dropIndex(pg.sql, articles)
 
 Search options: `fields`, `limit` (20), `offset` (0), `headline` (false), `language` ('english'), `minRank`.
 
-### preferences [α]
+### theme [α]
 
-Locale detection + theme + translations. `/__lang/:locale` and `/__theme/:theme` auto-routed.
+```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
+```
+
+| 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 |
@@ -1186,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 |
@@ -1411,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'
@@ -1449,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
@@ -1503,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 |
@@ -1517,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 |
 |--------|-------------|
@@ -1527,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
@@ -1652,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
 
@@ -1666,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 |
 
@@ -1705,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.
 
@@ -1721,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
@@ -1730,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
@@ -1789,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
 ```
 
@@ -1811,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,
@@ -1820,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
@@ -1831,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,