@djvlc/runtime-host-react 1.1.1 → 1.1.3

package/dist/index.cjs

@@ -25,21 +25,36 @@ __export(index_exports, {
   RuntimeContext: () => RuntimeContext,
   RuntimeProvider: () => RuntimeProvider,
   useAction: () => useAction,
+  useAsync: () => useAsync,
+  useComponentState: () => useComponentState,
   useDJVRuntime: () => useDJVRuntime,
   useData: () => useData,
+  useDebouncedAction: () => useDebouncedAction,
   useHostApi: () => useHostApi,
+  useLifecycle: () => useLifecycle,
+  usePageInfo: () => usePageInfo,
+  usePrevious: () => usePrevious,
   useQuery: () => useQuery,
   useReactRuntime: () => useReactRuntime,
   useRuntimeContext: () => useRuntimeContext,
   useRuntimeEvent: () => useRuntimeEvent,
   useRuntimeState: () => useRuntimeState,
-  useRuntimeStateWritable: () => useRuntimeStateWritable
+  useRuntimeStateWritable: () => useRuntimeStateWritable,
+  useWhen: () => useWhen
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/react-runtime.ts
 var import_react = require("react");
 var import_runtime_core = require("@djvlc/runtime-core");
+var defaultMetrics = {
+  initTime: 0,
+  loadTime: 0,
+  renderTime: 0,
+  totalTime: 0,
+  initTimestamp: null,
+  readyTimestamp: null
+};
 function useReactRuntime(options) {
   const [runtime, setRuntime] = (0, import_react.useState)(null);
   const [loading, setLoading] = (0, import_react.useState)(true);
@@ -47,12 +62,29 @@ function useReactRuntime(options) {
   const [page, setPage] = (0, import_react.useState)(null);
   const [error, setError] = (0, import_react.useState)(null);
   const [hostApi, setHostApi] = (0, import_react.useState)(null);
+  const [metrics, setMetrics] = (0, import_react.useState)(defaultMetrics);
   const runtimeRef = (0, import_react.useRef)(null);
+  const timingRef = (0, import_react.useRef)({
+    startTime: 0,
+    initStartTime: 0,
+    loadStartTime: 0,
+    renderStartTime: 0
+  });
+  const isReady = (0, import_react.useMemo)(() => phase === "ready", [phase]);
+  const hasError = (0, import_react.useMemo)(() => phase === "error" || error !== null, [phase, error]);
   const init = (0, import_react.useCallback)(async () => {
     const container = options.containerRef?.current;
     if (!container) {
       throw new Error("Container element not found");
     }
+    timingRef.current.startTime = performance.now();
+    timingRef.current.initStartTime = timingRef.current.startTime;
+    if (options.enableMetrics) {
+      setMetrics((prev) => ({
+        ...prev,
+        initTimestamp: Date.now()
+      }));
+    }
     const runtimeInstance = (0, import_runtime_core.createRuntime)({
       ...options,
       container,
@@ -78,23 +110,46 @@ function useReactRuntime(options) {
     });
     await runtimeInstance.init();
     setHostApi(runtimeInstance.getHostApi());
+    if (options.enableMetrics) {
+      setMetrics((prev) => ({
+        ...prev,
+        initTime: performance.now() - timingRef.current.initStartTime
+      }));
+    }
   }, [options]);
   const load = (0, import_react.useCallback)(async () => {
     if (!runtimeRef.current) {
       throw new Error("Runtime not initialized");
     }
+    timingRef.current.loadStartTime = performance.now();
     const result = await runtimeRef.current.load();
     setPage(result);
     setHostApi(runtimeRef.current.getHostApi());
+    if (options.enableMetrics) {
+      setMetrics((prev) => ({
+        ...prev,
+        loadTime: performance.now() - timingRef.current.loadStartTime
+      }));
+    }
     return result;
-  }, []);
+  }, [options.enableMetrics]);
   const render = (0, import_react.useCallback)(async () => {
     if (!runtimeRef.current) {
       throw new Error("Runtime not initialized");
     }
+    timingRef.current.renderStartTime = performance.now();
     await runtimeRef.current.render();
     setLoading(false);
-  }, []);
+    if (options.enableMetrics) {
+      const now = performance.now();
+      setMetrics((prev) => ({
+        ...prev,
+        renderTime: now - timingRef.current.renderStartTime,
+        totalTime: now - timingRef.current.startTime,
+        readyTimestamp: Date.now()
+      }));
+    }
+  }, [options.enableMetrics]);
   const destroy = (0, import_react.useCallback)(() => {
     runtimeRef.current?.destroy();
     runtimeRef.current = null;
@@ -104,13 +159,43 @@ function useReactRuntime(options) {
     setError(null);
     setPhase("idle");
     setLoading(true);
+    setMetrics(defaultMetrics);
   }, []);
+  const reload = (0, import_react.useCallback)(async () => {
+    if (!runtimeRef.current) {
+      throw new Error("Runtime not initialized");
+    }
+    setError(null);
+    setLoading(true);
+    await load();
+    await render();
+  }, [load, render]);
   const setVariable = (0, import_react.useCallback)((key, value) => {
     runtimeRef.current?.setVariable(key, value);
   }, []);
+  const setVariables = (0, import_react.useCallback)((variables) => {
+    if (!runtimeRef.current) return;
+    Object.entries(variables).forEach(([key, value]) => {
+      runtimeRef.current?.setVariable(key, value);
+    });
+  }, []);
+  const getVariable = (0, import_react.useCallback)((key) => {
+    return runtimeRef.current?.getState().variables[key];
+  }, []);
   const refreshData = (0, import_react.useCallback)(async (queryId) => {
     await runtimeRef.current?.refreshData(queryId);
   }, []);
+  const executeAction = (0, import_react.useCallback)(async (actionType, params) => {
+    const api = hostApi;
+    if (!api) {
+      throw new Error("HostAPI not available");
+    }
+    const response = await api.executeAction(actionType, params || {});
+    if (response.success) {
+      return response.data;
+    }
+    throw new Error(response.errorMessage || "Action failed");
+  }, [hostApi]);
   return {
     runtime,
     loading,
@@ -118,12 +203,19 @@ function useReactRuntime(options) {
     page,
     error,
     hostApi,
+    isReady,
+    hasError,
+    metrics,
     init,
     load,
     render,
     destroy,
+    reload,
     setVariable,
-    refreshData
+    setVariables,
+    getVariable,
+    refreshData,
+    executeAction
   };
 }
 
@@ -179,13 +271,20 @@ function DJVRenderer({
   onLoad,
   onError,
   onReady,
+  onPhaseChange,
   loadingComponent,
   errorComponent,
+  emptyComponent,
   children,
   className,
-  style
+  style,
+  retryCount = 3,
+  retryDelay = 1e3,
+  timeout = 3e4
 }) {
   const containerRef = (0, import_react3.useRef)(null);
+  const mountedRef = (0, import_react3.useRef)(true);
+  const retryCountRef = (0, import_react3.useRef)(0);
   const [state, setState] = (0, import_react3.useState)({
     phase: "idle",
     page: null,
@@ -214,8 +313,8 @@ function DJVRenderer({
   const {
     runtime,
     loading,
-    phase: _phase,
-    page: _page,
+    phase,
+    page,
     error,
     hostApi,
     init,
@@ -223,27 +322,61 @@ function DJVRenderer({
     render,
     destroy
   } = useReactRuntime(options);
-  void _phase;
-  void _page;
-  const initAndLoad = (0, import_react3.useCallback)(async () => {
-    if (!containerRef.current) return;
+  (0, import_react3.useEffect)(() => {
+    onPhaseChange?.(phase);
+  }, [phase, onPhaseChange]);
+  const initWithRetry = (0, import_react3.useCallback)(async () => {
+    if (!containerRef.current || !mountedRef.current) return;
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("\u52A0\u8F7D\u8D85\u65F6")), timeout);
+    });
     try {
-      await init();
-      const pageData = await load();
-      onLoad?.(pageData);
-      await render();
-      onReady?.();
-      if (runtime) {
-        runtime.onStateChange((newState) => {
-          setState(newState);
-        });
-      }
+      await Promise.race([
+        (async () => {
+          await init();
+          const pageData = await load();
+          if (mountedRef.current) {
+            onLoad?.(pageData);
+          }
+          await render();
+          if (mountedRef.current) {
+            onReady?.();
+            retryCountRef.current = 0;
+            if (runtime) {
+              runtime.onStateChange((newState) => {
+                if (mountedRef.current) {
+                  setState(newState);
+                }
+              });
+            }
+          }
+        })(),
+        timeoutPromise
+      ]);
     } catch (err) {
+      if (!mountedRef.current) return;
+      if (retryCountRef.current < retryCount) {
+        retryCountRef.current++;
+        if (debug) {
+          console.log(`[DJVRenderer] \u91CD\u8BD5 ${retryCountRef.current}/${retryCount}...`);
+        }
+        setTimeout(() => {
+          if (mountedRef.current) {
+            initWithRetry();
+          }
+        }, retryDelay);
+      }
     }
-  }, [init, load, render, runtime, onLoad, onReady]);
+  }, [init, load, render, runtime, onLoad, onReady, timeout, retryCount, retryDelay, debug]);
+  const handleRetry = (0, import_react3.useCallback)(() => {
+    retryCountRef.current = 0;
+    initWithRetry();
+  }, [initWithRetry]);
   (0, import_react3.useEffect)(() => {
-    initAndLoad();
+    mountedRef.current = true;
+    initWithRetry();
     return () => {
+      mountedRef.current = false;
       destroy();
     };
   }, [pageUid]);
@@ -251,18 +384,43 @@ function DJVRenderer({
     if (!loading) return null;
     return loadingComponent || /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "djvlc-loading", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "djvlc-loading-spinner" }),
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: "\u52A0\u8F7D\u4E2D..." })
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: "\u52A0\u8F7D\u4E2D..." }),
+      retryCountRef.current > 0 && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { className: "djvlc-loading-retry", children: [
+        "\u91CD\u8BD5 ",
+        retryCountRef.current,
+        "/",
+        retryCount
+      ] })
     ] });
   };
   const renderError = () => {
     if (!error) return null;
     if (typeof errorComponent === "function") {
-      return errorComponent(error);
+      return errorComponent(error, handleRetry);
+    }
+    return errorComponent || /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "djvlc-error", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "djvlc-error-icon", children: "\u26A0\uFE0F" }),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { className: "djvlc-error-message", children: [
+        "\u52A0\u8F7D\u5931\u8D25\uFF1A",
+        error.message
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "button",
+        {
+          className: "djvlc-error-retry-btn",
+          onClick: handleRetry,
+          type: "button",
+          children: "\u91CD\u8BD5"
+        }
+      )
+    ] });
+  };
+  const renderEmpty = () => {
+    if (loading || error || page) return null;
+    if (phase === "ready" && !page) {
+      return emptyComponent || /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "djvlc-empty", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: "\u6682\u65E0\u5185\u5BB9" }) });
     }
-    return errorComponent || /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "djvlc-error", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { children: [
-      "\u52A0\u8F7D\u5931\u8D25\uFF1A",
-      error.message
-    ] }) });
+    return null;
   };
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(RuntimeProvider, { runtime, state, hostApi, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     "div",
@@ -270,9 +428,12 @@ function DJVRenderer({
       ref: containerRef,
       className: `djvlc-renderer ${className || ""}`,
       style,
+      "data-phase": phase,
+      "data-page-uid": pageUid,
       children: [
         renderLoading(),
         renderError(),
+        renderEmpty(),
         children
       ]
     }
@@ -282,32 +443,63 @@ function DJVRenderer({
 // src/components/DJVProvider.tsx
 var import_react4 = require("react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
+var defaultState2 = {
+  phase: "idle",
+  page: null,
+  variables: {},
+  queries: {},
+  components: /* @__PURE__ */ new Map(),
+  error: null,
+  destroyed: false
+};
 function DJVProvider({
   runtime,
   hostApi,
-  children
+  children,
+  className,
+  debug = false,
+  onStateChange,
+  onPhaseChange,
+  onError
 }) {
   const [state, setState] = (0, import_react4.useState)(
-    runtime?.getState() || {
-      phase: "idle",
-      page: null,
-      variables: {},
-      queries: {},
-      components: /* @__PURE__ */ new Map(),
-      error: null,
-      destroyed: false
-    }
+    runtime?.getState() || defaultState2
   );
+  const prevPhaseRef = (0, import_react4.useRef)(state.phase);
   (0, import_react4.useEffect)(() => {
-    if (!runtime) return;
+    if (!runtime) {
+      setState(defaultState2);
+      return;
+    }
+    setState(runtime.getState());
     const unsubscribe = runtime.onStateChange((newState) => {
       setState(newState);
+      onStateChange?.(newState);
+      if (newState.phase !== prevPhaseRef.current) {
+        onPhaseChange?.(newState.phase);
+        if (debug) {
+          console.log(`[DJVProvider] Phase changed: ${prevPhaseRef.current} -> ${newState.phase}`);
+        }
+        prevPhaseRef.current = newState.phase;
+      }
+      if (newState.error) {
+        onError?.(newState.error);
+      }
     });
     return () => {
       unsubscribe();
     };
-  }, [runtime]);
-  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RuntimeProvider, { runtime, state, hostApi, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "djvlc-provider", children }) });
+  }, [runtime, onStateChange, onPhaseChange, onError, debug]);
+  (0, import_react4.useEffect)(() => {
+  }, [hostApi]);
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RuntimeProvider, { runtime, state, hostApi, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    "div",
+    {
+      className: ["djvlc-provider", className].filter(Boolean).join(" "),
+      "data-phase": state.phase,
+      children
+    }
+  ) });
 }
 
 // src/hooks/useDJVRuntime.ts
@@ -318,13 +510,25 @@ function useDJVRuntime() {
     const phase = context.state.phase;
     return phase !== "ready" && phase !== "error";
   }, [context.state.phase]);
+  const isReady = context.state.phase === "ready";
+  const hasError = context.state.phase === "error" || context.state.error !== null;
+  const reload = (0, import_react5.useCallback)(async () => {
+    if (!context.runtime) {
+      throw new Error("Runtime not available");
+    }
+    await context.runtime.load();
+    await context.runtime.render();
+  }, [context.runtime]);
   return {
     runtime: context.runtime,
     state: context.state,
     loading,
     phase: context.state.phase,
     error: context.state.error,
-    page: context.state.page
+    page: context.state.page,
+    isReady,
+    hasError,
+    reload
   };
 }
 function useHostApi() {
@@ -349,67 +553,143 @@ function useRuntimeStateWritable(key, defaultValue) {
   );
   return [value, setValue];
 }
-function useQuery(queryId) {
+function useQuery(queryId, options) {
   const context = useRuntimeContext();
   const [loading, setLoading] = (0, import_react5.useState)(false);
   const [error, setError] = (0, import_react5.useState)(null);
+  const [lastUpdated, setLastUpdated] = (0, import_react5.useState)(null);
+  const mountedRef = (0, import_react5.useRef)(true);
   const data = context.state.queries[queryId];
   const refetch = (0, import_react5.useCallback)(async () => {
+    if (!mountedRef.current) return;
     setLoading(true);
     setError(null);
     try {
       await context.runtime?.refreshData(queryId);
+      if (mountedRef.current) {
+        setLastUpdated(Date.now());
+      }
     } catch (e) {
-      setError(e);
+      if (mountedRef.current) {
+        setError(e);
+      }
     } finally {
-      setLoading(false);
+      if (mountedRef.current) {
+        setLoading(false);
+      }
     }
   }, [context.runtime, queryId]);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    if (options?.refreshOnMount && context.runtime) {
+      refetch();
+    }
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  (0, import_react5.useEffect)(() => {
+    if (!options?.refreshInterval || options.refreshInterval <= 0) return;
+    const timer = setInterval(() => {
+      refetch();
+    }, options.refreshInterval);
+    return () => clearInterval(timer);
+  }, [options?.refreshInterval, refetch]);
+  (0, import_react5.useEffect)(() => {
+    if (!options?.refreshOnFocus) return;
+    const handleFocus = () => {
+      refetch();
+    };
+    window.addEventListener("focus", handleFocus);
+    return () => window.removeEventListener("focus", handleFocus);
+  }, [options?.refreshOnFocus, refetch]);
   return {
     data,
     loading,
     error,
-    refetch
+    refetch,
+    lastUpdated
   };
 }
-function useAction(actionType) {
+function useAction(actionType, options) {
   const context = useRuntimeContext();
   const [loading, setLoading] = (0, import_react5.useState)(false);
   const [result, setResult] = (0, import_react5.useState)();
   const [error, setError] = (0, import_react5.useState)(null);
-  const execute = (0, import_react5.useCallback)(
-    async (params) => {
+  const [executionCount, setExecutionCount] = (0, import_react5.useState)(0);
+  const mountedRef = (0, import_react5.useRef)(true);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const reset = (0, import_react5.useCallback)(() => {
+    setResult(void 0);
+    setError(null);
+    setExecutionCount(0);
+  }, []);
+  const executeWithRetry = (0, import_react5.useCallback)(
+    async (params, retriesLeft) => {
       const hostApi = context.hostApi;
       if (!hostApi) {
         throw new Error("HostAPI not available");
       }
-      setLoading(true);
-      setError(null);
       try {
         const response = await hostApi.executeAction(
           actionType,
           params
         );
         if (response.success) {
-          setResult(response.data);
           return response.data;
         } else {
-          throw new Error(response.message || "Action failed");
+          throw new Error(response.errorMessage || "Action failed");
         }
       } catch (e) {
-        setError(e);
+        if (retriesLeft > 0) {
+          await new Promise((resolve) => setTimeout(resolve, options?.retryDelay || 1e3));
+          return executeWithRetry(params, retriesLeft - 1);
+        }
+        throw e;
+      }
+    },
+    [context.hostApi, actionType, options?.retryDelay]
+  );
+  const execute = (0, import_react5.useCallback)(
+    async (params) => {
+      if (!mountedRef.current) return void 0;
+      setLoading(true);
+      setError(null);
+      setExecutionCount((c) => c + 1);
+      try {
+        const data = await executeWithRetry(params, options?.retryCount || 0);
+        if (mountedRef.current) {
+          setResult(data);
+          options?.onSuccess?.(data);
+        }
+        return data;
+      } catch (e) {
+        const err = e;
+        if (mountedRef.current) {
+          setError(err);
+          options?.onError?.(err);
+        }
         throw e;
       } finally {
-        setLoading(false);
+        if (mountedRef.current) {
+          setLoading(false);
+        }
       }
     },
-    [context.hostApi, actionType]
+    [executeWithRetry, options]
   );
   return {
     execute,
     loading,
     result,
-    error
+    error,
+    reset,
+    executionCount
   };
 }
 function useData(queryId, params, options) {
@@ -417,42 +697,69 @@ function useData(queryId, params, options) {
   const [data, setData] = (0, import_react5.useState)();
   const [loading, setLoading] = (0, import_react5.useState)(false);
   const [error, setError] = (0, import_react5.useState)(null);
+  const [isFetched, setIsFetched] = (0, import_react5.useState)(false);
+  const mountedRef = (0, import_react5.useRef)(true);
+  const paramsRef = (0, import_react5.useRef)(params);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
   const refetch = (0, import_react5.useCallback)(
     async (newParams) => {
       const hostApi = context.hostApi;
-      if (!hostApi) {
-        throw new Error("HostAPI not available");
-      }
+      if (!hostApi || !mountedRef.current) return;
       setLoading(true);
       setError(null);
       try {
-        const response = await hostApi.requestData(
+        const data2 = await hostApi.requestData(
           queryId,
-          newParams || params
+          newParams || paramsRef.current
         );
-        if (response.success) {
-          setData(response.data);
-        } else {
-          throw new Error(response.message || "Query failed");
-        }
+        if (!mountedRef.current) return;
+        setData(data2);
+        setIsFetched(true);
+        options?.onSuccess?.(data2);
       } catch (e) {
-        setError(e);
+        if (mountedRef.current) {
+          const err = e;
+          setError(err);
+          options?.onError?.(err);
+        }
       } finally {
-        setLoading(false);
+        if (mountedRef.current) {
+          setLoading(false);
+        }
       }
     },
-    [context.hostApi, queryId, params]
+    [context.hostApi, queryId, options]
   );
+  (0, import_react5.useEffect)(() => {
+    const prevParams = paramsRef.current;
+    paramsRef.current = params;
+    if (options?.refreshOnParamsChange !== false && context.hostApi && isFetched && JSON.stringify(prevParams) !== JSON.stringify(params)) {
+      refetch();
+    }
+  }, [params, context.hostApi, options?.refreshOnParamsChange, isFetched, refetch]);
   (0, import_react5.useEffect)(() => {
     if (options?.immediate !== false && context.hostApi) {
       refetch();
     }
   }, [context.hostApi]);
+  (0, import_react5.useEffect)(() => {
+    if (!options?.refreshInterval || options.refreshInterval <= 0) return;
+    const timer = setInterval(() => {
+      refetch();
+    }, options.refreshInterval);
+    return () => clearInterval(timer);
+  }, [options?.refreshInterval, refetch]);
   return {
     data,
     loading,
     error,
-    refetch
+    refetch,
+    isFetched
   };
 }
 function useRuntimeEvent(eventType, handler) {
@@ -466,6 +773,189 @@ function useRuntimeEvent(eventType, handler) {
     };
   }, [context.runtime, eventType, handler]);
 }
+function usePageInfo() {
+  const context = useRuntimeContext();
+  const page = context.state.page;
+  return (0, import_react5.useMemo)(() => ({
+    /** 页面 UID */
+    pageUid: page?.pageUid,
+    /** 页面版本 ID */
+    pageVersionId: page?.pageVersionId,
+    /** Schema 版本 */
+    schemaVersion: page?.pageJson?.schemaVersion,
+    /** 页面标题 */
+    title: page?.title,
+    /** 页面配置 */
+    config: page?.config,
+    /** 页面是否已加载 */
+    isLoaded: page !== null
+  }), [page]);
+}
+function useComponentState(componentId) {
+  const context = useRuntimeContext();
+  const componentStatus = context.state.components.get(componentId);
+  return (0, import_react5.useMemo)(() => ({
+    /** 组件是否已加载 */
+    isLoaded: componentStatus?.status === "loaded",
+    /** 组件是否加载中 */
+    isLoading: componentStatus?.status === "loading",
+    /** 组件是否加载失败 */
+    hasError: componentStatus?.status === "failed",
+    /** 加载耗时 */
+    loadTime: componentStatus?.loadTime,
+    /** 组件信息 */
+    info: componentStatus
+  }), [componentStatus]);
+}
+function useLifecycle(options) {
+  const context = useRuntimeContext();
+  const [hasMounted, setHasMounted] = (0, import_react5.useState)(false);
+  const [hasReady, setHasReady] = (0, import_react5.useState)(false);
+  const prevPhaseRef = (0, import_react5.useRef)(context.state.phase);
+  const mountedRef = (0, import_react5.useRef)(true);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  (0, import_react5.useEffect)(() => {
+    const currentPhase = context.state.phase;
+    if (currentPhase !== prevPhaseRef.current) {
+      options?.onPhaseChange?.(currentPhase);
+      prevPhaseRef.current = currentPhase;
+    }
+    if (!hasMounted && currentPhase !== "idle") {
+      setHasMounted(true);
+      Promise.resolve(options?.onMounted?.()).catch((error) => {
+        options?.onError?.(error);
+      });
+    }
+    if (!hasReady && currentPhase === "ready") {
+      setHasReady(true);
+      Promise.resolve(options?.onReady?.()).catch((error) => {
+        options?.onError?.(error);
+      });
+    }
+    if (currentPhase === "error" && context.state.error) {
+      options?.onError?.(context.state.error);
+    }
+  }, [context.state.phase, context.state.error, hasMounted, hasReady, options]);
+  return {
+    /** 当前阶段 */
+    phase: context.state.phase,
+    /** 是否已 mounted */
+    hasMounted,
+    /** 是否已 ready */
+    hasReady
+  };
+}
+function useWhen(condition, callback, options) {
+  const [executed, setExecuted] = (0, import_react5.useState)(false);
+  const { once = true } = options || {};
+  (0, import_react5.useEffect)(() => {
+    if (condition && (!once || !executed)) {
+      setExecuted(true);
+      callback();
+    }
+  }, [condition, callback, once, executed]);
+  return {
+    /** 是否已执行 */
+    executed
+  };
+}
+function useDebouncedAction(actionType, delay = 300) {
+  const { execute: rawExecute, loading, result, error } = useAction(actionType);
+  const timeoutRef = (0, import_react5.useRef)(null);
+  const mountedRef = (0, import_react5.useRef)(true);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+  const execute = (0, import_react5.useCallback)((params) => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    timeoutRef.current = setTimeout(() => {
+      if (mountedRef.current) {
+        rawExecute(params).catch(() => {
+        });
+      }
+    }, delay);
+  }, [rawExecute, delay]);
+  const cancel = (0, import_react5.useCallback)(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+  return {
+    execute,
+    loading,
+    result,
+    error,
+    cancel
+  };
+}
+function useAsync(asyncFn, deps = [], options) {
+  const [data, setData] = (0, import_react5.useState)();
+  const [loading, setLoading] = (0, import_react5.useState)(false);
+  const [error, setError] = (0, import_react5.useState)(null);
+  const mountedRef = (0, import_react5.useRef)(true);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const execute = (0, import_react5.useCallback)(async () => {
+    if (!mountedRef.current) return void 0;
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await asyncFn();
+      if (mountedRef.current) {
+        setData(result);
+        options?.onSuccess?.(result);
+      }
+      return result;
+    } catch (e) {
+      const err = e;
+      if (mountedRef.current) {
+        setError(err);
+        options?.onError?.(err);
+      }
+      return void 0;
+    } finally {
+      if (mountedRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [asyncFn, ...deps]);
+  (0, import_react5.useEffect)(() => {
+    if (options?.immediate !== false) {
+      execute();
+    }
+  }, []);
+  return {
+    data,
+    loading,
+    error,
+    execute
+  };
+}
+function usePrevious(value) {
+  const ref = (0, import_react5.useRef)();
+  (0, import_react5.useEffect)(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DJVProvider,
@@ -473,13 +963,20 @@ function useRuntimeEvent(eventType, handler) {
   RuntimeContext,
   RuntimeProvider,
   useAction,
+  useAsync,
+  useComponentState,
   useDJVRuntime,
   useData,
+  useDebouncedAction,
   useHostApi,
+  useLifecycle,
+  usePageInfo,
+  usePrevious,
   useQuery,
   useReactRuntime,
   useRuntimeContext,
   useRuntimeEvent,
   useRuntimeState,
-  useRuntimeStateWritable
+  useRuntimeStateWritable,
+  useWhen
 });