weifuwu 0.33.1 → 0.33.2

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,21 @@
+/**
+ * weifuwu/client 应用 — 创建 ctx + 中间件链 + 挂载组件
+ *
+ * ```tsx
+ * import { createApp, router } from 'weifuwu/client'
+ *
+ * const app = createApp()
+ * 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) => void;
+};

package/dist/client/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * weifuwu/client — 响应式前端框架，TSX + Signal
+ *
+ * ```tsx
+ * import { signal, computed, Show, For, createApp, router, RouteView } from 'weifuwu/client'
+ * import type { WfuiContext } from 'weifuwu/client'
+ *
+ * const app = createApp()
+ * app.use(router({ routes: [
+ *   { path: '/', component: HomePage },
+ * ]}))
+ * 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';

package/dist/client/index.js

@@ -0,0 +1,320 @@
+// src/client/signal.ts
+var currentEffect = null;
+var Signal = class {
+  #value;
+  #listeners = /* @__PURE__ */ new Set();
+  constructor(value) {
+    this.#value = value;
+  }
+  get value() {
+    if (currentEffect) this.#listeners.add(currentEffect);
+    return this.#value;
+  }
+  set value(v) {
+    if (v !== this.#value) {
+      this.#value = v;
+      const fns = [...this.#listeners];
+      for (const fn of fns) fn();
+    }
+  }
+};
+function signal(initial) {
+  return new Signal(initial);
+}
+function isSignal(value) {
+  return value instanceof Signal;
+}
+function effect(fn) {
+  const wrapper = () => {
+    const prev = currentEffect;
+    currentEffect = wrapper;
+    try {
+      fn();
+    } finally {
+      currentEffect = prev;
+    }
+  };
+  wrapper();
+  return () => {
+  };
+}
+function computed(fn) {
+  const s = new Signal(void 0);
+  effect(() => {
+    s.value = fn();
+  });
+  return s;
+}
+
+// src/client/jsx-runtime.ts
+var currentCtx = null;
+function setCtx(ctx) {
+  currentCtx = ctx;
+}
+function setProp(el, key, value) {
+  if (key === "class" || key === "className") {
+    if (isSignal(value)) {
+      effect(() => {
+        el.className = String(value.value);
+      });
+    } else {
+      el.className = String(value ?? "");
+    }
+  } else if (key === "style" && typeof value === "object" && value !== null) {
+    Object.assign(el.style, value);
+  } else if (key.startsWith("on") && typeof value === "function") {
+    el.addEventListener(key.slice(2).toLowerCase(), value);
+  } else if (key === "ref" && typeof value === "function") {
+    value(el);
+  } else if (isSignal(value)) {
+    effect(() => {
+      const v = value.value;
+      if (v == null || v === false) el.removeAttribute(key);
+      else if (v === true) el.setAttribute(key, "");
+      else el.setAttribute(key, String(v));
+    });
+  } else if (value != null && value !== false) {
+    if (value === true) el.setAttribute(key, "");
+    else el.setAttribute(key, String(value));
+  }
+}
+function appendChild(parent, child) {
+  if (child == null || child === false || child === true) return;
+  if (Array.isArray(child)) {
+    child.forEach((c) => appendChild(parent, c));
+    return;
+  }
+  if (child instanceof Node) {
+    parent.appendChild(child);
+    return;
+  }
+  if (isSignal(child)) {
+    const text = document.createTextNode("");
+    effect(() => {
+      text.textContent = String(child.value);
+    });
+    parent.appendChild(text);
+    return;
+  }
+  parent.appendChild(document.createTextNode(String(child)));
+}
+function jsx(type, props, ...children) {
+  if (typeof type === "function") {
+    const merged = children.length > 0 ? { ...props, children } : props;
+    return type(merged, currentCtx) ?? document.createDocumentFragment();
+  }
+  const el = document.createElement(type);
+  if (props) {
+    for (const [k, v] of Object.entries(props)) {
+      if (k !== "children") setProp(el, k, v);
+    }
+  }
+  const childList = children.length > 0 ? children : props?.children != null ? [props.children] : [];
+  for (const child of childList) appendChild(el, child);
+  return el;
+}
+function jsxs(type, props, ...children) {
+  return jsx(type, props, ...children);
+}
+function jsxDEV(type, props, _key, _isStatic, _source, _self) {
+  return jsx(type, props, ...props?.children ? [props.children] : []);
+}
+function Fragment(props, ...children) {
+  const frag = document.createDocumentFragment();
+  for (const child of children) appendChild(frag, child);
+  return frag;
+}
+function domMount(root, app) {
+  const container = typeof root === "string" ? document.querySelector(root) : root;
+  if (!container) throw new Error(`mount target not found: ${root}`);
+  container.innerHTML = "";
+  container.appendChild(app);
+}
+function toNode(v) {
+  if (v instanceof Node) return v;
+  if (typeof v === "function") return toNode(v());
+  return document.createTextNode(String(v ?? ""));
+}
+function Show({ when, children, fallback }) {
+  const el = document.createElement("div");
+  function render(show) {
+    el.textContent = "";
+    if (show && children != null) {
+      el.appendChild(toNode(children));
+    } else if (!show && fallback != null) {
+      el.appendChild(toNode(fallback));
+    }
+  }
+  if (isSignal(when)) {
+    effect(() => render(Boolean(when.value)));
+  } else {
+    render(Boolean(when));
+  }
+  return el;
+}
+function For({ each, children }) {
+  const el = document.createElement("div");
+  function render(list) {
+    el.textContent = "";
+    for (let i = 0; i < list.length; i++) {
+      el.appendChild(children(list[i], i));
+    }
+  }
+  if (isSignal(each)) {
+    effect(() => render(each.value));
+  } else {
+    render(each);
+  }
+  return el;
+}
+
+// src/client/app.ts
+function createApp() {
+  const middlewares = [];
+  const provides = /* @__PURE__ */ new Map();
+  let ctx = {
+    route: {
+      path: window.location.pathname,
+      params: {},
+      query: Object.fromEntries(new URLSearchParams(window.location.search)),
+      hash: window.location.hash,
+      component: null
+    },
+    app: {
+      navigate(path) {
+        window.history.pushState({}, "", path);
+        ctx.route.path = path;
+        ctx.route.query = Object.fromEntries(new URLSearchParams(window.location.search));
+        ctx.route.hash = window.location.hash;
+        window.dispatchEvent(new CustomEvent("wefu:navigate", { detail: { path } }));
+      }
+    },
+    provide(key, value) {
+      provides.set(key, value);
+    },
+    inject(key) {
+      return provides.get(key) ?? null;
+    }
+  };
+  return {
+    get ctx() {
+      return ctx;
+    },
+    use(mw) {
+      middlewares.push(mw);
+      return this;
+    },
+    mount(rootSelector, RootComponent) {
+      for (const mw of middlewares) {
+        ctx = mw(ctx);
+      }
+      setCtx(ctx);
+      const app = jsx(RootComponent, {});
+      domMount(rootSelector, app);
+      setCtx(null);
+    }
+  };
+}
+
+// src/client/router.ts
+function router(opts) {
+  const mode = opts.mode ?? "hash";
+  const matchers = opts.routes.map((route) => {
+    const parts = route.path.split("/").filter(Boolean);
+    const keys = [];
+    const reStr = "^/" + parts.map((p) => {
+      if (p.startsWith(":")) {
+        keys.push(p.slice(1));
+        return "([^/]+)";
+      }
+      return p;
+    }).join("/") + "$";
+    return { re: new RegExp(reStr), keys, route };
+  });
+  function matchPath(path) {
+    for (const { re, keys, route } of matchers) {
+      const m = path.match(re);
+      if (m) {
+        const params = {};
+        keys.forEach((k, i) => {
+          params[k] = decodeURIComponent(m[i + 1]);
+        });
+        return { component: route.component, params, title: route.title, auth: route.auth };
+      }
+    }
+    return null;
+  }
+  return (ctx) => {
+    function handleRoute() {
+      const raw = mode === "hash" ? window.location.hash.slice(1) || "/" : window.location.pathname + window.location.search;
+      const [path, qs] = raw.split("?");
+      ctx.route.query = Object.fromEntries(new URLSearchParams(qs ?? ""));
+      const matched = matchPath(path);
+      if (matched) {
+        ctx.route.path = path;
+        ctx.route.params = matched.params;
+        ctx.route.component = matched.component;
+        ctx.route.title = matched.title;
+        ctx.route.auth = matched.auth;
+        if (matched.title) document.title = matched.title;
+        if (matched.auth && !ctx.user) {
+          setTimeout(() => ctx.app.navigate("/login"), 0);
+          return;
+        }
+      } else {
+        ctx.route.component = opts.notFound ?? null;
+      }
+      window.dispatchEvent(new CustomEvent("wefu:route", { detail: { path } }));
+    }
+    const origNavigate = ctx.app.navigate;
+    ctx.app.navigate = (path) => {
+      if (mode === "hash") {
+        window.location.hash = "#" + path;
+      } else {
+        window.history.pushState({}, "", path);
+        handleRoute();
+      }
+    };
+    if (mode === "hash") {
+      window.addEventListener("hashchange", handleRoute);
+    } else {
+      window.addEventListener("popstate", handleRoute);
+    }
+    handleRoute();
+    return ctx;
+  };
+}
+function RouteView(_props, ctx) {
+  const el = document.createElement("div");
+  function render() {
+    const Component = ctx.route.component;
+    if (!Component) {
+      el.textContent = "";
+      return;
+    }
+    el.textContent = "";
+    setCtx(ctx);
+    const page = jsx(Component, {});
+    el.appendChild(page);
+    setCtx(null);
+  }
+  render();
+  window.addEventListener("wefu:route", render);
+  return el;
+}
+export {
+  For,
+  Fragment,
+  RouteView,
+  Show,
+  computed,
+  createApp,
+  domMount,
+  effect,
+  isSignal,
+  jsx,
+  jsxDEV,
+  jsxs,
+  router,
+  signal
+};

package/dist/client/jsx-runtime.d.ts

@@ -0,0 +1,60 @@
+/**
+ * weifuwu/client JSX runtime — TSX 编译目标
+ *
+ * esbuild: --jsx=automatic --jsxImportSource=weifuwu/client
+ * tsconfig: "jsx": "react-jsx", "jsxImportSource": "weifuwu/client"
+ *
+ * createElement 直接创建真实 DOM 节点。
+ * Signal 值自动绑定：.value 变化时只更新对应 DOM 节点。
+ * 组件签名：(props, ctx) => JSX
+ */
+import { type Signal } from './signal.ts';
+import type { WfuiContext } from './types.ts';
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            [tag: string]: any;
+        }
+    }
+}
+export declare function setCtx(ctx: WfuiContext | null): void;
+export declare function getCtx(): WfuiContext | null;
+export type Component<P = {}> = (props: P, ctx: WfuiContext) => Node;
+export declare function jsx(type: string | Component, props: Record<string, unknown> | null, ...children: unknown[]): Node;
+export declare function jsxs(type: string | Component, props: Record<string, unknown> | null, ...children: unknown[]): Node;
+export declare function jsxDEV(type: string | Component, props: Record<string, unknown> | null, _key: string | null, _isStatic: boolean, _source: {
+    fileName: string;
+    lineNumber: number;
+}, _self: unknown): Node;
+export declare function Fragment(props: Record<string, unknown> | null, ...children: unknown[]): Node;
+/**
+ * 直接挂载 DOM（低层 API，一般用 createApp().mount()）
+ */
+export declare function domMount(root: string | Element, app: Node): void;
+/**
+ * 条件渲染 — when 为 Signal 时响应式切换
+ *
+ * ```tsx
+ * <Show when={isLoggedIn} fallback={<LoginPage />}>
+ *   <ChatPage />
+ * </Show>
+ * ```
+ */
+export declare function Show({ when, children, fallback }: {
+    when: boolean | Signal<boolean>;
+    children?: Node | (() => Node);
+    fallback?: Node | (() => Node);
+}): Node;
+/**
+ * 列表渲染 — each 为 Signal 时响应式更新
+ *
+ * ```tsx
+ * <For each={items}>
+ *   {(item) => <div>{item.name}</div>}
+ * </For>
+ * ```
+ */
+export declare function For<T>({ each, children }: {
+    each: T[] | Signal<T[]>;
+    children: (item: T, index: number) => Node;
+}): Node;