weifuwu 0.18.0 → 0.18.2

package/README.md

@@ -15,11 +15,14 @@ serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
 ```ts
-import { serve, Router, tsx, preferences } from 'weifuwu'
+import { serve, Router, preferences } from 'weifuwu'
+import { ssr, layout, liveReload } from 'weifuwu/ssr'
 const app = new Router()
 app.use(preferences({ dir: './locales' }))
-app.use('/', await tsx({ dir: './ui' }))
-serve(app.handler(), { port: 3000 })
+app.use(layout('./layouts/root.tsx'))
+app.get('/', ssr('./pages/home.tsx'))
+app.use(liveReload({ dirs: ['./pages', './layouts'] }))
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 ```
 
 ```bash
@@ -88,26 +91,54 @@ app.get('/admin', mw, handler)       // route-level
 
 ## Module Patterns
 
-All modules follow one of 6 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())                                    // with path
+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 can also be mounted **without a path** — internal routes (`/__xxx`) are inaccessible to the user:
+```ts
+app.use(liveReload({ dirs: ['./pages'] }))                      // no path, /__weifuwu/livereload
+```
+
+β 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, model: openai('gpt-4o'), embeddingModel: openai.embedding('text-embedding-3-small') })
 await a.migrate()
-app.use('/api', a.router())
+app.use('/api', a)
 await a.addKnowledge(agentId, 'Title', 'some knowledge content')
 a.run(agentId, { input: 'summarize the data', stream: true })
 ```
@@ -124,24 +155,30 @@ a.run(agentId, { input: 'summarize the data', stream: true })
 |--------|-------------|
 | `.run(agentId, { input, stream?, messages? })` | Execute agent with input |
 | `.addKnowledge(agentId, title, content)` | Add knowledge document |
-| `.router()` | REST + WS API |
+| `.migrate()` | DB setup |
 | `.close()` | Cleanup |
 
-### aiStream [E]
+### 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 |
@@ -154,10 +191,10 @@ 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
@@ -173,7 +210,7 @@ app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
 | `verify` | `(token, req) => object\|null` | — | Verify function, return value sets `ctx.user` |
 | `proxy` | `string` | — | Auth service URL to proxy requests to |
 
-### compress [A]
+### compress [α]
 
 ```ts
 app.use(compress())                         // brotli > gzip > deflate (min 1KB)
@@ -185,7 +222,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 [A]
+### cors [α]
 
 ```ts
 app.use(cors())                                            // allow all
@@ -203,7 +240,7 @@ app.use(cors({ credentials: true, maxAge: 3600 }))
 | `credentials` | `boolean` | `false` | Allow cookies/credentials |
 | `maxAge` | `number` | — | Preflight cache duration (seconds) |
 
-### csrf [A]
+### csrf [α]
 
 ```ts
 app.use(csrf())
@@ -234,10 +271,10 @@ const server = await deploy(config)
 // server.apps.list(), server.apps.status(name), server.apps.deploy(name)
 ```
 
-### health [D]
+### health [β]
 
 ```ts
-app.use(health({ path: '/health' }))
+app.use('/health', health())
 // Returns 200 on success, 503 when check throws
 ```
 
@@ -246,7 +283,7 @@ app.use(health({ path: '/health' }))
 | `path` | `string` | `'/health'` | Health check endpoint |
 | `check` | `() => Promise<void>` | — | Async function; throws → 503 |
 
-### helmet [A]
+### helmet [α]
 
 15 security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
 
@@ -267,12 +304,14 @@ app.use(helmet({ contentSecurityPolicy: "default-src 'self'", xFrameOptions: 'DE
 | `crossOriginOpenerPolicy` | — | COOP header |
 | `crossOriginResourcePolicy` | — | CORP header |
 
-### iii [C] — Worker / Function / Trigger
+### 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')
@@ -281,6 +320,12 @@ 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 |
@@ -289,19 +334,18 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 | `.listWorkers()` | List registered workers |
 | `.listFunctions()` | List registered functions |
 | `.listTriggers()` | List registered triggers |
-| `.router()` | REST + WS API |
 | `.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', metadata: { userId: 1 } })
 ```
@@ -317,13 +361,17 @@ await logger.log({ level: 'info', source: 'app', message: 'hello', metadata: { u
 | 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
@@ -337,25 +385,32 @@ 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) |
 
-### messager [C]
+### messager [β]
 
 Real-time chat with channels, WebSocket, agent routing.
 
 ```ts
 const msg = messager({ pg, agents, redis: redis() })
 await msg.migrate()
+app.use('/api', msg)
 app.ws('/ws', msg.wsHandler())
 await msg.send(channelId, 'System message', { sender_type: 'system', sender_id: 'bot' })
 ```
 
+| 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 |
-| `.router()` | REST API |
 | `.close()` | Cleanup |
 
-### opencode [C]
+### opencode [β]
 
 AI programming assistant.
 
@@ -367,14 +422,14 @@ const oc = await opencode({
   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())
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `pg` | `object` | — | PostgreSQL client |
-| `model` | `object` | — | AI model |
+| `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 |
@@ -382,7 +437,7 @@ app.ws('/opencode', oc.wsHandler())
 | `skills` | `object[]` | — | Custom skill definitions |
 | `permissions` | `object` | — | Tool permission rules |
 
-### postgres [B]
+### postgres [α]
 
 ```ts
 const pg = postgres()          // reads DATABASE_URL
@@ -413,7 +468,7 @@ 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.
 
@@ -444,7 +499,7 @@ const { theme, resolvedTheme, setTheme } = useTheme()
 // resolvedTheme resolves 'system' → 'dark'|'light' based on prefers-color-scheme
 ```
 
-### queue [B]
+### queue [α]
 
 ```ts
 const q = queue({ redis })
@@ -467,7 +522,7 @@ await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
 | `.stop()` | Stop processing |
 | `.close()` | Cleanup |
 
-### rateLimit [B]
+### rateLimit [α]
 
 ```ts
 app.use(rateLimit({ max: 100, window: 60_000 }))            // 100 req/min
@@ -484,7 +539,7 @@ app.use(rateLimit({ key: (req) => req.headers.get('x-api-key') ?? 'anonymous' })
 | `key` | `(req) => string` | IP-based | Key function |
 | `message` | `string` | `'Too Many Requests'` | 429 response body |
 
-### redis [B]
+### redis [α]
 
 ```ts
 const r = redis()          // reads REDIS_URL
@@ -498,7 +553,7 @@ await ctx.redis.set('key', 'value')
 | `url` | `string` | `REDIS_URL` env | Redis connection string |
 | (all ioredis options) | — | — | Passed directly to ioredis |
 
-### requestId [A]
+### requestId [α]
 
 ```ts
 app.use(requestId())
@@ -511,10 +566,106 @@ 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 |
 
-### seo [D] + seoMiddleware [A]
+---
+
+## React SSR (weifuwu/ssr)
+
+Import from `'weifuwu/ssr'`:
 
 ```ts
-app.use(seo({ baseUrl: 'https://example.com', robots: [{ userAgent: '*', allow: '/' }], sitemap: { urls: [{ loc: '/' }] } }))
+import { ssr, layout, liveReload, errorBoundary, notFound, tailwind } from 'weifuwu/ssr'
+```
+
+### ssr(path) [β]
+
+Compiles a `.tsx` file and returns a Router handler that renders the React component to HTML with streaming, client bundle injection, and context serialization.
+
+```ts
+app.get('/about', ssr('./pages/about.tsx'))
+```
+
+- Compiles via esbuild at runtime (no build step)
+- Reads `ctx.layoutStack` (set by `layout()` middleware) and wraps the component from outer to inner
+- Injects hydration script pointing to the auto-generated client bundle at `/__ssr/[hash].js`
+- Serializes middleware-injected `ctx` data to `window.__WEIFUWU_CTX` for client-side hydration
+- Dev mode: injects live reload WebSocket script
+
+### layout(path) [β]
+
+Compiles a `.tsx` file and returns middleware that pushes the layout component onto `ctx.layoutStack`. Pages rendered by `ssr()` consume this stack.
+
+```ts
+app.use(layout('./layouts/root.tsx'))       // outermost
+app.use('/blog', layout('./layouts/blog.tsx'))  // inner
+```
+
+Layout components receive `{ children }` (the child page or nested layout). Multiple layouts wrap from outer to inner in `use()` order.
+
+```tsx
+// layouts/root.tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html><head/><body><main>{children}</main></body></html>
+}
+```
+
+### liveReload(opts) [β]
+
+Returns a `Router` that registers a WebSocket endpoint at `/__weifuwu/livereload` and starts a file watcher on the given directories. When a `.tsx` file changes, it clears the compile cache and broadcasts a reload to all connected browsers.
+
+```ts
+if (process.env.NODE_ENV !== 'production') {
+  app.use(liveReload({ dirs: ['./pages', './layouts'] }))
+}
+```
+
+Mount without a path — the internal `/__weifuwu/livereload` route is invisible to the user. The `ssr()` function automatically injects the client-side WS script in dev mode.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dirs` | `string[]` | — | Directories to watch for `.tsx` changes |
+
+Returns `Router & { close: () => void }` — call `.close()` to stop the watcher.
+
+### errorBoundary(path) [β]
+
+Wraps child routes in an error boundary. If a page or middleware throws, the error component is rendered instead.
+
+```ts
+app.use('/blog', errorBoundary('./blog-error.tsx'))
+```
+
+The error component receives `{ error, reset }` as props:
+
+```tsx
+export default function BlogError({ error, reset }: { error: Error; reset: () => void }) {
+  return <div><h2>Error</h2><p>{error.message}</p></div>
+}
+```
+
+Error boundaries nest — the nearest one up the middleware chain catches the error.
+
+### notFound(path) [β]
+
+Returns a catch-all handler for 404 pages. Typically registered last:
+
+```ts
+app.all('/*', notFound('./not-found.tsx'))
+```
+
+### tailwind(path) [α]
+
+Compiles Tailwind CSS v4 via `@tailwindcss/postcss` and serves it at `/__wfw/style.css`. In dev mode, watches the CSS file for changes.
+
+```ts
+app.use(tailwind('./app.css'))
+```
+
+When `tailwind()` middleware is detected, `ssr()` automatically injects `<link rel="stylesheet" href="/__wfw/style.css" />` into the HTML `<head>`.
+
+### seo [β] + seoMiddleware [α]
+
+```ts
+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 } }))
@@ -522,7 +673,14 @@ app.use(seoMiddleware({ headers: { 'X-Robots-Tag': (path) => path.startsWith('/a
 
 Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML string.
 
-### tenant [C]
+| 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.
 
@@ -530,11 +688,16 @@ 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, allowedTypes: ['image/jpeg', 'image/png'] }), (req, ctx) => {
@@ -550,14 +713,14 @@ app.post('/upload', upload({ dir: './uploads', maxFileSize: 10_485_760, allowedT
 | `maxFileSize` | `number` | — | Max bytes per file |
 | `allowedTypes` | `string[]` | — | Allowed MIME types |
 
-### user [C]
+### 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, OAuth2 routes
+app.use('/auth', auth)               // POST /register, POST /login, OAuth2 routes
 app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 ```
 
@@ -574,10 +737,9 @@ app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 | `.register(data)` | Register a new user programmatically |
 | `.login(data)` | Log in programmatically |
 | `.verify(token)` | Verify JWT token |
-| `.router()` | REST routes (register, login, OAuth2) |
 | `.middleware()` | JWT verify middleware — sets `ctx.user` |
 
-### validate [A]
+### validate [α]
 
 ```ts
 import { z } from 'zod'
@@ -590,58 +752,6 @@ app.post('/users', validate({ body: CreateUser, query: z.object({ ref: z.string(
 })
 // Validation failure: returns 400 with { error: 'Validation failed', issues: [...] }
 ```
-
----
-
-## React SSR (tsx)
-
-```ts
-app.use('/', await tsx({ dir: './ui/' }))
-```
-
-```
-ui/
-├── pages/
-│   ├── page.tsx          → GET /
-│   ├── layout.tsx        → root layout
-│   ├── not-found.tsx     → 404
-│   ├── about/page.tsx    → GET /about
-│   ├── blog/[slug]/
-│   │   ├── page.tsx      → GET /blog/:slug
-│   │   ├── load.ts       → server data fetching
-│   │   └── route.ts      → API (named exports: POST, PUT...)
-│   ├── blog/layout.tsx   → nested layout
-│   └── api/search/
-│       └── route.ts      → GET /api/search
-└── components/
-```
-
-```tsx
-// page.tsx
-export default function Page() {
-  const { t } = useLocale()
-  const data = useLoaderData()
-  return <h1>{t('title') ?? data.title}</h1>
-}
-```
-
-```tsx
-// layout.tsx
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return <html><head/><body><main>{children}</main></body></html>
-}
-```
-
-```ts
-// load.ts — server-only data fetching
-export default async function load({ params, query }) { return { data: await db.query(params.slug) } }
-```
-
-```ts
-// route.ts — API co-located with page
-export const POST: Handler = async (req, ctx) => Response.json({ slug: ctx.params.slug })
-```
-
 ### Client-side navigation
 
 ```tsx
@@ -652,7 +762,7 @@ const navigate = useNavigate()               // programmatic: navigate('/contact
 const loading = useNavigating()              // reactive loading state
 ```
 
-`navigate()` fetches SSR, extracts `__weifuwu_root`, replaces in-place. `load.ts` runs on server each nav.
+`navigate()` fetches SSR, extracts `__weifuwu_root`, replaces 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.
 
@@ -737,16 +847,18 @@ function ThemeToggle() {
 
 **`applyTheme(theme)`** — DOM-only theme application. Sets `data-theme` on `<html>`, registers `matchMedia` listener for `'system'`. Used by the interceptor; exported for custom scenarios.
 
-**`useLoaderData()`** — Returns the data returned by `load.ts`. Update-triggered; re-renders on SPA navigation.
+**`useLoaderData()`** — Returns middleware-injected data from the request context. Works identically on server (SSR) and client (hydration/SPA). Re-renders on SPA navigation.
 
 ```tsx
 import { useLoaderData } from 'weifuwu/react'
 function Page() {
-  const data = useLoaderData<{ post: { title: string } }>()
-  return <h1>{data.post.title}</h1>
+  const data = useLoaderData<{ posts: Post[] }>()
+  return <ul>{data.posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
 }
 ```
 
+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.
+
 **`addInterceptor(fn)`** — Register a URL interceptor. Interceptors run before SPA navigation; if one returns `true`, `navigate()` skips the fetch-and-swap.
 
 ```ts
@@ -778,7 +890,19 @@ function Toast() {
 
 ### Dev mode
 
-Auto-detected when `NODE_ENV !== 'production'`. File watching, live reload, Tailwind v4 auto-compile.
+Auto-detected when `NODE_ENV !== 'production'`. File watching + live reload via `liveReload()`:
+
+```ts
+import { liveReload } from 'weifuwu/ssr'
+
+if (process.env.NODE_ENV !== 'production') {
+  app.use(liveReload({ dirs: ['./pages', './layouts'] }))
+}
+```
+
+When a `.tsx` file changes, `ssr()` clears its compile cache and the browser auto-refreshes. No process restart needed.
+
+Tailwind v4 auto-compile via `tailwind()` middleware:
 
 ---
 
@@ -789,21 +913,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