weifuwu 0.19.4 → 0.19.6

package/README.md

@@ -15,12 +15,11 @@ serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
 ```ts
-import { serve, Router, preferences, ssr, layout, liveReload } from 'weifuwu'
+import { serve, Router, preferences, ssr, rootLayout } from 'weifuwu'
 const app = new Router()
 app.use(preferences({ dir: './locales' }))
-app.use(layout('./layouts/root.tsx'))
-app.get('/', ssr('./pages/home.tsx'))
-app.use(liveReload({ dirs: ['./pages', './layouts'] }))
+app.use(rootLayout('./ui'))
+app.get('/', ssr('./ui/pages/home.tsx'))
 serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 ```
 
@@ -77,6 +76,23 @@ serve(handler, { port: 3000, websocket: wsHandler })
 
 Query params → `ctx.query`.
 
+### Request lifecycle
+
+```
+Request → serve() → app.handler() → global middleware × N → path middleware × N → route handler → Response
+                                                                      ↑
+                                                              mountPath set by sub-router
+```
+
+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()`)
+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
+
+Sub-routers (`app.use('/admin', adminRouter)`) are **flattened** into the parent trie. The sub-router's global middleware merges with the parent's. `ctx.mountPath` is set when entering a sub-router, allowing each module to derive its own paths.
+
 ### Middleware
 
 ```ts
@@ -86,6 +102,32 @@ app.use('/admin', mw)                // path-scoped
 app.get('/admin', mw, handler)       // route-level
 ```
 
+### Context
+
+The `ctx` object accumulates properties as it passes through the middleware chain. Below are all documented properties:
+
+| Property | Set by | Type | Description |
+|----------|--------|------|-------------|
+| `params` | Router | `Record<string, string>` | URL path parameters |
+| `query` | Router | `Record<string, string>` | URL query parameters |
+| `mountPath` | Router | `string` | Current sub-router mount prefix |
+| `env` | `loadEnv()` | `Record<string, string>` | Public env vars (`WEIFUWU_PUBLIC_*`) |
+| `csrfToken` | `csrf()` | `string` | CSRF token |
+| `requestId` | `requestId()` | `string` | Request ID |
+| `sql` | `postgres()` | `Sql<{}>` | PostgreSQL tagged-template client |
+| `redis` | `redis()` | `Redis` | Redis client |
+| `queue` | `queue()` | `Queue` | Job queue |
+| `prefs` | `preferences()` | `{ locale, theme }` | User preferences (locale, theme) |
+| `deploy` | `deploy()` | `{ appName? }` | Deploy gateway info |
+| `layoutStack` | `rootLayout()` / `layout()` | `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` | `tailwind()` | `string` | Compiled CSS content (internal) |
+| `tailwindCssUrl` | `tailwind()` | `string` | Compiled CSS route URL (internal) |
+
 ---
 
 ## Module Patterns
@@ -116,11 +158,6 @@ app.use('/auth', user({ pg, jwtSecret }))                       // with .middlew
 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()
@@ -255,21 +292,130 @@ app.use(csrf())
 | `key` | `'_csrf'` | Body field fallback |
 | `excludeMethods` | `['GET','HEAD','OPTIONS']` | Skip validation |
 
-### deploy
+### deploy [β]
+
+Multi-process manager with reverse proxy, health checks, auto-restart, and zero-downtime updates. Works identically locally and in production.
 
 ```ts
 import { deploy, defineConfig } from 'weifuwu'
-const config = defineConfig({
+
+// Local
+await deploy(defineConfig({
+  apps: { blog: {}, api: {} },
+}))
+
+// Production
+await deploy(defineConfig({
   domain: 'example.com',
+  deployToken: process.env.DEPLOY_TOKEN,
+  apps: { blog: {}, api: {} },
+}))
+```
+
+**Auto-derived defaults** — each app key derives `dir`, `port`, `entry`, and `path`:
+
+| Field | Default | Rule |
+|-------|---------|------|
+| `dir` | App key | `blog` → `'./blog'` |
+| `entry` | `'index.ts'` | Default entry file |
+| `port` | `3001+` | Auto-incremented from 3001 |
+| `path` | `'/key'` | Only for localhost domain |
+
+Override any field explicitly:
+
+```ts
+defineConfig({
   apps: {
-    api: { repo: 'git@github.com:user/api.git', entry: 'app.ts', port: 3001, subdomain: 'api' },
+    blog: { dir: '../packages/blog', entry: 'server.ts', port: 8080, path: '/blog' },
   },
 })
-const server = await deploy(config)
-// server.close(), server.ready, server.url
-// server.apps.list(), server.apps.status(name), server.apps.deploy(name)
 ```
 
+**Routing** — match priority: explicit path > app key > defaultApp.
+
+```ts
+apps: {
+  api: { path: '/api' },     // example.com/api  or  localhost:3000/api
+  blog: {},                   // blog.example.com or  localhost:3000/blog
+}
+```
+
+**Blue-green** — zero-downtime via `ports`:
+
+```ts
+apps: { blog: { ports: [3001, 3002] } }
+```
+
+**WebSocket** — automatically bridged through the gateway.
+
+**Process watchdog** — auto-restarts with exponential backoff on unexpected exit.
+
+**Management API** — all endpoints require `Authorization: Bearer <deployToken>`:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/_deploy/apps` | GET | List apps |
+| `/_deploy/apps/:name` | GET | App details |
+| `/_deploy/apps/:name/deploy` | POST | Restart |
+| `/_deploy/apps/:name/restart` | POST | Restart |
+| `/_deploy/apps/:name/stop` | POST | Stop |
+| `/_deploy/apps/:name/start` | POST | Start |
+| `/_deploy/apps/:name/logs` | GET | SSE log stream |
+
+```bash
+curl -H "Authorization: Bearer my-token" http://localhost:3000/_deploy/apps
+```
+
+**Running** — use systemd for production:
+
+```ini
+[Service]
+WorkingDirectory=/opt/deploy
+ExecStart=/usr/bin/node /opt/deploy/deploy.ts
+Restart=always
+```
+
+**DeployConfig:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `domain` | `'localhost'` | Root domain |
+| `port` | `3000` | Gateway port |
+| `deployToken` | — | Bearer token for management API |
+| `defaultApp` | — | Fallback route |
+| `apps` | — | `Record<string, AppConfig>` |
+
+**AppConfig:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `dir` | App key | Directory containing the app |
+| `port` | Auto (3001+) | Internal port |
+| `entry` | `'index.ts'` | Entry file |
+| `path` | `'/key'` (local) | URL path prefix |
+| `env` | — | Environment variables |
+| `healthEndpoint` | `/` | Health check path |
+| `buildCommand` | — | Build command |
+| `ports` | — | `[port, port+1]` for blue-green |
+
+### errorBoundary(path) [β]
+
+Wraps child routes in an error boundary. If a page or middleware throws, the error component is rendered via SSR with head injection (CSS, theme, context) and layout wrapping.
+
+```ts
+app.use('/blog', errorBoundary('./blog-error.tsx'))
+```
+
+The error component receives `{ error, reset }` as props (`reset` is a no-op on the server):
+
+```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.
+
 ### health [β]
 
 ```ts
@@ -337,6 +483,17 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 | `.migrate()` | DB setup |
 | `.shutdown()` | Clean shutdown |
 
+### layout(path) [β]
+
+Compiles a `.tsx` file and returns middleware that pushes the layout component onto `ctx.layoutStack`. Pages rendered by `ssr()` consume this stack. Use after `rootLayout()` to extend a shared structure.
+
+```ts
+app.use(rootLayout('./ui'))
+app.use(layout('./extra.tsx'))   // appended after rootLayout
+```
+
+Layout components receive `{ children }` (the child page or nested layout). Multiple layouts wrap from outer to inner in `use()` order.
+
 ### logdb [β]
 
 PostgreSQL structured event logging with monthly partitioning.
@@ -409,6 +566,18 @@ await msg.send(channelId, 'System message', { sender_type: 'system', sender_id:
 | `.send(channel, content, opts?)` | Send message to channel |
 | `.close()` | Cleanup |
 
+### notFound(path) [β]
+
+Returns a catch-all handler for 404 pages. When a path is given, the component is rendered via SSR with layout support. Falls back to plain text if compilation fails or no path given.
+
+```ts
+// No path — plain text
+app.all('/*', notFound())
+
+// Path to a .tsx component — renders via SSR
+app.all('/*', notFound('./not-found.tsx'))
+```
+
 ### opencode [β]
 
 AI programming assistant.
@@ -438,6 +607,8 @@ app.ws('/opencode', oc.wsHandler())
 
 ### postgres [α]
 
+Type-safe PostgreSQL client with schema builder, CRUD, migrations, soft delete, and JSONB/vector support.
+
 ```ts
 const pg = postgres()          // reads DATABASE_URL
 app.use(pg)                    // injects ctx.sql
@@ -452,20 +623,109 @@ app.use(pg)                    // injects ctx.sql
 | `connect_timeout` | `number` | `30` | Connection timeout |
 
 ```ts
+// Raw SQL via tagged template
+await pg.sql`SELECT * FROM users WHERE email = ${email}`
+
 // 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() })
-await users.create()
-await users.createIndex('email')
+import { pgTable, serial, text, boolean, timestamps } from 'weifuwu'
+
+const users = pgTable('_users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').unique().notNull(),
+  active: boolean('active').default(true),
+  ...timestamps(),
+})
+await users.create(pg.sql)
+await users.createIndex(pg.sql, 'email')
 
-// BoundTable CRUD
-const t = pg.table('_users', { ... })
+// BoundTable — sql bound once, no need to pass sql to every call
+const t = pg.table('_users', { id: serial('id'), name: text('name'), email: text('email'), ...timestamps() })
 await t.insert({ name: 'Alice' })
+// vs unbound Table — sql passed as first argument each time
+// const t = pgTable('_users', { ... })
+// await t.insert(pg.sql, { name: 'Alice' })
 const { count, data } = await t.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
 await t.upsert({ email: 'alice@test.com' }, 'email')
-await pg.transaction(async (tx) => { const users = pg.table('_users', { ... }).withSql(tx); return users.insert({ name: 'Bob' }) })
+
+// Transactions
+await pg.transaction(async (sql) => {
+  const users = pg.table('_users', {}).withSql(sql)
+  return users.insert({ name: 'Bob' })
+})
+
+// Soft delete — automatic if deleted_at column exists
+await t.delete(1)       // SET deleted_at = NOW()
+await t.hardDelete(1)   // DELETE FROM
+await t.readMany()      // WHERE deleted_at IS NULL (use withDeleted: true to include)
+
+// JSONB queries
+const logs = pg.table('logs', { meta: jsonb<{ service: string }>('meta') })
+await logs.readMany(contains('meta', { service: 'auth' }))
+
+// Partitioned tables
+await logs.create({ partitionBy: partitionBy('range', 'created_at') })
+```
+
+| Column builder | Type | Notes |
+|---------------|------|-------|
+| `serial(name)` | `number` | Auto-increment |
+| `uuid(name)` | `string` | — |
+| `text(name)` | `string` | — |
+| `integer(name)` | `number` | — |
+| `boolean(name)` / `boolean_(name)` | `boolean` | `_` suffix for JS reserved word |
+| `timestamptz(name)` | `string` | — |
+| `jsonb<T>(name)` | `T` | Generic for typed JSONB access |
+| `textArray(name)` | `string[]` | TEXT[] |
+| `vector(name, dims)` | `number[]` | pgvector support |
+
+**Column modifiers:** `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(val)`, `.unique()`, `.references(table, column?, onDelete?)`.
+
+**BoundTable CRUD methods:**
+
+| Method | Description |
+|--------|-------------|
+| `insert(data)` | INSERT + RETURNING \*, returns the inserted row |
+| `insertMany(data)` | Bulk INSERT + RETURNING \*, returns rows |
+| `read(id, opts?)` | SELECT by primary key, returns row or undefined |
+| `readMany(where?, opts?)` | Filtered query with `{ count, data }` — auto-filters soft-deleted |
+| `update(id, data)` | UPDATE by id + RETURNING \*, returns updated row |
+| `updateMany(where, data)` | Bulk UPDATE, returns affected row count |
+| `delete(id)` | Soft delete if `deleted_at` exists, else hard delete |
+| `hardDelete(id)` | Always DELETE FROM |
+| `deleteMany(where)` | Soft bulk delete if `deleted_at` exists |
+| `hardDeleteMany(where)` | Always DELETE FROM |
+| `upsert(data, conflict)` | INSERT ON CONFLICT DO UPDATE, returns row |
+| `count(where?)` | SELECT COUNT(\*) |
+| `create(opts?)` | CREATE TABLE IF NOT EXISTS |
+| `drop(opts?)` | DROP TABLE IF EXISTS |
+| `createIndex(columns, opts?)` | CREATE INDEX |
+| `createUniqueIndex(columns)` | CREATE UNIQUE INDEX |
+| `withSql(sql)` | Returns a new BoundTable bound to a different sql (for transactions) |
+
+**Where helpers** — composable query conditions:
+
+| Helper | SQL |
+|--------|-----|
+| `eq(col, val)` | `"col" = val` |
+| `ne(col, val)` | `"col" != val` |
+| `gt` / `gte` / `lt` / `lte` | Comparison operators |
+| `isNull(col)` / `isNotNull(col)` | `IS NULL` / `IS NOT NULL` |
+| `like(col, pattern)` | `LIKE` |
+| `contains(col, val)` | `@>` JSONB containment |
+| `in_(col, vals)` | `= ANY(...)` |
+| `and(...)` / `or(...)` / `not(...)` | Boolean composition |
+
+**PgModule** — base class for modules that need DB access:
+
+```ts
+class MyModule extends PgModule {
+  async migrate() { /* run DDL */ }
+  async getUsers() { return this.table('users', {}).readMany() }
+}
 ```
 
-Where helpers: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `isNull`, `isNotNull`, `like`, `contains`, `in_`, `and`, `or`, `not`.
+Where helpers + `and`/`or`/`not` can be imported from `'weifuwu'` alongside `postgres`. Full column builders and table helpers are in the same barrel.
 
 ### preferences [α]
 
@@ -565,117 +825,20 @@ 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 |
 
----
-
-## React SSR (weifuwu)
-
-Import from `'weifuwu'` (no separate ssr entry):
-
-```ts
-import { ssr, layout, liveReload, errorBoundary, notFound, tailwind } from 'weifuwu'
-```
-
-### 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:** uses `createRoot` instead of `hydrateRoot` — all hooks (`useState`, `useEffect`) work correctly; SSR content is still streamed for fast first paint
-- **Prod mode:** uses `hydrateRoot` for full SSR hydration
-
-### 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 compiles a hot-update bundle and broadcasts it to all connected browsers.
-
-```ts
-if (process.env.NODE_ENV !== 'production') {
-  app.use(liveReload({ dirs: ['./pages', './layouts'] }))
-}
-```
-
-**How HMR works:**
-
-1. File change detected → compiles the entry `page.tsx` (bundles all dependencies) with esbuild
-2. Browser receives WS message → `import()` the hot bundle
-3. Hot bundle calls `window.__WFW_REFRESH(newComponent)` → updates a stable proxy component
-4. Proxy reference unchanged → React reuses fiber tree → `useState` values preserved
-5. Sets `ctx.tick` to trigger re-render without page navigation
-
-**Key properties:**
-
-- **State preservation** — input fields, scroll position, and other `useState`-driven state survive edits
-- **Entry hash isolation** — each `ssr()` route has its own entry hash; WS messages carry the hash so only matching tabs update
-- **Lazy hydration cache** — hydration bundle is only rebuilt on actual page load, not on every file change
-- **Compilation fallback** — if esbuild encounters a syntax error, `location.reload()` is called to show the error
-
-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.
+### rootLayout(dir) [α]
 
-### notFound(path) [β]
-
-Returns a catch-all handler for 404 pages. Typically registered last:
+One-stop middleware for a page structure. Compiles `layout.tsx` and `app.css` from the given directory, and in dev mode registers vendor bundle, HMR WebSocket, and file watcher.
 
 ```ts
-app.all('/*', notFound('./not-found.tsx'))
+app.use(rootLayout('./ui'))
+// Scans ./ui/layout.tsx → layout component
+// Scans ./ui/app.css → tailwind CSS at /{mountPath}/__wfw/style/{hash}.css
+// Dev: vendor bundle + HMR WS + file watcher
 ```
 
-### tailwind(cssPath) [α]
-
-Compiles Tailwind CSS v4 via `@tailwindcss/postcss` and serves it at `/__wfw/style.css`. The file is compiled once and cached; on `app.css` changes in dev mode, the style is pushed to connected browsers via liveReload's WebSocket.
-
-```ts
-app.use(tailwind('./ui'))
-```
-
-The `dir` argument is the directory containing `app.css`. When `tailwind()` middleware is detected, `ssr()` automatically injects `<link rel="stylesheet" href="/__wfw/style.css" />` into the HTML `<head>`.
+- Sets `ctx.layoutStack` (consumed by `ssr()`)
+- Registers CSS route at `/__wfw/style/:hash.css` — Tailwind CSS compiled via `@tailwindcss/postcss` if `app.css` exists in the dir. Hash is content-based, ensuring cache invalidation on changes.
+- Each `rootLayout` instance is independent — sub-routes can define their own
 
 ### seo [β] + seoMiddleware [α]
 
@@ -695,6 +858,22 @@ Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML st
 | `sitemap` | `SitemapConfig` | — | Sitemap configuration (urls, resolve, cacheTTL) |
 | `headers` | `SeoHeadersConfig` | — | Response headers (e.g. `X-Robots-Tag`) |
 
+### 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('./ui/pages/about.tsx'))
+```
+
+- Compiles via esbuild at runtime (no build step)
+- Reads `ctx.layoutStack` (set by `rootLayout()` or `layout()`) and wraps the component from outer to inner
+- Injects hydration script pointing to the auto-generated client bundle at `/__ssr/{entryId}.js`
+- Injects `<link>` for tailwind CSS from `ctx.tailwindCssUrl` (set by `rootLayout()`)
+- Serializes middleware-injected `ctx` data to `window.__WEIFUWU_CTX` for client-side hydration
+- **Dev mode:** uses `createRoot` instead of `hydrateRoot` — all hooks (`useState`, `useEffect`) work correctly; SSR content is still streamed for fast first paint
+- **Prod mode:** uses `hydrateRoot` for full SSR hydration
+
 ### tenant [β]
 
 Multi-tenant BaaS with dynamic table API and GraphQL.
@@ -905,19 +1084,9 @@ function Toast() {
 
 ### Dev mode
 
-Auto-detected when `NODE_ENV !== 'production'`. File watching + live reload via `liveReload()`:
-
-```ts
-import { liveReload } from 'weifuwu'
-
-if (process.env.NODE_ENV !== 'production') {
-  app.use(liveReload({ dirs: ['./pages', './layouts'] }))
-}
-```
-
-When a `.tsx` file changes, the browser hot-updates without refreshing — `useState` values are preserved. See `liveReload` section for details.
+Auto-detected when `NODE_ENV !== 'production'`. `rootLayout(dir)` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
 
-Tailwind v4 auto-compile via `tailwind()` middleware:
+When a `.tsx` or `.css` file changes under the `rootLayout` dir, the browser hot-updates without refreshing — `useState` values are preserved. Layout changes trigger a full page reload.
 
 ---
 
@@ -949,58 +1118,66 @@ app.get('/stream', (req, ctx) => createSSEStream(events()))
 
 ---
 
-## Utility Functions
+## Complete export index
+
+Every public symbol can be imported from `'weifuwu'`:
 
-### Common
+### Core
 
-| Function | Description |
-|----------|-------------|
-| `loadEnv(path?)` | Load `.env` into `process.env` |
-| `serveStatic(root, opts?)` | Static file serving (20+ MIME, ETag, 304, path traversal protection) |
-| `getCookies(req)` | Parse cookies |
-| `setCookie(res, name, value, opts?)` | Set cookie |
-| `deleteCookie(res, name, opts?)` | Delete cookie |
-| `createTestServer(handler)` | `→ { server, url }` |
+```ts
+serve, createTestServer, Router,
+Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
+loadEnv
+```
 
-### AI re-exports
+### Middleware modules
 
 ```ts
-streamText, generateText, streamObject, generateObject,
-tool, embed, embedMany, smoothStream,
-openai, createOpenAI
+auth, cors, csrf, compress, helmet, logger, rateLimit, requestId, validate, upload,
+preferences, serveStatic
 ```
 
-### pgTable helpers
+### Database
 
 ```ts
-pgTable, pg.table,
-serial, uuid, text, integer, boolean, timestamptz, jsonb, textArray, vector, timestamps,
+postgres, PostgresOptions, PostgresClient,
+redis, RedisOptions, RedisClient,
+queue, QueueOptions, QueueJob, Queue,
+// Schema helpers — importable alongside postgres:
+pgTable, SQL, sql,
+ColumnBuilder, serial, uuid, text, integer, boolean, boolean_, timestamptz, jsonb, textArray, vector,
+partitionBy, timestamps, toDDL, PartitionByDef,
+Table, BoundTable, IndexOptions, FindOptions, CreateOptions,
 eq, ne, gt, gte, lt, lte, isNull, isNotNull, like, contains, in_, and, or, not
 ```
 
----
-
-## Testing
+### Client-side (from `'weifuwu/react'`)
 
 ```ts
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { Router } from 'weifuwu'
+TsxContext, useLoaderData,
+useWebsocket, useAction, useFetch, useQueryState, createStore,
+Link, useNavigate, useNavigating, addInterceptor,
+useLocale, useTheme, applyTheme, useFlashMessage,
+Head
+```
 
-describe('hello', () => {
-  it('returns 200', async () => {
-    const r = new Router()
-    r.get('/', () => new Response('ok'))
-    const res = await r.handler()(new Request('http://localhost/'), {} as any)
-    assert.equal(res.status, 200)
-  })
-})
+### AI SDK (re-exported from `ai`)
+
+```ts
+streamText, generateText, streamObject, generateObject,
+tool, embed, embedMany, smoothStream,
+openai, createOpenAI
 ```
 
+### Other modules
+
 ```ts
-import { createTestServer } from 'weifuwu'
-const { server, url } = await createTestServer(handler)
-const res = await fetch(`${url}/api/ping`)
+health, analytics, seo, seoMiddleware, seoTags,
+user, mailer, graphql, aiStream, runWorkflow,
+logdb, messager, agent, iii, createWorker, registerWorker,
+opencode, deploy, defineConfig,
+getCookies, setCookie, deleteCookie,
+createSSEStream, formatSSE, formatSSEData
 ```
 
 ---

package/cli/template/app.ts

@@ -1,11 +1,11 @@
 import { join } from 'node:path'
-import { Router, ssr, layout, tailwind, preferences } from '../../index.ts'
+import { Router, ssr, rootLayout, preferences } from '../../index.ts'
 
 const _ui = join(import.meta.dirname, 'ui')
 const _loc = join(import.meta.dirname, 'locales')
 
 export const app = new Router()
-app.use(tailwind(_ui))
+app.use(rootLayout(_ui))
 app.use(preferences({ dir: _loc, locale: { default: 'en' }, theme: { default: 'system' } }))
 app.use(async (req, ctx, next) => {
   ctx.loaderData = {
@@ -17,7 +17,6 @@ app.use(async (req, ctx, next) => {
   }
   return next(req, ctx)
 })
-app.use(layout(join(_ui, 'layout.tsx')))
 app.get('/', ssr(join(_ui, 'page.tsx')))
 app.get('/api/ping', () => Response.json({ pong: true, time: new Date().toISOString() }))
 app.ws('/ws/echo', { message(ws, _ctx, data) { ws.send(`echo: ${data}`) } })