weifuwu 0.33.1 → 0.33.3

package/README.md

@@ -1,17 +1,19 @@
 # weifuwu
 
-**AI SaaS framework** — `(req, ctx) => Response`
+**AI SaaS full-stack framework** — `(req, ctx) => Response` + `(props, ctx) => JSX`
 
 ```bash
 npm install weifuwu
 ```
 
-User system, instant messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage. Configure environment variables and go.
+One package. Backend + frontend. User system, instant messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage, and a reactive frontend framework. Configure environment variables and go.
 
 ---
 
 ## Quick Start
 
+### Backend
+
 ```ts
 import { serve, Router, postgres, user, kb, agent, messager } from 'weifuwu'
 import { openai } from '@ai-sdk/openai'
@@ -34,6 +36,46 @@ app.post('/api/chat', async (req, ctx) => {
 serve(app, { port: 3000 })
 ```
 
+### Frontend
+
+```tsx
+import { signal, Show, For, createApp, router, RouteView } from 'weifuwu/client'
+import type { WfuiContext } from 'weifuwu/client'
+
+function HomePage(_props: {}, ctx: WfuiContext) {
+  return (
+    <div>
+      <h1>Hello weifuwu</h1>
+      <p>当前路径: {ctx.route.path}</p>
+    </div>
+  )
+}
+
+const app = createApp()
+app.use(router({
+  routes: [
+    { path: '/', component: HomePage, title: '首页' },
+    { path: '/chat/:id', component: ChatPage, title: '聊天' },
+  ],
+}))
+app.mount('#root', AppShell)
+```
+
+```json
+// tsconfig.json
+{ "jsx": "react-jsx", "jsxImportSource": "weifuwu/client" }
+```
+
+```js
+// build.mjs
+esbuild.build({
+  entryPoints: ['src/main.tsx'],
+  jsx: 'automatic',
+  jsxImportSource: 'weifuwu/client',
+  bundle: true,
+})
+```
+
 ### Environment Variables
 
 | Variable | Default | Used by |
@@ -49,6 +91,8 @@ serve(app, { port: 3000 })
 
 ## Modules
 
+### Backend
+
 | Module | Import | Dependency | Purpose |
 |--------|--------|-----------|---------|
 | User | `user()` | `postgres()` | Auth, JWT, roles |
@@ -84,6 +128,20 @@ serve(app, { port: 3000 })
 | `queue()` | Job queue + cron |
 | `createHub()` | WebSocket pub/sub |
 
+### Frontend (weifuwu/client)
+
+| Import | Purpose |
+|--------|---------|
+| `signal()` | Reactive state |
+| `computed()` | Derived signals |
+| `effect()` | Auto-tracked side effects |
+| `<Show>` | Conditional rendering |
+| `<For>` | List rendering |
+| `<RouteView>` | Route outlet |
+| `createApp()` | App instance with middleware chain |
+| `router()` | Hash/history router with params + query |
+| `domMount()` | Direct DOM mounting |
+
 ### Utilities
 
 | Import | Purpose |
@@ -92,6 +150,92 @@ serve(app, { port: 3000 })
 
 ---
 
+## Frontend (weifuwu/client)
+
+**weifuwu/client** is a reactive frontend framework built on Signal + TSX. Zero virtual DOM, zero dependencies, ~600 lines total.
+
+### Concepts
+
+```ts
+// 1. Signal — reactive data
+const count = signal(0)
+count.value = count.value + 1  // DOM updates automatically
+
+// 2. Computed — derived signals
+const doubled = computed(() => count.value * 2)
+
+// 3. Effect — auto-tracked side effects
+effect(() => console.log('count:', count.value))
+
+// 4. Component — (props, ctx) => JSX
+function MyComponent({ name }: { name: string }, ctx: WfuiContext) {
+  return <div>Hello {name}</div>
+}
+```
+
+### createApp + Middleware
+
+```tsx
+import { createApp, router, RouteView } from 'weifuwu/client'
+import type { WfuiContext, RouteDef } from 'weifuwu/client'
+
+const app = createApp()
+app.use(router({ routes, mode: 'hash' }))
+app.mount('#root', AppShell)
+```
+
+### Router
+
+```tsx
+const routes: RouteDef[] = [
+  { path: '/', component: HomePage, title: '首页' },
+  { path: '/chat/:id', component: ChatPage, title: '聊天' },
+  { path: '/user/:name', component: UserPage, title: '用户' },
+]
+
+app.use(router({
+  routes,
+  notFound: NotFound,
+  mode: 'hash', // or 'history'
+}))
+
+// In layout:
+function AppShell(_, ctx) {
+  return (
+    <div>
+      <nav>
+        <a onClick={() => ctx.app.navigate('/')}>首页</a>
+        <a onClick={() => ctx.app.navigate('/chat/123')}>聊天</a>
+      </nav>
+      <main>
+        <RouteView />  {/* ← renders matched route */}
+      </main>
+    </div>
+  )
+}
+
+// Route params and query:
+ctx.route.path     // "/chat/123"
+ctx.route.params   // { id: "123" }
+ctx.route.query    // { tab: "settings" }
+```
+
+### Show / For
+
+```tsx
+// Conditional rendering (supports Signal)
+<Show when={isLoggedIn} fallback={<LoginPage />}>
+  <Dashboard />
+</Show>
+
+// List rendering (supports Signal)
+<For each={filteredItems}>
+  {(item) => <div>{item.name}</div>}
+</For>
+```
+
+---
+
 ## user
 
 Auth, registration, JWT, password management, roles.
@@ -344,7 +488,7 @@ app.post('/api/chat/sync', async (req, ctx) => {
 ### ctx.agent API
 
 | Method | Description |
-|--------|-------------|
+|-------------|-------------|
 | `chat(prompt, opts?)` | Non-streaming, returns text |
 | `chatStreamResponse({ messages })` | SSE stream (compatible with `useChat`) |
 
@@ -602,8 +746,21 @@ src/
 ├── queue/               ← Job queue + cron
 ├── graphql.ts           ← GraphQL
 ├── hub.ts               ← WebSocket hub
+├── client/              ← Frontend framework (signal, JSX, router)
+│   ├── index.ts
+│   ├── signal.ts
+│   ├── jsx-runtime.ts
+│   ├── app.ts
+│   ├── router.ts
+│   └── types.ts
 └── test/                ← 281 tests
 
+apps/demo/               ← Full-stack demo
+├── src/main.tsx
+├── public/index.html
+├── tsconfig.json
+└── scripts/build.mjs
+
 docker-compose.yml       ← postgres (pgvector) + redis
 ```
 

package/dist/client/app.d.ts

@@ -0,0 +1,24 @@
+/**
+ * weifuwu/client 应用 — 创建 ctx + 中间件链 + 挂载组件
+ *
+ * ```tsx
+ * import { createApp, api, auth, ws, router } from 'weifuwu/client'
+ *
+ * const app = createApp()
+ * app.use(api())
+ * app.use(auth())
+ * app.use(ws())
+ * app.use(router({ routes }))
+ * app.mount('#root', AppShell)
+ * ```
+ */
+import type { WfuiContext, AppMiddleware } from './types.ts';
+import type { Component } from './jsx-runtime.ts';
+/**
+ * 创建 weifuwu/client 应用
+ */
+export declare function createApp(): {
+    ctx: WfuiContext;
+    use: (mw: AppMiddleware) => any;
+    mount: (rootSelector: string, RootComponent: Component) => Promise<void>;
+};

package/dist/client/components/Chat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Chat — 消息聊天组件
+ *
+ * 与 weifuwu 后端 messager + agent 模块对接。
+ *
+ * ```ts
+ * import { Chat } from 'weifuwu/client'
+ *
+ * function ChatPage(_, ctx) {
+ *   return Chat({ conversationId: '123' }, ctx)
+ * }
+ * ```
+ */
+import type { WfuiContext } from '../types.ts';
+export declare function Chat({ conversationId }: {
+    conversationId: string;
+}, ctx: WfuiContext): Node;

package/dist/client/components/LoginForm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * LoginForm — 登录/注册组件
+ *
+ * ```ts
+ * import { LoginForm } from 'weifuwu/client'
+ *
+ * function LoginPage(_, ctx) {
+ *   if (ctx.isAuthenticated) return ctx.app.navigate('/')
+ *   return LoginForm({}, ctx)
+ * }
+ * ```
+ */
+import type { WfuiContext } from '../types.ts';
+export declare function LoginForm(_props: {}, ctx: WfuiContext): Node;

package/dist/client/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * weifuwu/client — 响应式前端框架，TSX + Signal
+ *
+ * ```tsx
+ * import { signal, createdApp, api, auth, ws, router, RouteView, Show, For } from 'weifuwu/client'
+ * import type { WfuiContext } from 'weifuwu/client'
+ *
+ * const app = createApp()
+ * app.use(api())
+ * app.use(auth())
+ * app.use(ws())
+ * app.use(router({ routes }))
+ * app.mount('#root', AppShell)
+ * ```
+ */
+export { signal, computed, effect, isSignal } from './signal.ts';
+export type { Signal } from './signal.ts';
+export { jsx, jsxs, jsxDEV, Fragment, Show, For, domMount } from './jsx-runtime.ts';
+export type { Component } from './jsx-runtime.ts';
+export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
+export { createApp } from './app.ts';
+export { router, RouteView } from './router.ts';
+export { api, ApiClient, ApiError } from './middleware/api.ts';
+export { auth } from './middleware/auth.ts';
+export type { UserRecord } from './middleware/auth.ts';
+export { ws } from './middleware/ws.ts';
+export { LoginForm } from './components/LoginForm.ts';
+export { Chat } from './components/Chat.ts';