weifuwu 0.55.3 → 0.56.0

package/dist/client/index.js

@@ -1,4 +1,13 @@
 // src/client/vnode.ts
+var ASYNC_MARK = "__wfAsyncComponent";
+function asyncComponent(factory) {
+  const fn = factory;
+  fn[ASYNC_MARK] = true;
+  return fn;
+}
+function isAsyncComponent(type) {
+  return typeof type === "function" && type?.[ASYNC_MARK] === true;
+}
 var Fragment = /* @__PURE__ */ Symbol("Fragment");
 var Portal = /* @__PURE__ */ Symbol("Portal");
 function jsx(type, props, key) {
@@ -56,10 +65,11 @@ function renderValue(v, ctx) {
   }
   if (vnode.type === Fragment) {
     const frag = document.createDocumentFragment();
-    forEach(vnode.props?.children, (child) => {
+    const children = vnode.props?.children == null ? [] : Array.isArray(vnode.props.children) ? vnode.props.children : [vnode.props.children];
+    for (const child of children) {
       const node = renderValue(child, ctx);
       if (node != null) frag.appendChild(node);
-    });
+    }
     return frag;
   }
   if (typeof vnode.type === "function") {
@@ -102,6 +112,60 @@ function renderValue(v, ctx) {
   if (typeof vnode.props?.ref === "function") vnode.props.ref(el);
   return el;
 }
+var asyncFactoryCache = /* @__PURE__ */ new WeakMap();
+function clearAsyncComponentCache() {
+  asyncFactoryCache = /* @__PURE__ */ new WeakMap();
+}
+function startAsyncFactory(Comp, ctx) {
+  const existing = asyncFactoryCache.get(Comp);
+  if (existing) return existing;
+  const entry = { promise: null };
+  entry.promise = Promise.resolve().then(() => Comp(ctx)).then((def) => {
+    if (typeof def !== "function") {
+      throw new Error(
+        `asyncComponent factory <${Comp.name || "anonymous"}> must return a Component (initProps, ctx) => (props) => VNode.`
+      );
+    }
+    entry.resolved = def;
+    return def;
+  });
+  asyncFactoryCache.set(Comp, entry);
+  return entry;
+}
+async function resolveAsyncFactory(Comp, ctx) {
+  return startAsyncFactory(Comp, ctx).promise;
+}
+function resolveAsyncFactorySync(Comp) {
+  return asyncFactoryCache.get(Comp)?.resolved;
+}
+function scheduleFullReRender(ctx) {
+  const ui = ctx.ui;
+  if (ui && typeof ui.render === "function") ui.render(["_wf_root"]);
+}
+function mountComponent(Comp, props, vnode, ctx) {
+  let def;
+  if (isAsyncComponent(Comp)) {
+    def = resolveAsyncFactorySync(Comp);
+    if (!def) {
+      void startAsyncFactory(Comp, ctx).promise.then(
+        () => scheduleFullReRender(ctx),
+        () => {
+        }
+      );
+      return null;
+    }
+  } else {
+    def = Comp;
+  }
+  let childVNode = def(props, ctx);
+  if (typeof childVNode !== "function") {
+    throw new Error(
+      `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
+    );
+  }
+  vnode._render = childVNode;
+  return childVNode(props);
+}
 function renderComponent(Comp, props, vnode, ctx) {
   ;
   ctx.ui = ctx.ui ?? {};
@@ -116,14 +180,7 @@ function renderComponent(Comp, props, vnode, ctx) {
   vnode._ctxVersion = childCtx.ui._ctxVersion ?? 0;
   let childVNode;
   try {
-    childVNode = Comp(props, childCtx);
-    if (typeof childVNode !== "function") {
-      throw new Error(
-        `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
-      );
-    }
-    vnode._render = childVNode;
-    childVNode = childVNode(props);
+    childVNode = mountComponent(Comp, props, vnode, childCtx);
   } catch (e) {
     const errHandler = ctx.ui?._errorHandler;
     if (errHandler) {
@@ -193,14 +250,6 @@ function patchPortal(oldV, newV, ctx) {
   ensureKeys(oldChildren, newChildren);
   patchKeyedChildren(sub, oldChildren, newChildren, ctx);
 }
-function forEach(children, fn) {
-  if (children == null) return;
-  if (Array.isArray(children)) {
-    children.forEach(fn);
-    return;
-  }
-  fn(children);
-}
 function flattenChildren(children) {
   if (children == null) return [];
   if (!Array.isArray(children)) return [children];
@@ -300,11 +349,7 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
       if (typeof newV._render === "function") {
         childNew = newV._render(newV.props);
       } else {
-        childNew = comp(newV.props, childCtx);
-        if (typeof childNew === "function") {
-          newV._render = childNew;
-          childNew = childNew(newV.props);
-        }
+        childNew = mountComponent(comp, newV.props, newV, childCtx);
       }
     } catch (e) {
       const errHandler = ctx.ui?._errorHandler;
@@ -395,8 +440,8 @@ function patchProps(el, oldProps, newProps) {
       if (newVal !== oldVal) el.innerHTML = String(newVal ?? "");
     } else if (newVal !== oldVal) {
       if (key === "class" || key === "className") {
-        if (el instanceof SVGElement) el.setAttribute("class", String(newVal ?? ""));
-        else el.className = String(newVal ?? "");
+        if (el instanceof SVGElement) el.setAttribute("class", classToString(newVal));
+        else el.className = classToString(newVal);
       } else if (key === "style" && typeof newVal === "object") {
         const st = el.style;
         for (const sk of Object.keys(newVal)) {
@@ -425,6 +470,14 @@ function patchProps(el, oldProps, newProps) {
     }
   }
 }
+function classToString(v) {
+  if (typeof v === "string") return v;
+  if (Array.isArray(v)) return v.filter(Boolean).join(" ");
+  if (v && typeof v === "object") {
+    return Object.entries(v).filter(([, b]) => b).map(([k]) => k).join(" ");
+  }
+  return "";
+}
 function getKey(input) {
   if (input == null || typeof input !== "object") return void 0;
   return input.key;
@@ -628,6 +681,192 @@ function callRefCleanup(input) {
     vnode._remoteEl = void 0;
   }
 }
+function cursorAdvance(c) {
+  c.node = c.node ? c.node.nextSibling : null;
+}
+function cursorInsert(c, n) {
+  if (c.node && c.node.parentNode) c.node.parentNode.insertBefore(n, c.node);
+  else c.parent.appendChild(n);
+}
+function cursorReplace(c, n) {
+  if (c.node && c.node.parentNode) {
+    c.node.parentNode.replaceChild(n, c.node);
+    cursorAdvance(c);
+  } else {
+    c.parent.appendChild(n);
+  }
+}
+async function renderValueHydrating(v, ctx, c) {
+  if (v == null || typeof v === "boolean") return null;
+  if (typeof v === "string" || typeof v === "number") {
+    const text = String(v);
+    if (c.node && c.node.nodeType === 3) {
+      if (c.node.textContent !== text) c.node.textContent = text;
+      cursorAdvance(c);
+      return c.node;
+    }
+    const tn = document.createTextNode(text);
+    cursorInsert(c, tn);
+    return tn;
+  }
+  if (Array.isArray(v)) {
+    let first = null;
+    for (const item of v) {
+      const n = await renderValueHydrating(item, ctx, c);
+      if (n != null && !first) first = n;
+    }
+    return first;
+  }
+  const vnode = v;
+  if (vnode.type === Portal || vnode.type === Fragment) {
+    const children = vnode.props?.children;
+    const arr = children == null ? [] : Array.isArray(children) ? children : [children];
+    let first = null;
+    for (const child of arr) {
+      const n = await renderValueHydrating(child, ctx, c);
+      if (n != null && !first) first = n;
+    }
+    return first;
+  }
+  if (typeof vnode.type === "function") {
+    return renderComponentHydrating(vnode, ctx, c);
+  }
+  const tag = vnode.type;
+  const props = vnode.props ?? {};
+  let el;
+  if (c.node && c.node.nodeType === 1 && c.node.tagName.toLowerCase() === tag.toLowerCase()) {
+    el = c.node;
+    cursorAdvance(c);
+  } else {
+    el = SVG_TAGS.has(tag) ? document.createElementNS(SVG_NS, tag) : document.createElement(tag);
+    cursorReplace(c, el);
+  }
+  vnode.el = el;
+  patchProps(el, null, props);
+  if ("innerHTML" in props) {
+  } else {
+    const childCursor = { parent: el, node: el.firstChild };
+    const children = flattenChildren(props.children);
+    for (const child of children) {
+      const n = await renderValueHydrating(child, ctx, childCursor);
+      if (n != null && n.parentNode !== el) el.appendChild(n);
+      if (child && typeof child === "object" && typeof child.type === "function") {
+        const childVNode = child;
+        if (!childVNode._parentNode) {
+          childVNode._parentNode = el;
+          childVNode._refNode = n;
+        }
+      }
+    }
+    while (childCursor.node) {
+      const n = childCursor.node;
+      childCursor.node = n.nextSibling;
+      n.parentNode?.removeChild(n);
+    }
+  }
+  if ("value" in props && el instanceof HTMLSelectElement) {
+    ;
+    el.value = String(props.value ?? "");
+  }
+  if (typeof props.ref === "function") props.ref(el);
+  return el;
+}
+async function renderComponentHydrating(vnode, ctx, c) {
+  ;
+  ctx.ui = ctx.ui ?? {};
+  if (!vnode._id) {
+    vnode._id = `_wf_${_idCounter++}`;
+    idRegistry.set(vnode._id, vnode);
+  }
+  const childCtx = Object.create(ctx);
+  childCtx.ui = Object.create(ctx.ui);
+  childCtx.ui._selfId = vnode._id;
+  childCtx.ui._selfVNode = vnode;
+  vnode._ctxVersion = childCtx.ui._ctxVersion ?? 0;
+  const Comp = vnode.type;
+  let childVNode;
+  try {
+    let def;
+    if (isAsyncComponent(Comp)) {
+      def = await resolveAsyncFactory(Comp, childCtx);
+    } else {
+      def = Comp;
+    }
+    const renderFn = def(vnode.props ?? {}, childCtx);
+    if (typeof renderFn !== "function") {
+      throw new Error(
+        `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
+      );
+    }
+    vnode._render = renderFn;
+    childVNode = renderFn(vnode.props ?? {});
+  } catch (e) {
+    const errHandler = ctx.ui?._errorHandler;
+    if (errHandler) {
+      errHandler(e);
+      childVNode = null;
+    } else {
+      console.error(
+        `[weifuwu] Component hydration error in <${Comp.name || "anonymous"}> (id: ${vnode._id ?? "?"})`,
+        e
+      );
+      childVNode = null;
+    }
+  }
+  if (childVNode == null) {
+    vnode._child = null;
+    return null;
+  }
+  vnode._child = childVNode;
+  const domNode = await renderValueHydrating(childVNode, childCtx, c);
+  if (!vnode._refNode) {
+    ;
+    vnode._refNode = domNode;
+  }
+  return domNode;
+}
+async function hydrateVNode(container, vnode, ctx) {
+  const cursor = { parent: container, node: container.firstChild };
+  await renderValueHydrating(vnode, ctx, cursor);
+  while (cursor.node) {
+    const n = cursor.node;
+    cursor.node = n.nextSibling;
+    n.parentNode?.removeChild(n);
+  }
+}
+
+// src/client/reactive.ts
+function createReactiveState(dirty) {
+  const proxyCache = /* @__PURE__ */ new WeakMap();
+  const reactive = (target) => {
+    if (target === null || typeof target !== "object") return target;
+    if (proxyCache.has(target)) return proxyCache.get(target);
+    const proxy = new Proxy(target, {
+      set(target2, key, value) {
+        const old = Reflect.get(target2, key);
+        if (old === value) return true;
+        Reflect.set(target2, key, value);
+        dirty();
+        return true;
+      },
+      get(target2, key) {
+        const value = Reflect.get(target2, key);
+        if (typeof value === "object" && value !== null) return reactive(value);
+        return value;
+      },
+      deleteProperty(target2, key) {
+        if (Reflect.has(target2, key)) {
+          Reflect.deleteProperty(target2, key);
+          dirty();
+        }
+        return true;
+      }
+    });
+    proxyCache.set(target, proxy);
+    return proxy;
+  };
+  return reactive({});
+}
 
 // src/client/app.ts
 function createApp() {
@@ -724,7 +963,7 @@ function createApp() {
       middlewares.push(mw);
       return app;
     },
-    async mount(rootSelector, RootComponent) {
+    async mount(rootSelector, RootComponent, options) {
       rootComponent = RootComponent;
       for (const mw of middlewares) {
         ctx = await mw(ctx);
@@ -732,7 +971,36 @@ function createApp() {
       const el = typeof rootSelector === "string" ? document.querySelector(rootSelector) : rootSelector;
       if (!el) throw new Error(`mount target not found: ${rootSelector}`);
       container = el;
-      container.innerHTML = "";
+      const hydrating = !!options?.hydrate;
+      if (!hydrating) container.innerHTML = "";
+      const dataCache = /* @__PURE__ */ new Map();
+      const hydratedData = globalThis.__DATA__;
+      if (hydratedData && typeof hydratedData === "object") {
+        for (const [k, v] of Object.entries(hydratedData)) {
+          dataCache.set(k, { value: v });
+        }
+      }
+      ;
+      ctx.data = {
+        async get(key, fetcher) {
+          const entry = dataCache.get(key);
+          if (entry && "value" in entry) return entry.value;
+          if (entry?.promise) return entry.promise;
+          if (!fetcher) return void 0;
+          const promise = Promise.resolve().then(() => fetcher()).then((val) => {
+            dataCache.set(key, { value: val });
+            return val;
+          });
+          dataCache.set(key, { promise });
+          return promise;
+        },
+        set(key, value) {
+          dataCache.set(key, { value });
+        },
+        has(key) {
+          return dataCache.has(key);
+        }
+      };
       ctx.ui = {
         _selfId: "_wf_root",
         // ── ctx 版本号（供三态 skip 判定） ──
@@ -852,16 +1120,16 @@ function createApp() {
          * pos 是稳定对象，render 闭包直接读取 top/left；
          * 滚动/resize 时自动重算并定向刷新；打开弹层瞬间调用 pos.refresh()。
          */
-        usePopupPosition: function(options) {
+        usePopupPosition: function(options2) {
           const selfId = getSelfId(this);
           const pos = { top: 0, left: 0, refresh: () => {
           } };
           if (!selfId) return pos;
           const tracker = {
             pos,
-            getEl: options.el,
-            isOpen: options.isOpen,
-            compute: options.compute
+            getEl: options2.el,
+            isOpen: options2.isOpen,
+            compute: options2.compute
           };
           _popupTrackers.set(selfId, tracker);
           if (!_popupListenersReady) {
@@ -896,10 +1164,14 @@ function createApp() {
       oldVNode = wrapComponent(RootComponent, ctx);
       oldVNode._id = "_wf_root";
       oldVNode._parentNode = container;
-      oldVNode._refNode = null;
+      oldVNode._refNode = hydrating ? container.firstChild : null;
       idRegistry.set("_wf_root", oldVNode);
-      const node = render(oldVNode, ctx);
-      if (node instanceof Node) container.appendChild(node);
+      if (hydrating) {
+        await hydrateVNode(container, oldVNode, ctx);
+      } else {
+        const node = render(oldVNode, ctx);
+        if (node instanceof Node) container.appendChild(node);
+      }
       oldVNode._refNode = container.firstChild;
       _rendering = false;
       flushDirtyBatch();
@@ -921,52 +1193,8 @@ function createApp() {
 function wrapComponent(Comp, _ctx) {
   return { type: Comp, props: {}, key: void 0 };
 }
-function createReactiveState(dirty) {
-  const proxyCache = /* @__PURE__ */ new WeakMap();
-  const reactive = (target) => {
-    if (target === null || typeof target !== "object") return target;
-    if (proxyCache.has(target)) return proxyCache.get(target);
-    const proxy = new Proxy(target, {
-      set(target2, key, value) {
-        const old = Reflect.get(target2, key);
-        if (old === value) return true;
-        Reflect.set(target2, key, value);
-        dirty();
-        return true;
-      },
-      get(target2, key) {
-        const value = Reflect.get(target2, key);
-        if (typeof value === "object" && value !== null) return reactive(value);
-        return value;
-      },
-      deleteProperty(target2, key) {
-        if (Reflect.has(target2, key)) {
-          Reflect.deleteProperty(target2, key);
-          dirty();
-        }
-        return true;
-      }
-    });
-    proxyCache.set(target, proxy);
-    return proxy;
-  };
-  return reactive({});
-}
 
-// src/client/router.ts
-function flattenRoutes(routes, basePath = "", chain = []) {
-  const result = [];
-  for (const route of routes) {
-    const fullPath = joinPaths(basePath, route.path);
-    const { re, keys } = compilePath(fullPath);
-    const fullChain = [...chain, route];
-    result.push({ re, keys, def: route, chain: fullChain });
-    if (route.children) {
-      result.push(...flattenRoutes(route.children, fullPath, fullChain));
-    }
-  }
-  return result;
-}
+// src/client/route-match.ts
 function joinPaths(a, b) {
   if (!b || b === "/") return a || "/";
   const left = a.endsWith("/") ? a.slice(0, -1) : a;
@@ -981,6 +1209,19 @@ function compilePath(path) {
   }).replace(/\*/g, ".*");
   return { re: new RegExp(`^${reStr}$`), keys };
 }
+function flattenRoutes(routes, basePath = "", chain = []) {
+  const result = [];
+  for (const route of routes) {
+    const fullPath = joinPaths(basePath, route.path);
+    const { re, keys } = compilePath(fullPath);
+    const fullChain = [...chain, route];
+    result.push({ re, keys, def: route, chain: fullChain });
+    if (route.children) {
+      result.push(...flattenRoutes(route.children, fullPath, fullChain));
+    }
+  }
+  return result;
+}
 function matchRoute(path, routes) {
   let best = null;
   for (const fr of routes) {
@@ -990,6 +1231,18 @@ function matchRoute(path, routes) {
   }
   return best;
 }
+function extractParams(path, match) {
+  const params = {};
+  const m = path.match(match.re);
+  if (m) {
+    for (let i = 0; i < match.keys.length; i++) {
+      params[match.keys[i]] = decodeURIComponent(m[i + 1]);
+    }
+  }
+  return params;
+}
+
+// src/client/router.ts
 function router(opts) {
   const flatRoutes = flattenRoutes(opts.routes);
   const mode = opts.mode || "history";
@@ -1003,17 +1256,10 @@ function router(opts) {
   function resolve(path) {
     const match = matchRoute(path, flatRoutes);
     if (match) {
-      const params = {};
-      const m = path.match(match.re);
-      if (m) {
-        for (let i = 0; i < match.keys.length; i++) {
-          params[match.keys[i]] = decodeURIComponent(m[i + 1]);
-        }
-      }
       const last = match.chain[match.chain.length - 1];
       return {
         path: match.def.path,
-        params,
+        params: extractParams(path, match),
         query: Object.fromEntries(new URLSearchParams(window.location.search)),
         chain: match.chain,
         title: last?.title ?? ""
@@ -1033,6 +1279,7 @@ function router(opts) {
     if (resolved.title) document.title = resolved.title;
     if (!ctx.app) ctx.app = {};
     ctx.app.navigate = (path) => {
+      clearAsyncComponentCache();
       if (mode === "hash") {
         window.location.hash = "#" + path;
         const resolved2 = resolve(path);
@@ -1047,6 +1294,7 @@ function router(opts) {
       ctx.ui?.render();
     };
     const onPop = () => {
+      clearAsyncComponentCache();
       const resolved2 = resolve(getPath());
       ctx.route = resolved2;
       if (ctx.route?.title) document.title = ctx.route.title;
@@ -1595,6 +1843,7 @@ export {
   Portal,
   RouteView,
   api,
+  asyncComponent,
   auth,
   computeFixedPos,
   computeFixedPosRect,
@@ -1604,6 +1853,7 @@ export {
   extendCtx,
   h,
   i18n,
+  isAsyncComponent,
   jsx,
   jsxDEV,
   jsxs,

package/dist/client/reactive.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 创建响应式状态容器：深度 Proxy，任意层级属性赋值自动触发 dirty。
+ *
+ * 纯 JS（无 DOM），客户端（ctx.ui.$()）与服务端（SSR ctx shim）共用。
+ */
+export declare function createReactiveState(dirty: () => void): Record<string, any>;

package/dist/client/render.d.ts

@@ -14,6 +14,12 @@ import type { VNode } from './vnode.ts';
 import type { WfuiContext } from './types.ts';
 export declare const idRegistry: Map<string, VNode>;
 export declare function render(input: any, ctx: WfuiContext): Node | null;
+/**
+ * 清空 async 工厂缓存。
+ * 页面上下文切换时调用（路由导航/登录登出）——工厂内 ctx.data.get 的 key 依赖 ctx（如 route.params），
+ * 上下文变化后旧缓存定义的数据已失效，需要让工厂以新 ctx 重新执行。
+ */
+export declare function clearAsyncComponentCache(): void;
 /** 首次渲染 Portal：创建远程容器、渲染子节点（不返回占位节点） */
 export declare function renderPortal(vnode: VNode, ctx: WfuiContext): void;
 /** 更新 Portal：复用远程容器，patch 子节点（不操作父 DOM） */
@@ -22,3 +28,8 @@ export declare function patchValue(parent: Node, oldNode: Node | null, oldInput:
 /** 通知 ref 清理 + Portal 子容器清理 */
 export declare function callRefCleanup(input: any): void;
 export declare function mountVNode(container: Element, vnode: VNode, ctx: WfuiContext): void;
+/**
+ * Hydration 挂载入口：收养 container 内现有服务端 HTML。
+ * 渲染完收尾：删除服务端有、客户端没有的残留 DOM。
+ */
+export declare function hydrateVNode(container: Element, vnode: VNode, ctx: WfuiContext): Promise<void>;

package/dist/client/route-match.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 路由匹配纯函数 — 客户端 router 与服务端 uiSsr 共用（无 DOM 依赖）
+ *
+ * 支持路径参数 :id、通配符 *、嵌套路由（children → chain）。
+ * 与后端 Router（Trie）独立——本模块服务于"前端路由表驱动的页面"。
+ */
+import type { RouteDef } from './types.ts';
+export interface FlattenedRoute {
+    re: RegExp;
+    keys: string[];
+    def: RouteDef;
+    chain: RouteDef[];
+}
+export declare function joinPaths(a: string, b: string): string;
+export declare function compilePath(path: string): {
+    re: RegExp;
+    keys: string[];
+};
+export declare function flattenRoutes(routes: RouteDef[], basePath?: string, chain?: RouteDef[]): FlattenedRoute[];
+export declare function matchRoute(path: string, routes: FlattenedRoute[]): FlattenedRoute | null;
+/** 从匹配结果提取路径参数 */
+export declare function extractParams(path: string, match: FlattenedRoute): Record<string, string>;

package/dist/client/types.d.ts

@@ -70,6 +70,23 @@ export interface WfuiContext {
         delete: <T = any>(url: string, opts?: any) => Promise<T>;
         [key: string]: any;
     };
+    /** 数据管道（由 createApp 注入）：ctx.data.get(key, fetcher) */
+    data?: {
+        /**
+         * 获取数据：
+         *   - SSR：服务端真 fetch，结果序列化进 __DATA__
+         *   - hydration：从 __DATA__ 缓存同步命中（工厂 await 微任务即 resolve）
+         *   - SPA：未命中则触发 fetcher，同 key 并发请求合并
+         *
+         * key 约定即 URL（`/api/posts/1`），天然唯一。
+         */
+        get: <T = any>(key: string, fetcher?: () => Promise<T>) => Promise<T>;
+        /** 向缓存写入值（如 hydration 种子） */
+        set: (key: string, value: unknown) => void;
+        /** 是否存在缓存（未触发 fetch） */
+        has: (key: string) => boolean;
+        [key: string]: any;
+    };
     /** 认证状态 */
     auth?: {
         token: string | null;

package/dist/client/vnode.d.ts

@@ -7,7 +7,7 @@
  *   --jsxImportSource=weifuwu/client
  */
 import type { WfuiContext } from './types.ts';
-export type VNodeType = string | Component | typeof Fragment | typeof Portal;
+export type VNodeType = string | Component | AsyncComponent | typeof Fragment | typeof Portal;
 export interface VNode {
     type: VNodeType;
     props: Record<string, any>;
@@ -37,6 +37,35 @@ export interface VNode {
  * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
  */
 export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => ((props: P) => VNode | null) | null;
+/**
+ * 异步组件工厂（形态 C）：async (ctx) => (initProps, ctx) => (props) => VNode
+ *
+ * 工厂层（async，只执行一次并缓存）：
+ *   - 数据声明：const data = await ctx.data.get(key, fetcher)
+ *   - 代码分割：const { default: def } = await import('./view.tsx')
+ *   - 异步初始化：模块加载、共享资源
+ *
+ * 返回标准的 Component——mount/render 保持同步，异步只发生在工厂边界。
+ * 服务端遍历器与客户端渲染器都 await 工厂；更新路径（_render 缓存）不碰工厂。
+ *
+ * 必须用 asyncComponent() 包装以标记（渲染器据此区分调用约定）：
+ *   Component       → Comp(initProps, ctx)
+ *   AsyncComponent  → await Comp(ctx) → Component
+ */
+export type AsyncComponent<C extends object = {}, P = {}> = (ctx: WfuiContext & C) => Promise<Component<P, C>>;
+/**
+ * 包装异步组件工厂。
+ *
+ * ```tsx
+ * const UserProfile = asyncComponent(async (ctx) => {
+ *   const user = await ctx.data.get(`/api/user/${ctx.params.id}`)
+ *   return (initProps, ctx) => (props) => h('div', {}, user.name)
+ * })
+ * ```
+ */
+export declare function asyncComponent<C extends object = {}, P = {}>(factory: AsyncComponent<C, P>): AsyncComponent<C, P>;
+/** 判定一个组件类型是否为 async 工厂（asyncComponent 包装过） */
+export declare function isAsyncComponent(type: any): type is AsyncComponent;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;