weifuwu 0.19.9 → 0.21.0

package/README.md

@@ -15,11 +15,9 @@ serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
 ```ts
-import { serve, Router, preferences, ssr, rootLayout } from 'weifuwu'
+import { serve, Router, ssr } from 'weifuwu'
 const app = new Router()
-app.use(preferences({ dir: './locales' }))
-app.use(rootLayout('./ui'))
-app.get('/', ssr('./ui/pages/home.tsx'))
+app.use('/', ssr({ dir: './ui' }))
 serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 ```
 
@@ -27,6 +25,17 @@ serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 npx weifuwu init my-app && cd my-app && npm run dev
 ```
 
+## CLI
+
+```bash
+npx weifuwu init my-app              # Full project (SSR + i18n + theme + WS demo)
+npx weifuwu init my-api --minimal    # Minimal HTTP project (2 files)
+npx weifuwu init my-api --skip-install # Skip npm install
+npx weifuwu dev                       # Start dev server (auto-detect index.ts)
+npx weifuwu generate module my-mod    # Scaffold middleware module + test
+npx weifuwu version                   # Print version
+```
+
 ---
 
 ## Core Concepts
@@ -44,11 +53,14 @@ await server.ready
 | `hostname` | `string` | `'0.0.0.0'` | Listen address |
 | `signal` | `AbortSignal` | — | Shutdown on abort |
 | `websocket` | `WsUpgradeHandler` | — | WebSocket upgrade handler |
-| `maxBodySize` | `number` | — | Max body bytes |
+| `maxBodySize` | `number` | `10MB` | Max body bytes (0 = unlimited) |
+| `timeout` | `number` | `30_000` | Socket inactivity timeout (ms) |
+| `keepAliveTimeout` | `number` | `5_000` | Keep-Alive idle timeout (ms) |
+| `headersTimeout` | `number` | `6_000` | Headers read timeout (ms) |
 | `shutdown` | `boolean` | `true` | Auto SIGTERM/SIGINT |
 
 ```ts
-interface Server { stop: () => void; readonly port: number; readonly hostname: string; ready: Promise<void> }
+interface Server { stop: () => Promise<void>; readonly port: number; readonly hostname: string; ready: Promise<void> }
 const { server, url } = await createTestServer(handler)
 ```
 
@@ -60,9 +72,24 @@ app.get('/hello/:name', (req, ctx) => Response.json({ message: `Hello, ${ctx.par
 app.post('/data', async (req, ctx) => { const body = await req.json(); return Response.json(body, { status: 201 }) })
 app.use('/admin', authMW)                    // path-scoped middleware
 app.use('/admin', adminRouter)               // sub-router (flattened into parent trie)
-app.ws('/echo', { open(ws) { ws.send('connected') }, message(ws, _ctx, data) { ws.send(`echo: ${data}`) } })
+app.ws('/echo', {
+  open(ws, ctx) { ctx.ws.json({ type: 'connected' }) },
+  message(ws, ctx, data) { ctx.ws.json({ echo: data.toString() }) },
+})
+app.ws('/chat', {
+  open(ws, ctx) { ctx.ws.join('room') },
+  message(ws, ctx, data) { ctx.ws.sendRoom('room', JSON.parse(data.toString())) },
+})
 app.onError((err, req, ctx) => Response.json({ error: err.message }, { status: 500 }))
 
+// Debug: list all registered routes
+console.log(app.routes())
+// [ 'GET     /hello/:name', 'POST    /data', 'WS       /echo', 'WS       /chat' ]
+
+// Cross-process WebSocket broadcast (Redis)
+import { createHub } from 'weifuwu'
+app.wsHub(createHub({ redis: redis() }))
+
 const handler = app.handler()
 const wsHandler = app.websocketHandler()
 serve(handler, { port: 3000, websocket: wsHandler })
@@ -119,14 +146,33 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `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 |
+| `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` | `tailwind()` | `string` | Compiled CSS content (internal) |
-| `tailwindCssUrl` | `tailwind()` | `string` | Compiled CSS route URL (internal) |
+| `compiledTailwindCss` | `ssr()` internal | `string` | Compiled CSS content (internal) |
+| `tailwindCssUrl` | `ssr()` internal | `string` | Compiled CSS route URL (internal) |
+
+### Type-Safe Context
+
+Middleware-injected properties are **automatically typed** through chained `use()` calls:
+
+```ts
+const app = new Router()
+  .use(csrf())          // → Router<Context & { csrfToken: string }>
+  .use(requestId())     // → Router<Context & { csrfToken, requestId }>
+  .use(postgres())      // → Router<Context & { csrfToken, requestId, sql }>
+
+app.get('/me', (_req, ctx) => {
+  ctx.csrfToken   // ✅ string (IDE autocomplete)
+  ctx.requestId   // ✅ string
+  ctx.sql`SELECT 1` // ✅ Sql<{}>
+})
+```
+
+Each module exports an `XxxInjected` type (e.g. `PostgresInjected`, `UserInjected`) for composing custom context types. `Context` is an interface — modules augment it via `declare module` for ambient compatibility.
 
 ---
 
@@ -137,7 +183,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('/path', mod())` | `health()`, `graphql(handler)`, `user()` |
+| `[β]` | `app.use('/path', mod())` | `health()`, `ssr({dir})`, `graphql(handler)`, `user()` |
 
 ### Pattern α — Middleware
 
@@ -167,6 +213,98 @@ app.use('/', a)           // dashboard
 
 ---
 
+## Request Tracing & Logging
+
+Every request gets a **trace ID** via `AsyncLocalStorage`, injected into responses as `X-Trace-Id`. W3C `traceparent` headers are forwarded.
+
+```ts
+import { currentTraceId } from 'weifuwu'
+
+app.get('/api', (req, ctx) => {
+  console.log('Handling request', currentTraceId()) // f240a3f3-60e2-...
+})
+```
+
+**Structured logging** — `logger({ format: 'json' })` outputs JSON to stderr with `traceId`, `timestamp`, `elapsed_ms`:
+
+```json
+{"level":"info","message":"request","method":"GET","path":"/api/users","status":200,"elapsed_ms":42,"traceId":"f240a3f3-...","timestamp":"2025-01-15T10:30:00.000Z"}
+```
+
+Default format is `'short'` (human-readable). `'combined'` includes query strings.
+
+---
+
+## AI Observability
+
+Agent runs are **automatically logged** to `_agent_runs`. Dashboard endpoints provide analytics:
+
+```
+GET /agents/:id/runs?days=7       → [{ input, output, tokens_in, tokens_out, elapsed_ms, status, trace_id, ... }]
+GET /agents/:id/runs/summary?days=7 → { total, success, error, success_rate, tokens_in, tokens_out, avg_elapsed_ms, p95_elapsed_ms }
+GET /opencode/sessions/:id/usage    → { message_count, tokens_in, tokens_out, tokens_total }
+```
+
+Non-streaming runs log full token data; streaming runs log `status: 'stream'`.
+
+---
+
+## Agent ↔ Messager Streaming
+
+Agent replies in messager channels now stream **token-by-token** via WebSocket:
+
+```ts
+// Backend — automatic when agents are attached to messager
+const msg = messager({ pg, agents: agent({ pg, model }) })
+app.ws('/ws', msg.wsHandler())
+// Agent replies stream to: hub.broadcast({ type: 'agent_stream', data: { token, full } })
+```
+
+```tsx
+// Frontend — React hook
+import { useAgentStream } from 'weifuwu/react'
+
+const { getAgentText, isAgentStreaming, stream } = useAgentStream({
+  wsPath: '/ws',
+  channelId: 1,
+})
+```
+
+Multi-round conversation context: the last 10 channel messages are automatically injected into agent calls.
+
+---
+
+## Test Utilities
+
+Chainable test helper for HTTP-level testing without starting a server:
+
+```ts
+import { testApp } from 'weifuwu'
+
+const app = testApp()
+app.use(postgres({ connection: TEST_DB }))
+app.get('/users/:id', (req, ctx) => Response.json({ id: ctx.params.id, user: ctx.user }))
+
+const res = await app
+  .getReq('/users/42?name=Alice')
+  .withUser({ id: 1 })
+  .header('X-Custom', 'val')
+  .body({ data: 'test' })
+  .send()
+
+assert.equal(res.status, 200)
+assert.deepEqual(await res.json(), { id: '42', user: { id: 1 } })
+```
+
+| Method | Description |
+|--------|-------------|
+| `app.getReq(path)` `postReq` `putReq` `patchReq` `deleteReq` | Start building a request |
+| `.withUser(u)` `.withTenant(t)` `.with(ctx)` | Simulate middleware injection |
+| `.header(k,v)` `.body(data)` `.rawBody(str)` | Set request properties |
+| `.send()` → `TestResponse` | Execute and get `{ status, headers, json(), text() }` |
+
+---
+
 ## Module Reference
 
 ### agent [β]
@@ -398,23 +536,30 @@ Restart=always
 | `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):
+### graphql [β]
 
-```tsx
-export default function BlogError({ error, reset }: { error: Error; reset: () => void }) {
-  return <div><h2>Error</h2><p>{error.message}</p></div>
-}
+```ts
+const handler: GraphQLHandler = () => ({
+  schema: `type Query { hello: String }`,
+  resolvers: { Query: { hello: () => 'world' } },
+  graphiql: true,         // GET / returns GraphiQL IDE
+  maxDepth: 10,            // max query nesting (default 10, 0 = disable)
+  timeout: 30_000,         // execution timeout in ms
+})
+app.use('/graphql', graphql(handler))
 ```
 
-Error boundaries nest — the nearest one up the middleware chain catches the error.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `schema` | `string \| GraphQLSchema` | — | SDL string or pre-built schema |
+| `resolvers` | `object` | — | Resolver map |
+| `rootValue` | `any` | — | Root value for queries |
+| `context` | `(req, ctx) => object` | — | Per-request context factory |
+| `graphiql` | `boolean` | `false` | Serve GraphiQL IDE at GET / |
+| `maxDepth` | `number` | `10` | Max query nesting depth |
+| `timeout` | `number` | `30_000` | Execution timeout (ms) |
 
 ### health [β]
 
@@ -483,16 +628,7 @@ 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 [β]
 
@@ -566,17 +702,7 @@ 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 [β]
 
@@ -621,52 +747,70 @@ app.use(pg)                    // injects ctx.sql
 | `ssl` | `boolean\|object` | — | SSL options |
 | `idle_timeout` | `number` | `30` | Idle timeout (seconds) |
 | `connect_timeout` | `number` | `30` | Connection timeout |
+| `statementTimeout` | `number` | `30_000` | Per-statement timeout (ms, 0 = disable) |
+| `onQuery` | `(query, ms, rows) => void` | — | Query logging callback |
 
 ```ts
 // Raw SQL via tagged template
 await pg.sql`SELECT * FROM users WHERE email = ${email}`
 
-// Type-safe DDL
-import { pgTable, serial, text, boolean, timestamps } from 'weifuwu'
+// Define a table — one API, sql pre-bound
+import { serial, text, boolean, timestamps } from 'weifuwu'
 
-const users = pgTable('_users', {
+const users = pg.table('_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 — 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')
-
-// Transactions
+await users.create()           // DDL — no need to pass sql
+await users.createIndex('email')
+
+// CRUD — sql already bound
+await users.insert({ name: 'Alice' })
+const { count, data } = await users.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
+await users.upsert({ email: 'alice@test.com' }, 'email')
+
+// Reuse schema without redefining fields
+import { pgTable } from 'weifuwu'
+const usersSchema = pgTable('_users', { id: serial('id'), name: text('name') })  // define once
+const users = pg.table(usersSchema)  // bind — no field duplication
+
+// Transactions — with auto-retry on deadlock/serialization failure
 await pg.transaction(async (sql) => {
-  const users = pg.table('_users', {}).withSql(sql)
-  return users.insert({ name: 'Bob' })
-})
+  const txUsers = users.withSql(sql)
+  return txUsers.insert({ name: 'Bob' })
+}, { maxRetries: 3 })
 
 // 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)
+await users.delete(1)       // SET deleted_at = NOW()
+await users.hardDelete(1)   // DELETE FROM
+await users.read(1)         // auto-filters 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' }))
 
+// Connection pool visibility
+console.log(pg.poolStats())  // { active: 3, idle: 7, waiting: 0, max: 10 }
+
+// Migration tracking
+await pg.migrate()           // creates _weifuwu_migrations
+await pg.markMigrated('myModule')  // idempotent
+const done = await pg.isMigrated('myModule')
+
 // Partitioned tables
 await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 ```
 
+**When to use pgTable vs pg.table:**
+| API | Use when |
+|-----|---------|
+| `pg.table('t', cols)` | You have `pg` available (factory, handler, migrate) |
+| `pg.table(schema)` | Reusing a schema without duplicating field definitions |
+| `pgTable('t', cols)` | No `pg` reference (utility modules, standalone schema files) |
+
 | Column builder | Type | Notes |
 |---------------|------|-------|
 | `serial(name)` | `number` | Auto-increment |
@@ -681,27 +825,27 @@ await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 
 **Column modifiers:** `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(val)`, `.unique()`, `.references(table, column?, onDelete?)`.
 
-**BoundTable CRUD methods:**
+**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 |
+| `read(id, opts?)` | SELECT by detected primary key + auto soft-delete filter |
 | `readMany(where?, opts?)` | Filtered query with `{ count, data }` — auto-filters soft-deleted |
-| `update(id, data)` | UPDATE by id + RETURNING \*, returns updated row |
+| `update(id, data)` | UPDATE by primary key + 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(\*) |
+| `count(where?)` | SELECT COUNT(\*) — auto-filters soft-deleted |
 | `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) |
+| `withSql(sql)` | Returns copy bound to a different sql (for transactions) |
 
 **Where helpers** — composable query conditions:
 
@@ -825,20 +969,7 @@ 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 |
 
-### rootLayout(dir) [α]
-
-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.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
-```
 
-- 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 [α]
 
@@ -858,21 +989,64 @@ 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) [β]
+### 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.
 
-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
+import { Router, ssr } from 'weifuwu'
+const app = new Router()
+app.use('/', ssr({ dir: './ui' }))
+```
+
+**Directory conventions (Next.js-style):**
+
+```
+./ui/
+├── app/                 ← only this directory affects routing
+│   ├── globals.css      ← tailwind CSS + CSS variables (optional)
+│   ├── layout.tsx       → root layout (wraps all pages)
+│   ├── page.tsx         → GET /
+│   ├── not-found.tsx    → 404 page (optional)
+│   ├── error.tsx        → error boundary (optional)
+│   ├── about/
+│   │   ├── page.tsx     → GET /about
+│   │   └── layout.tsx   → group layout
+│   └── posts/
+│       ├── page.tsx     → GET /posts
+│       └── [id]/
+│           └── page.tsx → GET /posts/:id
+├── components/          ← shared components (does not affect routing)
+└── lib/                 ← utilities (does not affect routing)
+```
+
+| Location | Route |
+|----------|-------|
+| `app/page.tsx` | `GET /` |
+| `app/[param]/page.tsx` | `GET /:param` |
+| `app/layout.tsx` | Root layout (wraps all pages in its subtree) |
+| `app/not-found.tsx` | 404 fallback for that subtree |
+| `app/error.tsx` | Error boundary for that subtree |
+| `app/globals.css` | Tailwind CSS entry (compiled via `@tailwindcss/postcss`) |
+
+**How it 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`
+- 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
 
 ```ts
-app.get('/about', ssr('./ui/pages/about.tsx'))
+// Multiple independent SSR directories
+app.use('/',      ssr({ dir: './www' }))
+app.use('/admin', ssr({ dir: './admin' }))
+
+// API routes coexist normally
+app.get('/api/ping', () => Response.json({ pong: true }))
 ```
 
-- 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
+Layout components receive `{ children }` and wrap from outer to inner:
 
 ### tenant [β]
 
@@ -1084,9 +1258,9 @@ function Toast() {
 
 ### Dev mode
 
-Auto-detected when `NODE_ENV !== 'production'`. `rootLayout(dir)` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
+Auto-detected when `NODE_ENV !== 'production'`. `ssr({dir})` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
 
-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.
+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.
 
 ---
 
@@ -1125,9 +1299,10 @@ Every public symbol can be imported from `'weifuwu'`:
 ### Core
 
 ```ts
-serve, createTestServer, Router,
+serve, createTestServer, Router, ssr,
 Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
-loadEnv
+loadEnv, testApp, TestApp, TestRequest, TestResponse,
+currentTraceId, currentTrace, runWithTrace, traceElapsed, TraceContext,
 ```
 
 ### Middleware modules
@@ -1143,6 +1318,7 @@ preferences, serveStatic
 postgres, PostgresOptions, PostgresClient,
 redis, RedisOptions, RedisClient,
 queue, QueueOptions, QueueJob, Queue,
+PostgresInjected, RedisInjected, QueueInjected,
 // Schema helpers — importable alongside postgres:
 pgTable, SQL, sql,
 ColumnBuilder, serial, uuid, text, integer, boolean, boolean_, timestamptz, jsonb, textArray, vector,
@@ -1158,8 +1334,10 @@ TsxContext, useLoaderData,
 useWebsocket, useAction, useFetch, useQueryState, createStore,
 Link, useNavigate, useNavigating, addInterceptor,
 useLocale, useTheme, applyTheme, useFlashMessage,
+useAgentStream,
 Head
 ```
+export type { UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState } from 'weifuwu/react'
 
 ### AI SDK (re-exported from `ai`)
 
@@ -1172,12 +1350,16 @@ openai, createOpenAI
 ### Other modules
 
 ```ts
-health, analytics, seo, seoMiddleware, seoTags,
+preferences, health, analytics, seo, seoMiddleware, seoTags,
 user, mailer, graphql, aiStream, runWorkflow,
 logdb, messager, agent, iii, createWorker, registerWorker,
 opencode, deploy, defineConfig,
+testApp, TestApp, TestRequest, TestResponse,
 getCookies, setCookie, deleteCookie,
-createSSEStream, formatSSE, formatSSEData
+createSSEStream, formatSSE, formatSSEData,
+currentTraceId, currentTrace, runWithTrace, traceElapsed,
+createHub, Hub, HubOptions,
+DEFAULT_MAX_BODY, MIGRATIONS_TABLE,
 ```
 
 ---

package/cli/template/app.ts

@@ -1,12 +1,8 @@
-import { join } from 'node:path'
-import { Router, ssr, rootLayout, preferences } from '../../index.ts'
-
-const _ui = join(import.meta.dirname, 'ui')
-const _loc = join(import.meta.dirname, 'locales')
+import { Router, ssr, preferences } from '../../index.ts'
 
 export const app = new Router()
-app.use(rootLayout(_ui))
-app.use(preferences({ dir: _loc, locale: { default: 'en' }, theme: { default: 'system' } }))
+app.use('/', ssr({ dir: './ui' }))
+app.use(preferences({ dir: './locales', locale: { default: 'en' }, theme: { default: 'system' } }))
 app.use(async (req, ctx, next) => {
   ctx.loaderData = {
     features: [
@@ -17,6 +13,5 @@ app.use(async (req, ctx, next) => {
   }
   return next(req, ctx)
 })
-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}`) } })

package/cli/template/index.ts

@@ -3,6 +3,4 @@ import { app } from './app.ts'
 
 loadEnv()
 const port = Number(process.env.PORT) || 3000
-const server = serve(app.handler(), { port, websocket: app.websocketHandler() })
-await server.ready
-console.log(`Listening on http://localhost:${server.port}`)
+serve(app.handler(), { port, websocket: app.websocketHandler() })

package/cli/template/ui/{page.tsx → app/page.tsx}

@@ -1,6 +1,6 @@
 import { useState } from 'react'
-import { useWebsocket, useLoaderData, useLocale, useTheme } from '../../../react.ts'
-import Greeting from './components/Greeting.tsx'
+import { useWebsocket, useLoaderData, useLocale, useTheme } from '../../../../react.ts'
+import Greeting from '../components/Greeting.tsx'
 
 export default function Home() {
   const [input, setInput] = useState('')