weifuwu 0.17.25 → 0.18.0

package/README.md

@@ -88,7 +88,7 @@ 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 6 patterns. The pattern letter is marked in each module's heading.
 
 | Pattern | How to mount | Example |
 |---------|-------------|---------|
@@ -105,13 +105,28 @@ All modules follow one of 5 patterns. The pattern letter is marked in each modul
 ### agent [C]
 
 ```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' })
+await a.addKnowledge(agentId, 'Title', 'some knowledge content')
+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 |
+| `tools` | `object[]` | — | Custom tool definitions |
+
+| Method | Description |
+|--------|-------------|
+| `.run(agentId, { input, stream?, messages? })` | Execute agent with input |
+| `.addKnowledge(agentId, title, content)` | Add knowledge document |
+| `.router()` | REST + WS API |
+| `.close()` | Cleanup |
+
 ### aiStream [E]
 
 ```ts
@@ -147,17 +162,29 @@ app.use('/', a.router())
 ```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)
 ```
 
+| 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 [A]
 
 ```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
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number` | `1024` | Minimum byte size to compress |
+| `level` | `number` | `6` | Compression level (zlib) |
+
 ### cors [A]
 
 ```ts
@@ -167,18 +194,28 @@ app.use(cors({ origin: (o) => o.endsWith('.trusted.com') && o }))
 app.use(cors({ credentials: true, maxAge: 3600 }))
 ```
 
+| 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 [A]
 
 ```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 +223,57 @@ 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]
 
 ```ts
-app.use(health())                         // GET /health → 200
-app.use(health({ checks: { db: async () => { await pg.sql`SELECT 1`; return { ok: true } } } }))
+app.use(health({ path: '/health' }))
+// Returns 200 on success, 503 when check throws
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | `'/health'` | Health check endpoint |
+| `check` | `() => Promise<void>` | — | Async function; throws → 503 |
+
 ### helmet [A]
 
-13 security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
+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' }))
 ```
 
+| 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 [C] — Worker / Function / Trigger
 
 ```ts
+import { createWorker } from 'weifuwu'
 const engine = iii({ pg, redis })
 app.use('/iii', engine.router())
+app.ws('/iii', engine.wsHandler())
 
 const w = createWorker('orders')
 w.registerFunction('orders::create', async (payload) => db.query('INSERT INTO orders ...', [payload.items]))
@@ -221,8 +284,15 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 | Method | Description |
 |--------|-------------|
 | `.addWorker(w)` | Register a worker |
-| `.trigger({ function_id, payload, action? })` | Invoke a function (sync or void) |
+| `.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 |
 | `.router()` | REST + WS API |
+| `.wsHandler()` | WebSocket handler |
+| `.migrate()` | DB setup |
+| `.shutdown()` | Clean shutdown |
 
 ### logdb [C]
 
@@ -233,9 +303,14 @@ const logger = logdb({ pg })
 await logger.migrate()
 app.use('/logs', logger.router())
 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 |
@@ -252,10 +327,16 @@ app.use(logger({ format: 'combined' }))       // with 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' })
 ```
 
+| 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 [C]
 
 Real-time chat with channels, WebSocket, agent routing.
@@ -263,21 +344,44 @@ 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.ws('/ws', msg.wsHandler())
+await msg.send(channelId, 'System message', { sender_type: 'system', sender_id: 'bot' })
 ```
 
+| Method | Description |
+|--------|-------------|
+| `.wsHandler()` | WebSocket handler (channels, typing, read receipts) |
+| `.send(channel, content, opts?)` | Send message to channel |
+| `.router()` | REST API |
+| `.close()` | Cleanup |
+
 ### opencode [C]
 
 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.ws('/opencode', oc.wsHandler())
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `object` | — | PostgreSQL client |
+| `model` | `object` | — | AI model |
+| `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 [B]
 
 ```ts
@@ -285,6 +389,14 @@ 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() })
@@ -308,6 +420,7 @@ Locale detection + theme + translations. `/__lang/:locale` and `/__theme/:theme`
 ```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
 ```
@@ -335,34 +448,69 @@ const { theme, resolvedTheme, setTheme } = useTheme()
 
 ```ts
 const q = queue({ redis })
+app.use(q)                     // injects ctx.queue
 await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
 ```
 
+| 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 [B]
 
 ```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
 ```
 
+| 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 [B]
 
 ```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
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | `REDIS_URL` env | Redis connection string |
+| (all ioredis options) | — | — | Passed directly to ioredis |
+
 ### requestId [A]
 
 ```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
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `header` | `string` | `'X-Request-ID'` | Header name to read/write |
+| `generator` | `() => string` | `crypto.randomUUID()` | ID generator |
+
 ### seo [D] + seoMiddleware [A]
 
 ```ts
@@ -372,6 +520,8 @@ app.use(seo({ baseUrl: 'https://example.com', robots: [{ userAgent: '*', allow:
 app.use(seoMiddleware({ headers: { 'X-Robots-Tag': (path) => path.startsWith('/admin') ? 'noindex' : undefined } }))
 ```
 
+Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML string.
+
 ### tenant [C]
 
 Multi-tenant BaaS with dynamic table API and GraphQL.
@@ -387,29 +537,58 @@ app.use('/graphql', t.graphql()) // dynamic GraphQL
 ### upload [A]
 
 ```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'
 })
 ```
 
+| 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 [C]
 
+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.router())               // POST /register, POST /login, OAuth2 routes
 app.get('/me', auth.middleware(), (req, ctx) => Response.json(ctx.user))
 ```
 
+| 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 |
+| `.router()` | REST routes (register, login, OAuth2) |
+| `.middleware()` | JWT verify middleware — sets `ctx.user` |
+
 ### validate [A]
 
 ```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: [...] }
 ```
 
 ---
@@ -439,15 +618,16 @@ ui/
 
 ```tsx
 // page.tsx
-export default function Page({ params, query }: { params: { slug: string }; query: Record<string, string> }) {
-  const { t } = useCtx()
-  return <h1>{t('title')}</h1>
+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, req }: { children: React.ReactNode; req: Request }) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return <html><head/><body><main>{children}</main></body></html>
 }
 ```
@@ -479,18 +659,28 @@ const loading = useNavigating()              // reactive loading state
 ### Client-side hooks
 
 ```tsx
-import { useWebsocket, useAction, useData, useQueryState, createStore, Head, setCtx } from 'weifuwu/react'
-import { useLocale, useTheme, applyTheme, addInterceptor } from 'weifuwu/react'
+import { useWebsocket, useAction, useFetch, useQueryState, createStore, Head } 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 } = useData('/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', '')
@@ -502,11 +692,10 @@ const count = useStore(s => s.count)
 
 // Per-page meta tags
 <Head><title>Page Title</title><meta name="description" content="..." /></Head>
-
-// Update context (locale switch etc.)
-setCtx({ locale: 'en', prefs: { locale: 'en' } })
 ```
 
+**`TsxContext`** — React context holding page data (`params`, `query`, `user`, `parsed`, `prefs`, `env`). Used internally by hooks; rarely needed directly.
+
 ### Locale & Theme
 
 ```tsx
@@ -521,7 +710,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'
@@ -548,6 +737,16 @@ 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.
+
+```tsx
+import { useLoaderData } from 'weifuwu/react'
+function Page() {
+  const data = useLoaderData<{ post: { title: string } }>()
+  return <h1>{data.post.title}</h1>
+}
+```
+
 **`addInterceptor(fn)`** — Register a URL interceptor. Interceptors run before SPA navigation; if one returns `true`, `navigate()` skips the fetch-and-swap.
 
 ```ts
@@ -562,11 +761,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

package/cli.ts

@@ -70,6 +70,10 @@ async function cmdInit(name: string) {
     '',
     'This is a [weifuwu](https://weifuwu.io) HTTP application — pure Node.js, no build step.',
     '',
+    '## Before you start',
+    '',
+    'Read `node_modules/weifuwu/README.md` first. Understand every module and API before writing any code. The weifuwu framework has its own patterns, types, and conventions — do not guess or assume.',
+    '',
     '## Commands',
     '',
     '- `npm run dev` — start dev server with `--watch`',

package/dist/cli.js

@@ -61,6 +61,10 @@ async function cmdInit(name) {
     "",
     "This is a [weifuwu](https://weifuwu.io) HTTP application \u2014 pure Node.js, no build step.",
     "",
+    "## Before you start",
+    "",
+    "Read `node_modules/weifuwu/README.md` first. Understand every module and API before writing any code. The weifuwu framework has its own patterns, types, and conventions \u2014 do not guess or assume.",
+    "",
     "## Commands",
     "",
     "- `npm run dev` \u2014 start dev server with `--watch`",

package/dist/client-state.d.ts

@@ -7,16 +7,16 @@ export interface StoreApi<T> {
     subscribe: (listener: () => void) => () => void;
 }
 export declare function createStore<T extends Record<string, unknown>>(initial: T): StoreApi<T>;
-interface UseDataResult<T> {
+interface UseFetchResult<T> {
     data: T | undefined;
     error: Error | undefined;
     loading: boolean;
     mutate: (data?: T) => Promise<void>;
 }
-interface UseDataOptions<T> {
+interface UseFetchOptions<T> {
     fallback?: T;
     ttl?: number;
 }
-export declare function useData<T = unknown>(url: string | null, options?: UseDataOptions<T>): UseDataResult<T>;
+export declare function useFetch<T = unknown>(url: string | null, options?: UseFetchOptions<T>): UseFetchResult<T>;
 export declare function useQueryState(key: string, defaultValue?: string): [string, (val: string | ((prev: string) => string)) => void];
 export {};

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { serve, createTestServer } from './serve.ts';
 export type { ServeOptions, Server } from './serve.ts';
 export { Router } from './router.ts';
 export type { WebSocketHandler } from './router.ts';
-export { tsx, TsxContext, useCtx, setCtx } from './tsx.ts';
+export { tsx, TsxContext } from './tsx.ts';
 export type { TsxOptions } from './tsx.ts';
 export { auth, cors, logger } from './middleware.ts';
 export type { AuthOptions, CORSOptions, LoggerOptions } from './middleware.ts';

package/dist/index.js

@@ -575,9 +575,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import chokidar from "chokidar";
 
 // tsx-context.ts
-import { useSyncExternalStore, createContext } from "react";
-var fallbackT = (key, _params, fallback) => fallback ?? key;
-var DEFAULT_CTX = { params: {}, query: {}, parsed: {}, prefs: {}, env: {}, t: fallbackT, user: {} };
+import { createContext } from "react";
+var DEFAULT_CTX = { params: {}, query: {}, parsed: {}, prefs: {}, loaderData: {}, env: {}, user: {} };
 var KEY = "__WEIFUWU_CTX_STORE";
 function getStore() {
   if (typeof globalThis !== "undefined" && globalThis[KEY]) {
@@ -595,14 +594,6 @@ function getStore() {
   return s;
 }
 var store = getStore();
-var subscribe = (cb) => {
-  store._listeners.add(cb);
-  return () => {
-    store._listeners.delete(cb);
-  };
-};
-var getSnapshot = () => store._snapshot;
-var getServerSnapshot = getSnapshot;
 function __registerAls(getStore2) {
   store._alsGetStore = getStore2;
 }
@@ -611,28 +602,6 @@ function setCtx(value) {
   store._snapshot = { params: store._ctx.params, query: store._ctx.query, user: store._ctx.user, parsed: store._ctx.parsed, prefs: store._ctx.prefs, env: store._ctx.env };
   store._listeners.forEach((fn) => fn());
 }
-function _buildT() {
-  const messages2 = typeof window !== "undefined" ? window.__LOCALE_DATA__ : globalThis.__LOCALE_DATA__;
-  if (!messages2) return fallbackT;
-  return (key, params, fallback) => {
-    const msg = key.split(".").reduce((o, k) => o?.[k], messages2);
-    if (msg === void 0 || msg === null) return fallback ?? key;
-    if (!params) return String(msg);
-    let result = String(msg);
-    for (const [k, v] of Object.entries(params)) result = result.replace(`{${k}}`, v);
-    return result;
-  };
-}
-function _readCtx() {
-  const alsStore = store._alsGetStore?.();
-  const base = alsStore ?? store._ctx;
-  const data = typeof window !== "undefined" ? window.__WEIFUWU_CTX : null;
-  return { ...base, ...data, t: _buildT() };
-}
-function useCtx() {
-  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-  return _readCtx();
-}
 var TsxContext = createContext(DEFAULT_CTX);
 
 // tsx-instance.ts
@@ -929,7 +898,7 @@ var TsxInstance = class {
           user: ctx.user ?? {},
           parsed: ctx.parsed ?? {},
           prefs: ctx.prefs ?? {},
-          t: ctx.t ?? ((key) => key),
+          loaderData: {},
           env: ctx.env ?? {}
         };
         return als.run(ctxValue, async () => {
@@ -1032,24 +1001,27 @@ ${src}`;
   async buildClientBundle(entryPath, layoutPaths, pagesDir) {
     try {
       const layoutImports = layoutPaths.map((p) => `import${JSON.stringify(p)};`).join("");
+      const _sc = `(function(){var k='__WEIFUWU_CTX_STORE';var s=typeof globalThis!='undefined'&&globalThis[k];if(!s)return function(){};return function(v){s._ctx={...s._ctx,...v};s._snapshot={params:s._ctx.params,query:s._ctx.query,user:s._ctx.user,parsed:s._ctx.parsed,prefs:s._ctx.prefs,env:s._ctx.env};s._listeners.forEach(function(fn){fn()})}})()`;
       const code = [
         layoutImports,
         `import{hydrateRoot}from'react-dom/client';`,
         `import{createElement,useState,useEffect}from'react';`,
         `import{TsxContext}from'weifuwu/react';`,
         `import P from${JSON.stringify(entryPath)};`,
+        `var setCtx=${_sc};`,
         `const c=document.getElementById('__weifuwu_root');`,
+        `if(window.__WEIFUWU_PROPS)setCtx({loaderData:window.__WEIFUWU_PROPS});`,
         `if(!window.__WFW_ROOT){`,
         `function App(){`,
-        `const[p,setP]=useState({C:P,props:window.__WEIFUWU_PROPS});`,
-        `useEffect(()=>{window.__WFW_SET_PAGE=(C,props)=>setP({C,props})},[]);`,
-        `const ctx=window.__WEIFUWU_CTX||{params:{},query:{}};`,
+        `const[p,setP]=useState({C:P});`,
+        `useEffect(()=>{window.__WFW_SET_PAGE=(C)=>{setCtx({loaderData:window.__WEIFUWU_PROPS});setP({C})}},[]);`,
+        `const ctx=window.__WEIFUWU_CTX||{};`,
         `return createElement(TsxContext.Provider,{value:ctx},`,
-        `createElement(p.C,p.props))`,
+        `createElement(p.C,null))`,
         `}`,
         `window.__WFW_ROOT=hydrateRoot(c,createElement(App));`,
         `}else{`,
-        `window.__WFW_SET_PAGE?.(P,window.__WEIFUWU_PROPS);`,
+        `window.__WFW_SET_PAGE?.(P);`,
         `}`
       ].join("");
       const publicEnv = {};
@@ -1119,28 +1091,27 @@ ${src}`;
       const pageMod = this.pageModules.get(entryPath);
       if (!pageMod) return new Response("", { status: 500 });
       const Component = pageMod.default;
+      const loadMod = loadPath ? this.loadModules.get(loadPath) : void 0;
+      const loadFn = loadMod?.default;
+      const loadProps = loadFn ? await loadFn({ params: ctx.params, query: ctx.query }) : {};
       const ctxValue = {
         params: ctx.params,
         query: ctx.query,
         user: ctx.user ?? {},
         parsed: ctx.parsed ?? {},
         prefs: ctx.prefs ?? {},
-        t: ctx.t ?? ((key) => key),
+        loaderData: loadProps,
         env: ctx.env ?? {}
       };
       return als.run(ctxValue, async () => {
         setCtx(ctxValue);
-        const loadMod = loadPath ? this.loadModules.get(loadPath) : void 0;
-        const loadFn = loadMod?.default;
-        const loadProps = loadFn ? await loadFn({ params: ctx.params, query: ctx.query }) : {};
-        const allProps = { ...loadProps, params: ctx.params, query: ctx.query };
         let element = createElement(
           TsxContext.Provider,
           { value: ctxValue },
           createElement(
             "div",
             { id: "__weifuwu_root" },
-            createElement(Component, allProps)
+            createElement(Component, null)
           )
         );
         if (layoutPaths.length === 0) {
@@ -1165,7 +1136,7 @@ ${src}`;
             const isRoot = i === 0;
             element = createElement(
               Layout,
-              isRoot ? { children: element, req } : { children: element }
+              { children: element }
             );
           }
         }
@@ -1177,7 +1148,7 @@ ${src}`;
           compiledTailwindCss: this.compiledTailwindCss,
           isDev,
           bundle,
-          allProps
+          loaderData: loadProps
         });
       });
     };
@@ -1456,12 +1427,13 @@ function buildHeadPayload(opts) {
   return result;
 }
 function buildBodyScripts(opts) {
-  if (!opts.bundle) return "";
   const parts = [];
-  if (opts.allProps) {
-    parts.push(`<script>window.__WEIFUWU_PROPS=${JSON.stringify(opts.allProps)}</script>`);
+  if (opts.loaderData && Object.keys(opts.loaderData).length > 0) {
+    parts.push(`<script>window.__WEIFUWU_PROPS=${JSON.stringify(opts.loaderData)}</script>`);
+  }
+  if (opts.bundle) {
+    parts.push(`<script type="module" src="${opts.base}${opts.bundle.url}"></script>`);
   }
-  parts.push(`<script type="module" src="${opts.base}${opts.bundle.url}"></script>`);
   return parts.join("\n");
 }
 
@@ -8665,7 +8637,6 @@ export {
   serve,
   serveStatic,
   setCookie,
-  setCtx,
   smoothStream,
   streamObject,
   streamText,
@@ -8673,7 +8644,6 @@ export {
   tool2 as tool,
   tsx,
   upload,
-  useCtx,
   user,
   validate
 };

package/dist/react.d.ts

@@ -3,9 +3,10 @@ export type { UseWebsocketOptions, UseWebsocketReturn } from './use-websocket.ts
 export { useAction } from './use-action.ts';
 export type { UseActionOptions, UseActionReturn } from './use-action.ts';
 export { Link, useNavigate, navigate, useNavigating, addInterceptor } from './client-router.ts';
-export { TsxContext, useCtx, setCtx } from './tsx-context.ts';
+export { TsxContext, useLoaderData } from './tsx-context.ts';
 export { Head } from './head.tsx';
-export { createStore, useData, useQueryState } from './client-state.ts';
+export { createStore, useFetch, useQueryState } from './client-state.ts';
 export type { StoreApi } from './client-state.ts';
 export { useLocale } from './client-locale.ts';
 export { useTheme, applyTheme } from './client-theme.ts';
+export { useFlashMessage } from './use-flash-message.ts';

package/dist/react.js

@@ -331,9 +331,8 @@ async function prefetchPage(href) {
 }
 
 // tsx-context.ts
-import { useSyncExternalStore, createContext } from "react";
-var fallbackT = (key, _params, fallback) => fallback ?? key;
-var DEFAULT_CTX = { params: {}, query: {}, parsed: {}, prefs: {}, env: {}, t: fallbackT, user: {} };
+import { createContext } from "react";
+var DEFAULT_CTX = { params: {}, query: {}, parsed: {}, prefs: {}, loaderData: {}, env: {}, user: {} };
 var KEY = "__WEIFUWU_CTX_STORE";
 function getStore() {
   if (typeof globalThis !== "undefined" && globalThis[KEY]) {
@@ -351,40 +350,22 @@ function getStore() {
   return s;
 }
 var store = getStore();
-var subscribe = (cb) => {
-  store._listeners.add(cb);
-  return () => {
-    store._listeners.delete(cb);
-  };
-};
-var getSnapshot = () => store._snapshot;
-var getServerSnapshot = getSnapshot;
 function setCtx(value) {
   store._ctx = { ...store._ctx, ...value };
   store._snapshot = { params: store._ctx.params, query: store._ctx.query, user: store._ctx.user, parsed: store._ctx.parsed, prefs: store._ctx.prefs, env: store._ctx.env };
   store._listeners.forEach((fn) => fn());
 }
-function _buildT() {
-  const messages = typeof window !== "undefined" ? window.__LOCALE_DATA__ : globalThis.__LOCALE_DATA__;
-  if (!messages) return fallbackT;
-  return (key, params, fallback) => {
-    const msg = key.split(".").reduce((o, k) => o?.[k], messages);
-    if (msg === void 0 || msg === null) return fallback ?? key;
-    if (!params) return String(msg);
-    let result = String(msg);
-    for (const [k, v] of Object.entries(params)) result = result.replace(`{${k}}`, v);
-    return result;
-  };
-}
-function _readCtx() {
+function useCtx() {
   const alsStore = store._alsGetStore?.();
   const base = alsStore ?? store._ctx;
   const data = typeof window !== "undefined" ? window.__WEIFUWU_CTX : null;
-  return { ...base, ...data, t: _buildT() };
+  return { ...base, ...data };
 }
-function useCtx() {
-  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-  return _readCtx();
+function useLoaderData() {
+  const alsStore = store._alsGetStore?.();
+  const base = alsStore ?? store._ctx;
+  const data = typeof window !== "undefined" ? window.__WEIFUWU_CTX : null;
+  return { ...base, ...data }.loaderData;
 }
 var TsxContext = createContext(DEFAULT_CTX);
 
@@ -405,25 +386,25 @@ function createStore(initial) {
     state = { ...state, ...next };
     listeners.forEach((fn) => fn());
   };
-  const subscribe2 = (listener) => {
+  const subscribe = (listener) => {
     listeners.add(listener);
     return () => {
       listeners.delete(listener);
     };
   };
   const useStore = ((selector) => useSyncExternalStore2(
-    subscribe2,
+    subscribe,
     () => selector ? selector(state) : state
   ));
   useStore.getState = getState;
   useStore.setState = setState;
-  useStore.subscribe = subscribe2;
+  useStore.subscribe = subscribe;
   return useStore;
 }
 var dataCache = /* @__PURE__ */ new Map();
 var inflight = /* @__PURE__ */ new Map();
 var CACHE_TTL = 6e4;
-function useData(url, options) {
+function useFetch(url, options) {
   const ttl = options?.ttl ?? CACHE_TTL;
   const [state, setState] = useState4({
     data: options?.fallback,
@@ -497,7 +478,7 @@ function notifyQueryListeners() {
   window.dispatchEvent(new PopStateEvent("popstate"));
 }
 function useQueryState(key, defaultValue = "") {
-  function getSnapshot2() {
+  function getSnapshot() {
     if (typeof window === "undefined") return defaultValue;
     const params = new URLSearchParams(window.location.search);
     return params.get(key) ?? defaultValue;
@@ -509,12 +490,12 @@ function useQueryState(key, defaultValue = "") {
       window.addEventListener("popstate", cb);
       return () => window.removeEventListener("popstate", cb);
     },
-    getSnapshot2,
+    getSnapshot,
     () => defaultValue
   );
   const setValue = useCallback4((val) => {
     if (typeof window === "undefined") return;
-    const resolved = typeof val === "function" ? val(getSnapshot2()) : val;
+    const resolved = typeof val === "function" ? val(getSnapshot()) : val;
     const url = new URL(window.location.href);
     if (resolved === defaultValue || resolved === "") {
       url.searchParams.delete(key);
@@ -528,6 +509,18 @@ function useQueryState(key, defaultValue = "") {
 }
 
 // client-locale.ts
+function buildT() {
+  const messages = typeof window !== "undefined" ? window.__LOCALE_DATA__ : globalThis.__LOCALE_DATA__;
+  if (!messages) return (key, _p, fb) => fb ?? key;
+  return (key, params, fallback) => {
+    const msg = key.split(".").reduce((o, k) => o?.[k], messages);
+    if (msg === void 0 || msg === null) return fallback ?? key;
+    if (!params) return String(msg);
+    let result = String(msg);
+    for (const [k, v] of Object.entries(params)) result = result.replace(`{${k}}`, v);
+    return result;
+  };
+}
 addInterceptor(async (url) => {
   const m = url.pathname.match(/^\/__lang\/(\w+)$/);
   if (!m) return false;
@@ -551,11 +544,12 @@ function useLocale() {
   return {
     locale: ctx.prefs.locale,
     setLocale: (locale) => navigate("/__lang/" + locale),
-    t: ctx.t
+    t: buildT()
   };
 }
 
 // client-theme.ts
+import { useEffect as useEffect4 } from "react";
 function resolveTheme(theme) {
   if (theme === "system") {
     if (typeof window === "undefined") return "light";
@@ -601,12 +595,27 @@ addInterceptor(async (url) => {
 function useTheme() {
   const ctx = useCtx();
   const theme = ctx.prefs.theme ?? "system";
+  useEffect4(() => {
+    applyTheme(theme);
+  }, [theme]);
   return {
     theme,
     resolvedTheme: resolveTheme(theme),
     setTheme: (t) => navigate("/__theme/" + t)
   };
 }
+
+// use-flash-message.ts
+import { useState as useState5 } from "react";
+function useFlashMessage() {
+  const [flash] = useState5(() => {
+    if (typeof window === "undefined") return null;
+    const raw = window.__WEIFUWU_CTX?.prefs?.flash;
+    if (!raw) return null;
+    return typeof raw === "string" ? JSON.parse(raw) : raw;
+  });
+  return flash;
+}
 export {
   Head,
   Link,
@@ -615,10 +624,10 @@ export {
   applyTheme,
   createStore,
   navigate,
-  setCtx,
   useAction,
-  useCtx,
-  useData,
+  useFetch,
+  useFlashMessage,
+  useLoaderData,
   useLocale,
   useNavigate,
   useNavigating,

package/dist/tsx-context.d.ts

@@ -1,4 +1,4 @@
-export interface CtxValue {
+export interface PageContext {
     params: Record<string, string>;
     query: Record<string, string>;
     user: {
@@ -6,11 +6,13 @@ export interface CtxValue {
     };
     parsed: Record<string, unknown>;
     prefs: Record<string, string>;
-    t: (key: string, params?: Record<string, string>, fallback?: string) => string;
+    loaderData: Record<string, unknown>;
     env: Record<string, string>;
 }
 /** @internal Injected by tsx-instance.ts for async-safe context isolation */
-export declare function __registerAls(getStore: () => CtxValue | undefined): void;
-export declare function setCtx(value: Partial<CtxValue>): void;
-export declare function useCtx(): CtxValue;
-export declare const TsxContext: import("react").Context<CtxValue>;
+export declare function __registerAls(getStore: () => PageContext | undefined): void;
+declare function setCtx(value: Partial<PageContext>): void;
+declare function useCtx(): PageContext;
+export declare function useLoaderData<T = Record<string, unknown>>(): T;
+export declare const TsxContext: import("react").Context<PageContext>;
+export { useCtx, setCtx };

package/dist/tsx-instance.d.ts

@@ -1,6 +1,6 @@
 import { Router } from './router.ts';
-import { TsxContext, useCtx, setCtx } from './tsx-context.ts';
-export { TsxContext, useCtx, setCtx };
+import { TsxContext } from './tsx-context.ts';
+export { TsxContext };
 export interface TsxOptions {
     dir: string;
 }

package/dist/tsx.d.ts

@@ -1,7 +1,7 @@
-import { TsxContext, useCtx, setCtx } from './tsx-instance.ts';
+import { TsxContext } from './tsx-instance.ts';
 import type { TsxOptions } from './tsx-instance.ts';
 import type { Router } from './router.ts';
-export { TsxContext, useCtx, setCtx };
+export { TsxContext };
 export type { TsxOptions };
 export declare function tsx(options: TsxOptions): Promise<Router & {
     stop: () => void;

package/dist/types.d.ts

@@ -4,12 +4,9 @@ export interface Context {
     user?: unknown;
     parsed?: Record<string, unknown>;
     mountPath?: string;
-    locale?: string;
     t?: (key: string, params?: Record<string, string>, fallback?: string) => string;
-    requestId?: string;
-    prefs?: Record<string, string>;
-    theme?: string;
     setPref?: (name: string, value: string) => Response;
+    prefs?: Record<string, string>;
     env?: Record<string, string>;
 }
 export type Handler = (req: Request, ctx: Context) => Response | Promise<Response>;

package/dist/use-flash-message.d.ts

@@ -0,0 +1 @@
+export declare function useFlashMessage<T = any>(): T | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weifuwu",
-  "version": "0.17.25",
+  "version": "0.18.0",
   "description": "Web-standard HTTP framework for Node.js — (req, ctx) => Response",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",