weifuwu 0.34.0 → 0.35.0

package/README.md

@@ -315,28 +315,34 @@ esbuild.build({
 })
 ```
 
-### 状态管理
+### 状态管理 — 深度 Proxy
+
+`ctx.ui.$` 是**深度 Proxy**：任何属性/数组/对象层面的写入自动触发渲染，无需手动调用。
 
 ```tsx
-const $ = ctx.ui.$                         // 获取状态对象
+const $ = ctx.ui.$
+
+// 顶层属性赋值
+$.count = 0                                // → 自动渲染
+$.user = { name: 'alice' }                 // → 新值自动深度包装
 
-$.count = 0                                // 赋值 → 自动渲染
-$.items = [...$.items, newItem]            // 不可变更新
-$.items.push(newItem); ctx.ui.dirty()      // 可变更新需显式 dirty
+// 数组突变
+$.items.push(newItem)                      // → 自动渲染
+$.items.pop()                              // → 自动渲染
+$.items.splice(i, 1)                       // → 自动渲染
 
-// 派生值 — 每次 render 重新计算
-const doubled = $.count * 2
-const completed = $.todos.filter(t => t.done)
+// 对象属性突变（数组内部也支持）
+$.items[0].done = true                     // → 自动渲染
+$.msgs[idx].content += event.text          // → 自动渲染
+
+// 不可变更新（同样支持）
+$.items = [...$.items, newItem]
 ```
 
 | API | 说明 |
 |------|------|
-| `ctx.ui.$` | 状态代理对象，赋值自动触发渲染 |
-| `ctx.ui.dirty()` | 显式标记脏状态（嵌套突变后用） |
-| `ctx.ui.render()` | 同步立即渲染 |
-
-**原理**：`ctx.ui.$` 是 Proxy 对象，任何属性赋值（`$.x = val`）自动调用 `queueMicrotask(render)`。\
-多次赋值在同一个微任务内合并为一次渲染。
+| `ctx.ui.$` | 深度 Proxy 对象，所有写入自动触发渲染 |
+| `ctx.ui.dirty()` | ⚠ 极少需要 — 仅当绕过 Proxy 直接操作底层对象时 |
 
 ### JSX 运行时
 

package/dist/client/app.d.ts

@@ -7,6 +7,13 @@
  *   ctx.ui.render()    触发组件重渲染
  *   ctx.ui.$          持久化组件状态（由渲染器管理）
  *   ctx.ui.ready       首次执行标记（由渲染器管理）
+ *
+ * ctx.ui.$ 是深度 Proxy：
+ *   $.x = val              → 自动渲染（顶层属性赋值）
+ *   $.items.push(val)      → 自动渲染（数组突变方法）
+ *   $.items[0].x = val     → 自动渲染（对象属性突变）
+ *   $.items.push({x: 1})   → 新对象自动深度包装
+ *   ctx.ui.dirty()         → 极少需要（仅当绕过 Proxy 直接操作底层对象）
  */
 import type { WfuiContext, AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';

package/dist/client/error-boundary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ErrorBoundary — 错误边界组件
+ *
+ * 捕获子组件渲染时的错误，展示 fallback 替代崩溃白屏。
+ *
+ * ```tsx
+ * <ErrorBoundary fallback={<p>出错了</p>}>
+ *   <UserProfile />
+ * </ErrorBoundary>
+ * ```
+ *
+ * 基于 ctx.ui._errorHandler 机制：在渲染子组件前注入错误处理器，
+ * 子组件 render 抛错时设置 $.error → 重新渲染 fallback。
+ */
+import type { WfuiContext } from './types.ts';
+import type { VNode } from './vnode.ts';
+export interface ErrorBoundaryProps {
+    fallback?: VNode | ((props: {
+        error: unknown;
+    }) => VNode) | null;
+    children?: any;
+}
+export declare function ErrorBoundary(props: ErrorBoundaryProps, ctx: WfuiContext): VNode | null;

package/dist/client/index.d.ts

@@ -27,3 +27,5 @@ export { ApiError } from './middleware/api.ts';
 export type { AuthClient, AuthOptions } from './middleware/auth.ts';
 export { extendCtx } from './types.ts';
 export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
+export { ErrorBoundary } from './error-boundary.ts';
+export type { ErrorBoundaryProps } from './error-boundary.ts';

package/dist/client/index.js

@@ -59,7 +59,19 @@ function renderComponent(Comp, props, vnode, ctx) {
   if (!prev$) vnode._$ = {};
   ctx.ui = ctx.ui ?? {};
   ctx.ui.ready = !!prev$;
-  const childVNode = Comp(props, ctx);
+  let childVNode;
+  try {
+    childVNode = Comp(props, ctx);
+  } catch (e) {
+    const errHandler = ctx.ui?._errorHandler;
+    if (errHandler) {
+      errHandler(e);
+      childVNode = null;
+    } else {
+      console.error("Component render error:", e);
+      childVNode = null;
+    }
+  }
   if (childVNode == null) {
     vnode._child = null;
     return document.createTextNode("");
@@ -150,11 +162,9 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
     if (oldV._$) newV._$ = oldV._$;
     ctx.ui = ctx.ui ?? {};
     ctx.ui.ready = !!newV._$;
-    const childOld = oldV._child != null ? oldV._child : comp(oldV.props, ctx);
-    ctx.ui.ready = !!newV._$;
     const childNew = comp(newV.props, ctx);
     newV._child = childNew;
-    return patchValue(parent, oldNode, childOld, childNew, ctx);
+    return patchValue(parent, oldNode, oldV._child, childNew, ctx);
   }
   if (newV.type === Fragment) {
     patchChildren(parent, oldV, newV, ctx);
@@ -330,88 +340,6 @@ function callRef(input, el) {
   forEach(vnode.props?.children, (child) => callRef(child, el));
 }
 
-// src/client/app.ts
-function createApp() {
-  const middlewares = [];
-  let ctx = {};
-  let container = null;
-  let rootComponent = null;
-  let oldVNode = null;
-  let rendered = false;
-  const app = {
-    get ctx() {
-      return ctx;
-    },
-    use(mw) {
-      middlewares.push(mw);
-      return app;
-    },
-    async mount(rootSelector, RootComponent) {
-      rootComponent = RootComponent;
-      for (const mw of middlewares) {
-        ctx = await mw(ctx);
-      }
-      const el = typeof rootSelector === "string" ? document.querySelector(rootSelector) : rootSelector;
-      if (!el) throw new Error(`mount target not found: ${rootSelector}`);
-      container = el;
-      container.innerHTML = "";
-      let _dirty = false;
-      const $target = {};
-      ctx.ui = {
-        render: () => {
-          if (!container || !rootComponent || !oldVNode) return;
-          _dirty = false;
-          ctx._rvDepth = 0;
-          const newVNode = wrapComponent(rootComponent, ctx);
-          const oldNode = container.firstChild;
-          if (oldNode) {
-            patchValue(container, oldNode, oldVNode, newVNode, ctx);
-          }
-          oldVNode = newVNode;
-        },
-        /** 显式标记脏（用于嵌套突变如 push、arr[i].x +=） */
-        dirty: () => {
-          if (_dirty) return;
-          _dirty = true;
-          queueMicrotask(() => {
-            if (!_dirty) return;
-            _dirty = false;
-            ctx.ui.render();
-          });
-        },
-        $: new Proxy($target, {
-          set(_target, key, val) {
-            _target[key] = val;
-            if (!_dirty) {
-              _dirty = true;
-              queueMicrotask(() => {
-                if (!_dirty) return;
-                _dirty = false;
-                ctx.ui.render();
-              });
-            }
-            return true;
-          }
-        }),
-        ready: false
-      };
-      oldVNode = wrapComponent(RootComponent, ctx);
-      const node = render(oldVNode, ctx);
-      if (node instanceof Node) container.appendChild(node);
-      rendered = true;
-    },
-    destroy() {
-      if (container) container.innerHTML = "";
-      container = null;
-      ctx = {};
-    }
-  };
-  return app;
-}
-function wrapComponent(Comp, _ctx) {
-  return { type: Comp, props: {}, key: void 0 };
-}
-
 // src/client/router.ts
 function flattenRoutes(routes, basePath = "", chain = []) {
   const result = [];
@@ -426,6 +354,7 @@ function flattenRoutes(routes, basePath = "", chain = []) {
   }
   return result;
 }
+var layoutDepth = /* @__PURE__ */ new WeakMap();
 function joinPaths(a, b) {
   if (!b || b === "/") return a || "/";
   const left = a.endsWith("/") ? a.slice(0, -1) : a;
@@ -451,6 +380,14 @@ function matchRoute(path, routes) {
 }
 function router(opts) {
   const flatRoutes = flattenRoutes(opts.routes);
+  const mode = opts.mode || "history";
+  function getPath() {
+    if (mode === "hash") {
+      const hash = window.location.hash.replace(/^#/, "") || "/";
+      return hash;
+    }
+    return window.location.pathname;
+  }
   function resolve(path) {
     const match = matchRoute(path, flatRoutes);
     if (match) {
@@ -471,20 +408,30 @@ function router(opts) {
     return { path, params: {}, query: {}, chain: [] };
   }
   return (ctx) => {
-    const resolved = resolve(window.location.pathname);
+    const resolved = resolve(getPath());
     ctx.route = resolved;
     if (!ctx.app) ctx.app = {};
     ctx.app.navigate = (path) => {
-      window.history.pushState({}, "", path);
-      const resolved2 = resolve(path);
-      ctx.route = resolved2;
+      if (mode === "hash") {
+        window.location.hash = "#" + path;
+        const resolved2 = resolve(path);
+        ctx.route = resolved2;
+      } else {
+        window.history.pushState({}, "", path);
+        const resolved2 = resolve(path);
+        ctx.route = resolved2;
+      }
       ctx.ui?.render();
     };
-    window.addEventListener("popstate", () => {
-      const resolved2 = resolve(window.location.pathname);
+    const onPop = () => {
+      const resolved2 = resolve(getPath());
       ctx.route = resolved2;
       ctx.ui?.render();
-    });
+    };
+    window.addEventListener("popstate", onPop);
+    if (mode === "hash") {
+      window.addEventListener("hashchange", onPop);
+    }
     return ctx;
   };
 }
@@ -492,12 +439,135 @@ function RouteView(_props, ctx) {
   const route = ctx.route;
   if (!route?.chain?.length) return null;
   const ctxAny = ctx;
-  const depth = ctxAny._rvDepth ?? 0;
+  const depth = layoutDepth.get(ctxAny) ?? 0;
   if (depth >= route.chain.length) return null;
   const def = route.chain[depth];
   const Comp = def.layout ?? def.component;
   if (!Comp) return null;
-  if (def.layout) ctxAny._rvDepth = depth + 1;
+  if (def.layout) {
+    layoutDepth.set(ctxAny, depth + 1);
+  }
+  return { type: Comp, props: {}, key: void 0 };
+}
+
+// src/client/app.ts
+var mutationMethods = ["push", "pop", "splice", "shift", "unshift", "sort", "reverse"];
+var wrappedCache = /* @__PURE__ */ new WeakMap();
+function wrapDeep(val, dirty) {
+  if (val === null || typeof val !== "object") return val;
+  if (val instanceof Node) return val;
+  if (wrappedCache.has(val)) return wrappedCache.get(val);
+  let proxy;
+  if (Array.isArray(val)) {
+    proxy = new Proxy(val, {
+      get(target, key, receiver) {
+        const v = Reflect.get(target, key, receiver);
+        if (typeof key === "string" && mutationMethods.includes(key) && typeof v === "function") {
+          return function(...args) {
+            const r = v.apply(target, args);
+            dirty();
+            return r;
+          };
+        }
+        return wrapDeep(v, dirty);
+      },
+      set(target, key, val2) {
+        target[key] = wrapDeep(val2, dirty);
+        dirty();
+        return true;
+      }
+    });
+  } else {
+    proxy = new Proxy(val, {
+      get(_target, key, receiver) {
+        const v = Reflect.get(_target, key, receiver);
+        return wrapDeep(v, dirty);
+      },
+      set(target, key, val2) {
+        target[key] = wrapDeep(val2, dirty);
+        dirty();
+        return true;
+      }
+    });
+  }
+  wrappedCache.set(val, proxy);
+  return proxy;
+}
+function createApp() {
+  const middlewares = [];
+  let ctx = {};
+  let container = null;
+  let rootComponent = null;
+  let oldVNode = null;
+  let rendered = false;
+  const app = {
+    get ctx() {
+      return ctx;
+    },
+    use(mw) {
+      middlewares.push(mw);
+      return app;
+    },
+    async mount(rootSelector, RootComponent) {
+      rootComponent = RootComponent;
+      for (const mw of middlewares) {
+        ctx = await mw(ctx);
+      }
+      const el = typeof rootSelector === "string" ? document.querySelector(rootSelector) : rootSelector;
+      if (!el) throw new Error(`mount target not found: ${rootSelector}`);
+      container = el;
+      container.innerHTML = "";
+      let _dirty = false;
+      function scheduleRender() {
+        if (_dirty) return;
+        _dirty = true;
+        queueMicrotask(() => {
+          if (!_dirty) return;
+          _dirty = false;
+          ctx.ui.render();
+        });
+      }
+      const $target = {};
+      ctx.ui = {
+        render: () => {
+          if (!container || !rootComponent || !oldVNode) return;
+          _dirty = false;
+          layoutDepth.delete(ctx);
+          const newVNode = wrapComponent(rootComponent, ctx);
+          const oldNode = container.firstChild;
+          if (oldNode) {
+            patchValue(container, oldNode, oldVNode, newVNode, ctx);
+          }
+          oldVNode = newVNode;
+        },
+        /** 极少需要：仅当绕过 Proxy 直接操作底层对象时使用 */
+        dirty: () => {
+          scheduleRender();
+        },
+        $: new Proxy($target, {
+          set(_target, key, val) {
+            _target[key] = wrapDeep(val, scheduleRender);
+            scheduleRender();
+            return true;
+          }
+        }),
+        ready: false
+      };
+      oldVNode = wrapComponent(RootComponent, ctx);
+      const node = render(oldVNode, ctx);
+      if (node instanceof Node) container.appendChild(node);
+      _dirty = false;
+      rendered = true;
+    },
+    destroy() {
+      if (container) container.innerHTML = "";
+      container = null;
+      ctx = {};
+    }
+  };
+  return app;
+}
+function wrapComponent(Comp, _ctx) {
   return { type: Comp, props: {}, key: void 0 };
 }
 
@@ -761,8 +831,38 @@ function auth(options) {
     return extendCtx(ctx, { auth: authClient });
   };
 }
+
+// src/client/error-boundary.ts
+function ErrorBoundary(props, ctx) {
+  const $ = ctx.ui.$;
+  if (!("error" in $)) $.error = null;
+  if ($.error) {
+    const fb = props.fallback;
+    if (typeof fb === "function") {
+      return fb({ error: $.error });
+    }
+    return fb ?? null;
+  }
+  ;
+  ctx.ui._errorHandler = (err) => {
+    $.error = err;
+    ctx.ui.dirty();
+  };
+  try {
+    const result = props.children;
+    return result ?? null;
+  } catch (e) {
+    $.error = e;
+    const fb = props.fallback;
+    if (typeof fb === "function") {
+      return fb({ error: e });
+    }
+    return fb ?? null;
+  }
+}
 export {
   ApiError,
+  ErrorBoundary,
   Fragment,
   RouteView,
   api,

package/dist/client/router.d.ts

@@ -9,5 +9,6 @@ export interface RouterOptions {
     routes: RouteDef[];
     notFound?: (props: any, ctx: WfuiContext) => any;
 }
+export declare const layoutDepth: WeakMap<any, number>;
 export declare function router(opts: RouterOptions): AppMiddleware;
 export declare function RouteView(_props: {}, ctx: WfuiContext): any;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {