weifuwu 0.16.6 → 0.17.1

package/README.md

@@ -14,7 +14,6 @@ description: Web-standard HTTP framework for Node.js — (req, ctx) => Response
 - [React SSR (tsx)](#react-ssr-tsx)
 - [PostgreSQL](#postgresql)
 - [Auth](#auth)
-- [Security](#security)
 - [WebSocket & Real-time](#websocket--real-time)
 - [AI](#ai)
 - [Data Layer](#data-layer)
@@ -26,7 +25,7 @@ description: Web-standard HTTP framework for Node.js — (req, ctx) => Response
 - [Opencode](#opencode)
 - [Deploy](#deploy)
 - [Health check](#health-check)
-- [Internationalization](#internationalization)
+- [Preferences](#preferences)
 - [Email](#email)
 - [Server-Sent Events](#server-sent-events)
 - [Utility functions](#utility-functions)
@@ -44,17 +43,42 @@ import { serve } from 'weifuwu'
 serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
-### weifuwu init
+### Full-stack SSR in one file
+
+```ts
+import { serve, Router, tsx, preferences } from 'weifuwu'
+
+const app = new Router()
+app.use(preferences({
+  dir: './locales',           // i18n (0 extra deps)
+  theme: {},                  // dark mode (0 extra deps)
+}))
+app.use('/', await tsx({ dir: './ui' }))
+
+serve(app.handler(), { port: 3000 })
+```
+
+Your tsx pages can use it directly:
+
+```tsx
+import { Head, useCtx, useData, createStore } from 'weifuwu/react'
 
-Generate a full project with React SSR, WebSocket, Tailwind CSS, and graceful shutdown:
+export default function Page() {
+  const { t, theme } = useCtx()          // i18n + theme
+  const { data } = useData('/api/list')  // data fetching
+  return <h1>{t('hello')} / {theme}</h1>
+}
+```
+
+**Zero extra dependencies** — no zustand, react-query, next-intl, next-themes, react-hot-toast needed.
+
+### weifuwu init
 
 ```bash
 npx weifuwu init my-app
 cd my-app && npm install && npm run dev
 ```
 
-Creates `app.ts` with `tsx()`, `router.ws()`, `/api/ping` API route, and `ui/pages/layout.tsx` + `page.tsx`.
-
 ---
 
 ## serve() — HTTP server
@@ -183,10 +207,11 @@ app.get('/admin', middleware, handler)       // route-level
 | `compress(options?)` | Brotli / Gzip / Deflate compression |
 | `validate(schemas)` | Zod validation (body, query, params) |
 | `upload(options?)` | Multipart file upload |
-| `i18n(options)` | Internationalization — `ctx.t()`, locale detection |
+| `preferences(options?)` | Locale + theme detection, `ctx.t()`, `ctx.prefs`, `ctx.setPref()` |
 | `seoMiddleware(options?)` | `X-Robots-Tag` header — string or path-based function |
 | `helmet(options?)` | Security headers — CSP, HSTS, X-Frame-Options, etc. |
 | `requestId(options?)` | `X-Request-ID` header + `ctx.requestId` |
+| `health(options?)` | `GET /health` endpoint with custom checks |
 
 ### auth
 
@@ -332,6 +357,8 @@ app.use(helmet({
 }))
 ```
 
+13 security headers by default: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, `Strict-Transport-Security`, `Content-Security-Policy`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy`, `Cross-Origin-Embedder-Policy`, `X-DNS-Prefetch-Control`, `X-Download-Options`, `X-Permitted-Cross-Domain-Policies`.
+
 ### requestId
 
 ```ts
@@ -341,14 +368,11 @@ app.use(requestId())
 // Sets X-Request-ID header on responses, available as ctx.requestId
 ```
 
-13 security headers set by default with `helmet()`: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, `Strict-Transport-Security`, `Content-Security-Policy`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Openner-Policy`, `Cross-Origin-Resource-Policy`, `Cross-Origin-Embedder-Policy`, `X-DNS-Prefetch-Control`, `X-Download-Options`, `X-Permitted-Cross-Domain-Policies`.
-
 ---
 
 ## React SSR (tsx)
 
 ```ts
-import { serve, Router } from 'weifuwu'
 import { serve, Router, tsx } from 'weifuwu'
 
 const app = new Router()
@@ -378,12 +402,25 @@ ui/
 
 ### page.tsx — page component
 
+Components receive `{ params, query }` from routing and can use hooks for
+context, data fetching, state, URL sync, and meta tags (see [exports table](#react-exports-weifuwureact)):
+
 ```tsx
-export default function Page({ params, query }: {
-  params: { slug: string }
-  query: Record<string, string>
-}) {
-  return <article><h1>{params.slug}</h1></article>
+import { Head, useCtx, useData, createStore, useQueryState } from 'weifuwu/react'
+
+const useFilters = createStore({ category: '' })
+
+export default function Page({ params, query }: { params: { slug: string }; query: Record<string, string> }) {
+  const { t, locale, theme } = useCtx()                    // i18n + theme + prefs
+  const [page, setPage] = useQueryState('page', '1')       // URL sync
+  const { data, loading, mutate } = useData(`/api/posts?page=${page}`)  // data fetching
+
+  return (
+    <>
+      <Head><title>{t('page.title')}</title></Head>
+      {loading ? <Skeleton /> : data.posts.map(p => <Card key={p.id} />)}
+    </>
+  )
 }
 ```
 
@@ -422,6 +459,8 @@ export default function RootLayout({ children, req, ctx }: {
 
 **Nested layouts** (`pages/blog/layout.tsx`) — receives only `{ children }`.
 
+Page components access preferences, i18n, and theme via `useCtx()` — see [Preferences](#preferences).
+
 ### route.ts — API (co-located with page)
 
 ```ts
@@ -446,6 +485,17 @@ const apiUrl = process.env.WEIFUWU_PUBLIC_API_URL
 
 The hydration bundle also injects `self.process = { env: {} }` as a safety net so any `process.env.*` reference in bundled dependencies won't throw.
 
+### Streaming SSR
+
+HTML is streamed via `TransformStream` — the browser starts rendering before the full page is ready. `<head>` content (theme blocking script, locale data, CSS) is injected at the `</head>` boundary and sent immediately.
+
+### Persistent layout
+
+The client hydration bundle creates a persistent `App` root that wraps all pages. Client-side navigation via `<Link>` (or `navigate()`) replaces the page component in-place instead of unmounting and re-hydrating. This means:
+- `TsxContext.Provider` stays alive across navigations
+- `createStore()` state persists (no cache-busting on bundle imports)
+- Faster navigation — React only re-renders the page component
+
 ### Client-side hooks
 
 #### useWebsocket — auto-reconnecting WebSocket
@@ -490,13 +540,14 @@ Auto-serializes JSON, auto-reads `_csrf` cookie and sends as `X-CSRF-Token`. Ret
 ### Client-side navigation
 
 ```tsx
-import { Link, useNavigate } from 'weifuwu/react'
+import { Link, useNavigate, useNavigating } from 'weifuwu/react'
 
 function Nav() {
   const navigate = useNavigate()
+  const loading = useNavigating()
   return (
-    <nav>
-      <Link href="/about">About</Link>
+    <nav className={loading ? 'opacity-50' : ''}>
+      <Link href="/about" prefetch>About</Link>
       <button onClick={() => navigate('/contact')}>Contact</button>
     </nav>
   )
@@ -505,6 +556,126 @@ function Nav() {
 
 `navigate(href)` fetches the target via SSR, extracts `__weifuwu_root` content and `__WEIFUWU_PROPS`, replaces in-place, then imports the new hydration bundle. `load.ts` runs on the server for every navigation. Initial load is full SSR; subsequent navigations are client-side.
 
+- `<Link prefetch>` — pre-fetches page data on hover / when entering viewport (200px margin)
+- `useNavigating()` — reactive boolean, `true` while navigation is in-flight
+- `isNavigating()` / `onNavigate(fn)` — non-hook alternatives
+- Scroll position is saved before navigation and restored after the new page renders
+
+### Head — per-page meta tags
+
+```tsx
+import { Head } from 'weifuwu/react'
+
+export default function Page() {
+  return (
+    <>
+      <Head>
+        <title>My Page - App</title>
+        <meta name="description" content="Page description" />
+        <meta property="og:title" content="My Page" />
+      </Head>
+      <h1>Content</h1>
+    </>
+  )
+}
+```
+
+During SSR, the `<Head>` content is extracted from the body and merged into `<head>`. On client-side navigation via `<Link>`, title and meta tags are updated automatically.
+
+### Flash messages
+
+```ts
+// Server: set a flash message before redirect
+router.post('/post', (req, ctx) => {
+  return ctx.setPref('flash', JSON.stringify({
+    type: 'success', message: 'Published!'
+  }))  // → 302 with Set-Cookie: flash=...
+})
+```
+
+```tsx
+// Client: display flash from preferences
+function Toast() {
+  const { prefs } = useCtx()
+  const flash = prefs?.flash ? JSON.parse(prefs.flash) : null
+  if (!flash) return null
+  return <div className={`toast ${flash.type}`}>{flash.message}</div>
+}
+```
+
+Flash is read once from the cookie, then automatically cleared on the response. After page refresh the flash is gone.
+
+### Client-side state management
+
+#### createStore — shared state (replaces Zustand)
+
+```tsx
+import { createStore } from 'weifuwu/react'
+
+const useStore = createStore({ count: 0, items: [] as string[] })
+
+function Counter() {
+  const count = useStore(s => s.count)       // selector
+  const { setState, getState } = useStore()   // full state + API
+  return <button onClick={() => setState({ count: count + 1 })}>{count}</button>
+}
+
+function List() {
+  const items = useStore(s => s.items)
+  return items.map(i => <div>{i}</div>)
+}
+
+// Outside components:
+useStore.getState()
+useStore.setState({ count: 1 })
+useStore.subscribe(() => {})
+```
+
+Uses `useSyncExternalStore` internally. No context provider needed. State persists across client-side navigations (no cache-busting on bundle imports).
+
+#### useData — data fetching (replaces React Query / SWR)
+
+```tsx
+import { useData } from 'weifuwu/react'
+
+// Client-only fetch (shows loading skeleton on first load)
+function PostList() {
+  const { data, error, loading, mutate } = useData('/api/posts')
+  if (loading) return <Skeleton />
+  return <div>{data.posts.map(p => <PostCard key={p.id} post={p} />)}</div>
+}
+
+// With SSR fallback — data from load.ts, client takes over after hydration
+function PostList({ load }: { load: { posts: Post[] } }) {
+  const { data, mutate } = useData('/api/posts', { fallback: load })
+  return <div>{data.posts.map(p => <PostCard key={p.id} post={p} />)}</div>
+}
+```
+
+In-memory cache with 60s TTL, concurrent request dedup. `mutate(data)` for optimistic updates, `mutate()` for revalidation.
+
+#### useQueryState — URL query params
+
+```tsx
+import { useQueryState } from 'weifuwu/react'
+
+function SearchPage() {
+  const [q, setQ] = useQueryState('q', '')
+  const [page, setPage] = useQueryState('page', '1')
+  const { data } = useData(`/api/search?q=${q}&page=${page}`)
+
+  return (
+    <>
+      <input value={q} onChange={e => { setQ(e.target.value); setPage('1') }} />
+      <Results items={data?.items} />
+      <Pagination page={Number(page)} onChange={setPage} />
+    </>
+  )
+}
+```
+
+Synced with `window.location.search` via `useSyncExternalStore`. Back/forward navigation updates the state. Changes use `history.replaceState` and dispatch a synthetic `popstate` for reactivity.
+
 ### Development mode
 
 Auto-detected when `NODE_ENV !== 'production'`. File watching (`chokidar`), single-file recompilation, WebSocket live reload (`/__weifuwu/livereload`), Tailwind CSS v4 auto-compilation.
@@ -990,18 +1161,31 @@ app.use(health({
 
 ---
 
-## Internationalization
+## Preferences
 
 ```ts
-import { i18n } from 'weifuwu'
+import { preferences } from 'weifuwu'
 
-app.use(i18n({ dir: './locales', defaultLocale: 'en' }))
+app.use(preferences({
+  dir: './locales',                // translation directory (optional)
+  locale: { default: 'en' },       // locale detection
+  theme: { default: 'system' },    // 'light' | 'dark' | 'system'
+}))
 
 // In handlers: ctx.t('greeting') → "Hello"
-// In layout: ctx.locale → "en"
+//              ctx.locale → "en"
+//              ctx.theme → "light"
+//              ctx.prefs → { locale: 'en', theme: 'light' }
+//              ctx.setPref('locale', 'zh') → 302 + cookie
+//              ctx.setPref('flash', '{"type":"success","message":"Done"}') → flash message
+
+// In tsx components:
+const { t, locale, theme } = useCtx()
 ```
 
-Locale detection: `Accept-Language` header → browser preference. Falls back to `defaultLocale`.
+Locale detection priority: cookie → `Accept-Language` → default.
+Theme detection: cookie → default (`'system'`).
+Flash messages: set via `ctx.setPref('flash', ...)` → auto-read from cookie → cleared after rendering.
 
 ---
 
@@ -1045,13 +1229,22 @@ app.get('/stream', (req, ctx) => createSSEStream(events()))
 | `formatSSE(event, data)` | Format SSE event string |
 | `formatSSEData(data)` | Format SSE data string |
 | `runWorkflow(options)` | DAG execution engine as AI SDK Tool |
-| `useWebsocket(url, opts?)` | React auto-reconnecting WebSocket hook |
-| `useAction(url, opts?)` | React async form submission hook |
-| `navigate(href)` | Client-side page navigation |
-| `useNavigate()` | React hook returning navigate function |
-| `csrf(options?)` | CSRF protection middleware |
-| `seoTags(config)` | Generate `<title>`, `<meta>`, OG, Twitter Card tags |
-| `createHub(options?)` | WebSocket channel hub |
+
+### React exports (`weifuwu/react`)
+
+| Hook / Component | Description |
+|-----------------|-------------|
+| `useCtx()` | Unified context — `{ prefs, locale, theme, t, params, query }` (requires `preferences` middleware) |
+| `createStore(initial)` | Zustand-compatible shared state — `getState`, `setState`, `subscribe` |
+| `useData(url, opts?)` | SWR-style data fetching — cache, dedup, mutate, fallback |
+| `useQueryState(key, default)` | URL query param sync — `?page=1` via `useSyncExternalStore` |
+| `useAction(url, opts?)` | Async form submission — `{ submit, data, error, pending }` |
+| `useWebsocket(url, opts?)` | Auto-reconnecting WebSocket — `{ send, lastMessage, readyState }` |
+| `useNavigate()` | Client-side navigation callback |
+| `useNavigating()` | Reactive loading state during navigation |
+| `navigate(href)` | Client-side page navigation (imperative) |
+| `Link` | `<Link href prefetch>` — prefetch on hover/visible |
+| `Head` | `<Head>` — per-page `<title>` / `<meta>` merged into `<head>` |
 
 ### AI SDK re-exports
 

package/dist/client-router.d.ts

@@ -1,10 +1,19 @@
+export declare function isNavigating(): boolean;
+export declare function onNavigate(fn: (v: boolean) => void): () => void;
 export declare function navigate(href: string): Promise<void>;
 export declare function useNavigate(): (href: string) => Promise<void>;
+export declare function useNavigating(): boolean;
 interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
     href: string;
     children: React.ReactNode;
+    prefetch?: boolean;
 }
-export declare function Link({ href, children, onClick, ...props }: LinkProps): import("react").DetailedReactHTMLElement<{
+export declare function Link({ href, children, onClick, prefetch, ...props }: LinkProps): import("react").DetailedReactHTMLElement<{
+    slot?: string | undefined | undefined;
+    style?: import("react").CSSProperties | undefined;
+    title?: string | undefined | undefined;
+    dir?: string | undefined | undefined;
+    property?: string | undefined | undefined;
     download?: any;
     hrefLang?: string | undefined | undefined;
     media?: string | undefined | undefined;
@@ -22,18 +31,14 @@ export declare function Link({ href, children, onClick, ...props }: LinkProps):
     className?: string | undefined | undefined;
     contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined | undefined;
-    dir?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
     hidden?: boolean | undefined | undefined;
     id?: string | undefined | undefined;
     lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;
-    slot?: string | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
-    style?: import("react").CSSProperties | undefined;
     tabIndex?: number | undefined | undefined;
-    title?: string | undefined | undefined;
     translate?: "yes" | "no" | undefined | undefined;
     radioGroup?: string | undefined | undefined;
     role?: import("react").AriaRole | undefined;
@@ -42,7 +47,6 @@ export declare function Link({ href, children, onClick, ...props }: LinkProps):
     datatype?: string | undefined | undefined;
     inlist?: any;
     prefix?: string | undefined | undefined;
-    property?: string | undefined | undefined;
     rel?: string | undefined | undefined;
     resource?: string | undefined | undefined;
     rev?: string | undefined | undefined;
@@ -230,7 +234,7 @@ export declare function Link({ href, children, onClick, ...props }: LinkProps):
     onDropCapture?: import("react").DragEventHandler<HTMLAnchorElement> | undefined;
     onMouseDown?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;
     onMouseDownCapture?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;
-    onMouseEnter?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;
+    onMouseEnter: import("react").MouseEventHandler<HTMLAnchorElement>;
     onMouseLeave?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;
     onMouseMove?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;
     onMouseMoveCapture?: import("react").MouseEventHandler<HTMLAnchorElement> | undefined;

package/dist/client-state.d.ts

@@ -0,0 +1,22 @@
+type SetPartial<T> = Partial<T> | ((prev: T) => Partial<T>);
+export interface StoreApi<T> {
+    (): T;
+    <S>(selector: (state: T) => S): S;
+    getState: () => T;
+    setState: (partial: SetPartial<T>) => void;
+    subscribe: (listener: () => void) => () => void;
+}
+export declare function createStore<T extends Record<string, unknown>>(initial: T): StoreApi<T>;
+interface UseDataResult<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    loading: boolean;
+    mutate: (data?: T) => Promise<void>;
+}
+interface UseDataOptions<T> {
+    fallback?: T;
+    ttl?: number;
+}
+export declare function useData<T = unknown>(url: string | null, options?: UseDataOptions<T>): UseDataResult<T>;
+export declare function useQueryState(key: string, defaultValue?: string): [string, (val: string | ((prev: string) => string)) => void];
+export {};

package/dist/head.d.ts

@@ -0,0 +1,6 @@
+import { type ReactNode } from 'react';
+export declare function Head({ children }: {
+    children: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+    id: string;
+}, HTMLElement>;

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, useTsx } from './tsx.ts';
+export { tsx, TsxContext, useCtx } from './tsx.ts';
 export type { TsxOptions } from './tsx.ts';
 export { auth, cors, logger } from './middleware.ts';
 export type { AuthOptions, CORSOptions, LoggerOptions } from './middleware.ts';
@@ -54,8 +54,8 @@ export { opencode } from './opencode/index.ts';
 export type { OpencodeOptions, OpencodeModule, SkillDef, OpencodePermissions, Session as OpencodeSession, } from './opencode/types.ts';
 export { health } from './health.ts';
 export type { HealthOptions } from './health.ts';
-export { i18n } from './i18n.ts';
-export type { I18nOptions } from './i18n.ts';
+export { preferences } from './preferences.ts';
+export type { PrefOptions } from './preferences.ts';
 export { seo, seoMiddleware, seoTags } from './seo.ts';
 export type { SeoOptions, RobotsRule, SitemapUrl, SitemapConfig, SeoHeadersConfig, SeoTagsConfig, } from './seo.ts';
 export { mailer } from './mailer.ts';