@4399ywkf/core 5.1.4 → 5.1.6

package/dist/runtime/index.d.ts

@@ -1,10 +1,75 @@
-import { a as AppConfig, M as MicroAppConfig, b as AppContextValue, P as ProviderConfig } from '../types-BYqzyGAY.js';
-export { A as AntdConfig, L as LifecycleHooks, R as RequestConfig, c as Result } from '../types-BYqzyGAY.js';
+import { C as ChunkRecoveryConfig, c as ChunkRecoveryEvent, e as ChunkRecoverySource, a as AppConfig, M as MicroAppConfig, b as AppContextValue, P as ProviderConfig } from '../types-ZJhd87ue.js';
+export { A as AntdConfig, d as ChunkRecoveryOutcome, L as LifecycleHooks, R as RequestConfig, f as Result } from '../types-ZJhd87ue.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, Component, ErrorInfo, ComponentType } from 'react';
 import 'react-router';
 
+declare const DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS = 30000;
+declare const CHUNK_RECOVERY_STORAGE_KEY = "@4399ywkf/core:chunk-recovery-attempt";
+declare const CHUNK_RECOVERY_CACHE_BUST_PARAM = "__ywkf_chunk_retry";
+declare const CHUNK_RECOVERY_ACTIVE_SYMBOL: unique symbol;
+interface ChunkRecoveryStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+type ChunkRecoveryClaim = {
+    claimed: true;
+    attemptedAt: number;
+} | {
+    claimed: false;
+    reason: "already-attempted" | "cooldown" | "storage-unavailable";
+    attemptedAt?: number;
+};
+interface ClaimChunkRecoveryAttemptOptions {
+    cooldownMs?: number;
+    now: number;
+    recoveryId: string;
+    storageKey?: string;
+}
+interface ChunkRecoveryPolicyContext {
+    isProduction: boolean;
+    isMicroApp: boolean;
+}
+interface ChunkRecoveryPolicy {
+    enabled: boolean;
+    disabledReason?: "configuration" | "environment" | "micro-app";
+    cooldownMs: number;
+    globalHandlers: boolean;
+}
+interface HandleChunkRecoveryOptions {
+    source: ChunkRecoverySource;
+    config?: boolean | ChunkRecoveryConfig;
+    isMicroApp?: boolean;
+    onError?: (error: Error) => void;
+    onRecoveryEvent?: (event: ChunkRecoveryEvent) => void;
+}
+interface GlobalChunkRecoveryHandlersOptions {
+    config?: boolean | ChunkRecoveryConfig;
+    isMicroApp?: boolean;
+    onError?: (error: Error) => void;
+    onRecoveryEvent?: (event: ChunkRecoveryEvent) => void;
+}
+/** 仅匹配 Rspack/Webpack/Vite 的高置信度异步 chunk 加载错误。 */
+declare function isChunkLoadError(error: unknown): boolean;
+/** 将配置解析成与运行环境无关、可测试的恢复策略。 */
+declare function resolveChunkRecoveryPolicy(config: boolean | ChunkRecoveryConfig | undefined, context: ChunkRecoveryPolicyContext): ChunkRecoveryPolicy;
+/**
+ * 同步检查并预占本次刷新额度。
+ * 一次 setItem 同时提交 build 尝试集合与全局冷却时间；读写或数据校验失败时 fail closed。
+ */
+declare function claimChunkRecoveryAttempt(storage: ChunkRecoveryStorage, options: ClaimChunkRecoveryAttemptOptions): ChunkRecoveryClaim;
+/** 判断当前页面是否运行在已知微前端容器中。 */
+declare function isMicroAppRuntime(): boolean;
+/** 在新文档启动后移除内部 cache-bust 参数，不污染业务分享 URL。 */
+declare function clearChunkRecoveryCacheBustParam(): void;
+declare function handleChunkLoadError(reason: unknown, options: HandleChunkRecoveryOptions): ChunkRecoveryEvent | null;
+/**
+ * 可选的全局 chunk 错误监听。仅当 globalHandlers: true 且恢复策略启用时安装。
+ * 多个 core 实例共享一组 DOM listener；后注册的实例优先，卸载后自动回退到前一个实例。
+ */
+declare function installGlobalChunkRecoveryHandlers(options: GlobalChunkRecoveryHandlersOptions): () => void;
+
 /**
  * 启动应用
  */
@@ -99,6 +164,12 @@ interface ErrorBoundaryProps {
     fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
     /** 错误回调 */
     onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** 异步 chunk 加载失败恢复配置；公开组件默认不启用，由 RootProvider 显式传入 */
+    chunkRecovery?: boolean | ChunkRecoveryConfig;
+    /** chunk 加载恢复事件 */
+    onRecoveryEvent?: (event: ChunkRecoveryEvent) => void;
+    /** 是否运行在微前端子应用中 */
+    isMicroApp?: boolean;
 }
 interface ErrorBoundaryState {
     hasError: boolean;
@@ -114,16 +185,27 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryS
     reset: () => void;
     render(): ReactNode;
 }
+interface RouteErrorBoundaryProps {
+    /** 业务自定义的同步错误 UI；函数形式可接收标准化后的错误 */
+    fallback?: ReactNode | ((error: Error) => ReactNode);
+}
+/**
+ * React Router 专用的同步错误元素。
+ * Router 会在内部吞掉 lazy route 异常，因此约定式路由必须用该组件把 chunk 错误交回恢复器。
+ */
+declare function RouteErrorBoundary({ fallback }: RouteErrorBoundaryProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
 
 interface RootProviderProps {
     config: AppConfig;
     children?: ReactNode;
+    /** 是否运行在微前端子应用中；未传时由运行环境自动判断 */
+    isMicroApp?: boolean;
 }
 /**
  * 根 Provider 组件
  * 自动组合所有必要的 Provider
  */
-declare function RootProvider({ config, children }: RootProviderProps): react_jsx_runtime.JSX.Element;
+declare function RootProvider({ config, children, isMicroApp }: RootProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * 创建自定义 Provider 配置的辅助函数
  */
@@ -131,4 +213,4 @@ declare function createProvider<P extends Record<string, unknown>>(component: Co
     children: ReactNode;
 }>, props?: Omit<P, "children">, order?: number): ProviderConfig;
 
-export { AppConfig, AppContext, AppContextProvider, AppContextValue, ErrorBoundary, type ErrorBoundaryProps, MicroAppConfig, ProviderConfig, RootProvider, type RootProviderProps, bootstrap, createGarfishProvider, createMicroApp, createProvider, getMicroAppPublicPath, isMicroAppEnv, unmount, useApp, useAppName, useBasename, useEnv, useIsDev };
+export { AppConfig, AppContext, AppContextProvider, AppContextValue, CHUNK_RECOVERY_ACTIVE_SYMBOL, CHUNK_RECOVERY_CACHE_BUST_PARAM, CHUNK_RECOVERY_STORAGE_KEY, type ChunkRecoveryClaim, ChunkRecoveryConfig, ChunkRecoveryEvent, type ChunkRecoveryPolicy, type ChunkRecoveryPolicyContext, ChunkRecoverySource, type ChunkRecoveryStorage, type ClaimChunkRecoveryAttemptOptions, DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS, ErrorBoundary, type ErrorBoundaryProps, type GlobalChunkRecoveryHandlersOptions, type HandleChunkRecoveryOptions, MicroAppConfig, ProviderConfig, RootProvider, type RootProviderProps, RouteErrorBoundary, type RouteErrorBoundaryProps, bootstrap, claimChunkRecoveryAttempt, clearChunkRecoveryCacheBustParam, createGarfishProvider, createMicroApp, createProvider, getMicroAppPublicPath, handleChunkLoadError, installGlobalChunkRecoveryHandlers, isChunkLoadError, isMicroAppEnv, isMicroAppRuntime, resolveChunkRecoveryPolicy, unmount, useApp, useAppName, useBasename, useEnv, useIsDev };