@blueking/bk-weweb 0.0.35 → 0.0.36-beta.16

package/dist/index.d.mts

@@ -1,27 +1,34 @@
+type ExecuteResult = Comment | HTMLScriptElement | undefined;
+/** Script脚本实例类 */
 declare class Script {
     async: boolean;
     code: string;
     defer: boolean;
-    exportInstance?: any;
+    exportInstance?: unknown;
     fromHtml: boolean;
+    blobUrl?: string;
     initial: boolean;
     isModule: boolean;
     scoped: boolean;
     url: string | undefined;
     constructor({ async, code, defer, fromHtml, initial, isModule, url }: IScriptOption);
-    /**
-     * @param app 应用
-     * @param needReplaceScriptElement 是否需要替换script标签
-     * @returns 返回执行后的script标签或注释
-     */
-    executeCode(app: BaseModel, needReplaceScriptElement?: boolean): Promise<Comment | HTMLScriptElement | undefined>;
+    /** 执行脚本代码 */
+    executeCode(app: BaseModel, needReplaceScriptElement?: boolean): Promise<ExecuteResult>;
+    /** 内存脚本执行 */
     executeMemoryScript(app: BaseModel, scopedCode: string): void;
+    /** 脚本标签执行 */
     executeSourceScript(scriptElement: HTMLScriptElement, scopedCode: string): void;
+    /** 获取脚本内容 */
     getCode(app?: BaseModel): Promise<string>;
     setCode(code: string): void;
+    /** 转换脚本内容 */
     transformCode(app: BaseModel): string;
 }
 
+type PackRuleType = CSSMediaRule | CSSSupportsRule;
+/**
+ * 样式处理类
+ */
 declare class Style {
     code: string;
     fromHtml: boolean;
@@ -33,90 +40,321 @@ declare class Style {
     url: string | undefined;
     constructor({ code, fromHtml, initial, prefetch, preload, url }: IStyleOption);
     /**
-     * @param styleElement 样式node
+     * 通用样式作用域处理
+     * @param styleElement 样式元素
      * @param app 应用实例
      */
     commonScoped(styleElement: HTMLStyleElement, app: BaseModel): void;
+    /**
+     * 创建样式元素
+     */
     createStyleElement(): HTMLStyleElement;
     /**
+     * 执行样式代码
      * @param app 应用实例
      * @returns 返回执行后的style标签
      */
     executeCode(app: BaseModel): Promise<HTMLStyleElement>;
+    /**
+     * 获取样式代码
+     */
     getCode(app?: BaseModel): Promise<string>;
+    /**
+     * 检查并链接基础应用样式
+     * @param styleElement 样式元素
+     * @param app 应用实例
+     * @returns 是否已链接基础样式
+     */
     linkedBaseStyle(styleElement: HTMLStyleElement, app: BaseModel): boolean;
-    resetPackRule(rule: CSSMediaRule | CSSSupportsRule, prefix: string, packName: string): string;
+    /**
+     * 重置包装规则
+     */
+    resetPackRule(rule: PackRuleType, prefix: string, packName: string): string;
+    /**
+     * 重置URL地址
+     */
     resetUrlHost(cssText: string, uri: string, linkPath?: string): string;
+    /**
+     * css rule 处理
+     */
     scopeRule(rules: CSSRule[], cssPrefix: string): string;
+    /**
+     * style rule 处理
+     */
     scopeStyleRule(rule: CSSStyleRule, prefix: string): string;
+    /**
+     * link style 处理
+     */
     scopedLinkCSS(app: BaseModel, linkElement: HTMLLinkElement): HTMLStyleElement;
+    /**
+     * 隔离 style
+     */
     scopedStyleCSS(app: BaseModel, styleElement: HTMLStyleElement): HTMLStyleElement;
+    /**
+     * 应用隔离 style
+     */
+    private applyScopedCSS;
+    private applyUnscopedCSS;
+    /**
+     * 处理ShadowRoot中的字体
+     */
+    private handleShadowRootFonts;
+    private getCodeFromAppSource;
+    private getCodeFromCache;
+    private fetchCodeFromRemote;
+    private clearStyleElement;
+    private buildBaseURI;
+    private handleExistingCode;
+    /**
+     * 处理href属性
+     */
+    private handleHrefAttribute;
+    /**
+     * 处理缺失的href
+     */
+    private handleMissingHref;
+    private processExistingContent;
+    private observeContentChanges;
 }
 
+/**
+ * 应用缓存管理器
+ * @description 负责管理所有微应用实例的缓存、资源共享和状态跟踪
+ */
 declare class AppCache {
-    private baseSource;
-    private cache;
+    /** 基础资源源，用于主应用共享资源包 */
+    private readonly baseSource;
+    /** 应用实例缓存映射表 */
+    private readonly cache;
+    /**
+     * 构造函数
+     * @description 初始化应用缓存管理器
+     */
     constructor();
-    deleteApp(url: string): void;
+    /**
+     * 设置应用实例到缓存
+     * @description 将应用实例添加到缓存中，使用应用的缓存键作为标识
+     * @param app - 要缓存的应用实例
+     */
+    setApp(app: BaseModel): void;
+    /**
+     * 获取缓存的应用实例
+     * @description 根据名称或ID获取已缓存的应用实例
+     * @param name - 应用名称或ID，为空时返回 undefined
+     * @returns BaseModel | undefined - 应用实例或 undefined
+     */
     getApp(name?: null | string): BaseModel | undefined;
-    getBaseAppStyle(urlOrCode: string): Style | undefined;
+    /**
+     * 删除缓存的应用实例
+     * @description 从缓存中移除指定URL的应用实例
+     * @param url - 要删除的应用URL标识
+     */
+    deleteApp(url: string): void;
+    /**
+     * 获取缓存的HTML内容
+     * @description 根据URL获取已缓存的HTML内容
+     * @param url - 应用的URL
+     * @returns string - HTML内容，未找到时返回空字符串
+     */
     getCacheHtml(url: string): string;
-    getCacheScript(url: string): Script | undefined;
-    getCacheStyle(url: string): Style | undefined;
-    setApp(app: BaseModel): void;
+    /**
+     * 设置基础应用脚本
+     * @description 将脚本添加到基础资源源中，供多个应用共享
+     * @param url - 脚本的URL
+     * @param script - 脚本实例
+     */
     setBaseAppScript(url: string, script: Script): void;
+    /**
+     * 获取缓存的脚本资源
+     * @description 从基础资源源或应用缓存中获取脚本资源
+     * @param url - 脚本的URL
+     * @returns Script | undefined - 脚本实例或 undefined
+     */
+    getCacheScript(url: string): Script | undefined;
+    /**
+     * 设置基础应用样式
+     * @description 将样式添加到基础资源源中，供多个应用共享
+     * @param url - 样式的URL
+     * @param style - 样式实例
+     */
     setBaseAppStyle(url: string, style: Style): void;
+    /**
+     * 获取基础应用样式
+     * @description 从基础资源源中获取样式资源
+     * @param urlOrCode - 样式的URL或代码
+     * @returns Style | undefined - 样式实例或 undefined
+     */
+    getBaseAppStyle(urlOrCode: string): Style | undefined;
+    /**
+     * 获取缓存的样式资源
+     * @description 从基础资源源或应用缓存中获取样式资源
+     * @param url - 样式的URL
+     * @returns Style | undefined - 样式实例或 undefined
+     */
+    getCacheStyle(url: string): Style | undefined;
+    /**
+     * 检查是否存在活跃的应用
+     * @description 判断当前是否有处于非卸载状态的应用实例
+     * @returns boolean - 存在活跃应用时返回 true
+     */
     get hasActiveApp(): boolean;
 }
 
-declare enum AppState {
-    ACTIVATED = "ACTIVATED",// 激活
-    DEACTIVATED = "DEACTIVATED",// 未激活
-    ERROR = "ERROR",// Error
-    LOADED = "LOADED",// 加载完成
-    LOADING = "LOADING",// 加载中
-    MOUNTED = "MOUNTED",// 挂载完成
-    MOUNTING = "MOUNTING",// 挂载中
-    UNMOUNT = "UNMOUNT",// 卸载
-    UNSET = "UNSET"
-}
+/**
+ * 应用状态常量
+ * 定义微前端应用的生命周期状态
+ */
+declare const AppState: {
+    /** 未设置状态 */
+    readonly UNSET: "UNSET";
+    /** 加载中 */
+    readonly LOADING: "LOADING";
+    /** 加载完成 */
+    readonly LOADED: "LOADED";
+    /** 挂载中 */
+    readonly MOUNTING: "MOUNTING";
+    /** 挂载完成 */
+    readonly MOUNTED: "MOUNTED";
+    /** 激活状态 */
+    readonly ACTIVATED: "ACTIVATED";
+    /** 未激活状态 */
+    readonly DEACTIVATED: "DEACTIVATED";
+    /** 卸载状态 */
+    readonly UNMOUNT: "UNMOUNT";
+    /** 错误状态 */
+    readonly ERROR: "ERROR";
+};
+type KeyOfAppState = keyof typeof AppState;
+type ValueOfAppState = (typeof AppState)[KeyOfAppState];
 
+/**
+ * BK WEWEB 支持的自定义属性枚举
+ * @description 定义了 bk-weweb 自定义元素支持的所有属性配置
+ */
 declare enum WewebCustomAttrs {
-    data = "data",// 传递给子应用的数据
-    id = "id",// 应用id
-    keepAlive = "keepAlive",// 是否缓存
-    mode = "mode",// 模式
-    scopeCss = "scopeCss",// 是否开启css隔离
-    scopeJs = "scopeJs",// 是否开启js隔离
-    scopeLocation = "scopeLocation",// 是否开启location隔离
-    setShodowDom = "setShodowDom",// 是否开启shadowDom
-    showSourceCode = "showSourceCode",// 是否显示源码
+    /** 传递给子应用的数据 */
+    data = "data",
+    /** 应用唯一标识符 */
+    id = "id",
+    /** 是否启用缓存模式 */
+    keepAlive = "keepAlive",
+    /** 应用运行模式 */
+    mode = "mode",
+    /** 是否开启 CSS 样式隔离 */
+    scopeCss = "scopeCss",
+    /** 是否开启 JavaScript 隔离 */
+    scopeJs = "scopeJs",
+    /** 是否开启 location 路由隔离 */
+    scopeLocation = "scopeLocation",
+    /** 是否启用 Shadow DOM */
+    setShadowDom = "setShadowDom",
+    /** @deprecated 请使用 setShadowDom 代替 */
+    setShodowDom = "setShodowDom",
+    /** 是否显示源码 */
+    showSourceCode = "showSourceCode",
+    /** 应用资源 URL */
     url = "url"
 }
 
+type FakeWindow = Window & Record<string, unknown>;
+
+/**
+ * 微前端沙箱
+ * @description 提供应用间的环境隔离，防止全局变量污染，支持多应用并存运行
+ */
 declare class SandBox {
-    app: BaseModel;
+    readonly app: BaseModel;
+    /** 沙箱激活状态标识 */
     private active;
-    private inRawWindowKeySet;
+    /** 记录在原始 window 上新增的属性键集合 */
+    private readonly inRawWindowKeySet;
+    /** 重置文档和 body 事件的函数 */
     private resetDocumentAndBodyEvent?;
-    private resetWindowFunction;
-    private sameRawWindowKeySet;
-    fakeWindow: Window & IInjectWindowAttrs;
+    /** 重置 window 函数的方法 */
+    private readonly resetWindowFunction;
+    /** 记录与原始 window 相同的属性键集合 */
+    private readonly sameRawWindowKeySet;
+    /** 伪造的 window 对象 */
+    readonly fakeWindow: FakeWindow & IInjectWindowAttrs;
+    /** 代理的 document 对象 */
     proxyDocument: any;
-    proxyWindow: WindowProxy & IInjectWindowAttrs;
+    /** 代理的 window 对象 */
+    readonly proxyWindow: WindowProxy & IInjectWindowAttrs;
+    /** 原始 document 对象 */
     rawDocument: Record<string, any>;
-    rawWindow: Window;
-    windowSymbolKey: keyof Window;
+    /** 原始 window 对象 */
+    readonly rawWindow: Window;
+    /** 在 window 上的唯一标识键 */
+    readonly windowSymbolKey: keyof Window;
+    /** 初始化沙箱环境 */
     constructor(app: BaseModel);
+    /** 处理代理对象的 get 操作 */
+    private handleProxyGet;
+    /**
+     * 处理代理对象的 set 操作
+     * @description 统一处理代理对象属性设置的复杂逻辑
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @returns boolean - 设置是否成功
+     * @private
+     */
+    private handleProxySet;
+    /**
+     * 判断是否应该使用 iframe 的 location
+     * @description 检查是否在 iframe 模式下访问 location 相关属性
+     * @param key - 属性键
+     * @returns boolean - 是否使用 iframe location
+     * @private
+     */
+    private shouldUseIframeLocation;
+    /**
+     * 创建 getComputedStyle 方法的代理
+     * @description 为 getComputedStyle 方法创建安全的代理实现
+     * @param rawWindow - 原始 window 对象
+     * @returns Function - 代理后的 getComputedStyle 方法
+     * @private
+     */
+    private createGetComputedStyleProxy;
+    /**
+     * 判断是否应该在目标对象上设置属性
+     * @description 检查属性设置的逻辑条件
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param rawWindow - 原始 window 对象
+     * @returns boolean - 是否在目标对象上设置
+     * @private
+     */
+    private shouldSetOnTarget;
+    /**
+     * 在目标对象上设置属性
+     * @description 安全地在目标对象上设置属性，保持描述符特性
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @private
+     */
+    private setPropertyOnTarget;
     /**
-     *
-     * @param data data for sandbox
-     * @description active hook for sandbox
+     * 处理白名单属性
+     * @description 处理需要在原始 window 上设置的白名单属性
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @private
+     */
+    private handleWhiteListProperty;
+    /**
+     * 激活沙箱
+     * @description 启动沙箱环境，初始化代理对象和事件处理
+     * @param data - 传递给沙箱的数据（可选）
      */
     activated(data?: Record<string, unknown>): void;
     /**
-     *
-     * @description decativated hook for sandbox
+     * 停用沙箱
+     * @description 关闭沙箱环境，清理所有副作用和修改
      */
     deactivated(): void;
 }
@@ -124,9 +362,10 @@ declare class SandBox {
 type SourceFuncType = () => Promise<string[]>;
 type SourceType = SourceFuncType | string[];
 
+/** BK-WEWEB 微应用模式类 */
 declare class MicroAppModel implements BaseModel {
     private state;
-    container?: HTMLElement | ShadowRoot;
+    container?: ContainerType;
     data: Record<string, unknown>;
     iframe: HTMLIFrameElement | null;
     initSource: SourceType;
@@ -142,22 +381,57 @@ declare class MicroAppModel implements BaseModel {
     showSourceCode: boolean;
     source?: EntrySource;
     url: string;
-    constructor(props: IAppModleProps);
-    activated(container: HTMLElement | ShadowRoot, callback?: (app: BaseModel) => void): void;
+    constructor(props: IAppModelProps);
+    /** 激活微应用 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 创建隔离iframe */
     createIframe(): Promise<HTMLIFrameElement>;
+    /** 停用微应用 */
     deactivated(): void;
+    /** 初始化ShadowRoot容器 */
     initShadowRootContainer(): void;
-    mount(container?: HTMLElement | ShadowRoot, callback?: (app: BaseModel) => void): void;
+    /** 挂载微应用 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
     onError(): void;
+    /** 挂载处理 */
     onMount(): void;
+    /** 注册运行中的微应用 */
     registerRunningApp(): void;
+    /** 启动微应用 */
     start(): Promise<void>;
+    /** 卸载微应用 */
     unmount(needDestroy?: boolean): void;
     get appCacheKey(): string;
-    get status(): AppState;
-    set status(v: AppState);
+    get status(): ValueOfAppState;
+    set status(value: ValueOfAppState);
+    /** 初始化沙盒 */
+    private initializeSandBox;
+    /** 设置容器属性 */
+    private setContainerAttribute;
+    /** 转移节点到新容器 */
+    private transferNodes;
+    /** 设置节点属性 */
+    private setupNodeProperties;
+    /** 创建iframe元素 */
+    private createIframeElement;
+    /** 构建iframe源地址 */
+    private buildIframeSrc;
+    /** 检查是否为Chrome浏览器 */
+    private isChromeUserAgent;
+    /** 处理非Chrome浏览器iframe */
+    private handleNonChromeIframe;
+    /** 渲染应用内容 */
+    private renderAppContent;
+    /** 检查是否需要重新加载 */
+    private needsReload;
 }
 
+interface CollectResult {
+    replace: Comment | Element;
+    style?: Style;
+    script?: Script;
+}
 declare class EntrySource {
     url: string;
     html: HTMLElement | null;
@@ -165,82 +439,210 @@ declare class EntrySource {
     scripts: Map<string, Script>;
     styles: Map<string, Style>;
     constructor(url: string);
-    collectLink(link: HTMLLinkElement, parent: Node, needReplaceELement?: boolean): {
+    /** 收集链接元素 */
+    collectLink: (link: HTMLLinkElement, parent: Node, needReplaceElement?: boolean) => {
         replace: Comment | Element;
         style?: Style;
     };
-    collectScript(script: HTMLScriptElement, parent: Node, needReplaceELement?: boolean): {
-        replace: Comment | Element;
-        script?: Script;
-    } | undefined;
-    collectScriptAndStyle(parent: HTMLElement): void;
-    getScript(url: string): Script | undefined;
-    getStyle(urlOrCode: string): Style | undefined;
+    /** 收集脚本元素 */
+    collectScript: (script: HTMLScriptElement, parent: Node, needReplaceElement?: boolean) => CollectResult | undefined;
+    /** 收集样式和脚本 */
+    collectScriptAndStyle: (parent: HTMLElement) => void;
+    getScript: (url: string) => Script | undefined;
+    getStyle: (urlOrCode: string) => Style | undefined;
+    /** html entry */
     importEntry(app: BaseModel): Promise<void>;
+    /** 微应用入口 */
     importHtmlEntry(app: MicroAppModel): Promise<void>;
+    /** 微模块入口 */
     importInstanceEntry(app: BaseModel): Promise<void>;
-    setScript(url: string, script: IScriptOption | Script): void;
-    setStyle(url: string, style: Style): void;
+    setScript: (url: string, script: IScriptOption | Script) => void;
+    setStyle: (url: string, style: Style) => void;
+    /** 处理样式表链接 */
+    private handleStylesheetLink;
+    /**
+     * 处理图标链接
+     */
+    private handleIconLink;
+    /**
+     * 检查是否应该忽略脚本
+     */
+    private shouldIgnoreScript;
+    /**
+     * 处理被排除的脚本
+     */
+    private handleExcludedScript;
+    /**
+     * 处理外部脚本
+     */
+    private handleExternalScript;
+    /**
+     * 处理内联脚本
+     */
+    private handleInlineScript;
+    /**
+     * 处理链接元素
+     */
+    private processLinks;
+    /**
+     * 处理样式元素
+     */
+    private processStyles;
+    /**
+     * 处理脚本元素
+     */
+    private processScripts;
+    /**
+     * 处理Meta元素
+     */
+    private processMetas;
+    /**
+     * 处理图片元素
+     */
+    private processImages;
+    /**
+     * 加载初始资源
+     */
+    private loadInitialSources;
+    /**
+     * 获取HTML content
+     */
+    private fetchHtmlContent;
+    /**
+     * 创建顶层 root 元素
+     */
+    private createWrapElement;
+    /**
+     * 获取JS content
+     */
+    private fetchJsContent;
 }
 
-declare function fetchSource(url: string, options?: {}, app?: BaseModel): Promise<string>;
+type FetchOptions = Record<string, unknown>;
+/**
+ * 统一的资源获取方法，支持应用级别和全局级别的自定义fetch
+ * 优先级：应用级fetchSource > 全局fetchSource > 原生fetch
+ * @param url 要获取的资源URL
+ * @param options fetch请求选项，默认为空对象
+ * @param app 可选的应用实例，如果提供且有自定义fetchSource则优先使用
+ * @returns Promise<string> 返回资源内容的Promise，失败时返回空字符串
+ */
+declare const fetchSource: (url: string, options?: FetchOptions, app?: BaseModel) => Promise<string>;
 
+/** WEWEB运行模式 */
+declare enum WewebMode {
+    /** 微应用模式 */
+    APP = "app",
+    /** 配置模式 */
+    CONFIG = "config",
+    /** 微模块模式 */
+    INSTANCE = "js"
+}
+/** 容器类型 */
+type ContainerType = HTMLElement | ShadowRoot;
+/** 通用回调函数类型 */
+type CallbackFunction<T = unknown> = (instance: BaseModel, exportInstance?: T) => void;
+/** 基础模型属性接口 */
 interface IBaseModelProps {
+    /** 运行模式 */
     [WewebCustomAttrs.mode]?: WewebMode;
+    /** 应用URL */
     [WewebCustomAttrs.url]: string;
-    id?: null | string;
+    /** 应用ID */
+    id?: string | null;
+    /** 是否预加载 */
     isPreLoad?: boolean;
 }
-interface IAppModleProps extends IBaseModelProps {
+/** 微应用模式属性配置 */
+interface IAppModelProps extends IBaseModelProps {
+    /** 传递给子应用的数据 */
     [WewebCustomAttrs.data]?: Record<string, unknown>;
+    /** 是否缓存DOM */
     [WewebCustomAttrs.keepAlive]?: boolean;
+    /** 是否启用样式隔离 */
     [WewebCustomAttrs.scopeCss]?: boolean;
+    /** 是否使用沙盒隔离 */
     [WewebCustomAttrs.scopeJs]?: boolean;
+    /** 是否共享主应用路由 */
     [WewebCustomAttrs.scopeLocation]?: boolean;
-    [WewebCustomAttrs.setShodowDom]?: boolean;
+    /** 是否使用 ShadowDOM */
+    [WewebCustomAttrs.setShadowDom]?: boolean;
+    /** 是否显示源码 */
     [WewebCustomAttrs.showSourceCode]?: boolean;
-    container?: HTMLElement | ShadowRoot | null;
+    /** 容器元素 */
+    container?: ContainerType | null;
+    /** 初始化资源 */
     initSource?: SourceType;
 }
+/** 微模块模式属性配置 */
 interface IJsModelProps extends IBaseModelProps {
+    /** 传递给模块的数据 */
     [WewebCustomAttrs.data]?: Record<string, unknown>;
+    /** 是否显示源码 */
     [WewebCustomAttrs.showSourceCode]?: boolean;
-    container?: HTMLElement | ShadowRoot | null;
+    /** 容器元素 */
+    container?: ContainerType | null;
+    /** 初始化资源 */
     initSource?: SourceType;
+    /** 是否缓存DOM */
     keepAlive?: boolean;
+    /** 是否启用样式隔离 */
     scopeCss?: boolean;
+    /** 是否使用沙盒隔离 */
     scopeJs?: boolean;
 }
+/** 基础模型接口 */
 interface BaseModel {
-    activated<T>(container: HTMLElement | ShadowRoot, callback?: (instance: BaseModel, exportInstance?: T) => void): void;
-    container?: HTMLElement | ShadowRoot;
-    deactivated(): void;
-    get appCacheKey(): string;
-    get status(): AppState;
+    /** 应用缓存键 */
+    readonly appCacheKey: string;
+    /** 容器元素 */
+    container?: ContainerType;
+    /** 初始化资源 */
     initSource?: SourceType;
+    /** 是否为模块应用 */
     isModuleApp?: boolean;
+    /** 是否预加载 */
     isPreLoad: boolean;
+    /** 是否保持活跃 */
     keepAlive?: boolean;
-    mount<T>(container?: HTMLElement | ShadowRoot, callback?: (instance: BaseModel, exportInstance?: T) => void): void;
+    /** 应用名称 */
     name: string;
-    onError(): void;
-    onMount(): void;
-    registerRunningApp(): void;
+    /** 沙盒实例 */
     sandBox?: SandBox;
+    /** 是否启用样式隔离 */
     scopeCss?: boolean;
+    /** 是否使用JS隔离 */
     scopeJs: boolean;
-    set status(v: AppState);
+    /** 是否显示源码 */
     showSourceCode?: boolean;
+    /** 入口资源 */
     source?: EntrySource;
-    start(): Promise<void>;
-    unmount(needDestroy?: boolean): void;
+    /** 应用URL */
     url: string;
+    /** 获取资源的函数 */
     fetchSource?: typeof fetchSource;
-}
-declare enum WewebMode {
-    APP = "app",
-    CONFIG = "config",
-    INSTANCE = "js"
+    /** 传递给应用的数据 */
+    data: Record<string, unknown>;
+    /** 激活应用 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 停用应用 */
+    deactivated(): void;
+    /** 挂载应用 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
+    onError(): void;
+    /** 挂载处理 */
+    onMount(): void;
+    /** 注册运行中的应用 */
+    registerRunningApp(): void;
+    /** 启动应用 */
+    start(): Promise<void>;
+    /** 卸载应用 */
+    unmount(needDestroy?: boolean): void;
+    /** 获取应用状态 */
+    get status(): ValueOfAppState;
+    /** 设置应用状态 */
+    set status(value: ValueOfAppState);
 }
 
 declare global {
@@ -252,39 +654,70 @@ declare global {
     interface Node {
         __BK_WEWEB_APP_KEY__?: string;
         __KEEP_ALIVE__?: string;
-        data?: any;
+        data?: unknown;
     }
 }
 
 /**
- * 接口定义：样式选项
+ * 资源加载相关类型定义
+ * @description 定义了样式、脚本等资源的配置选项和相关类型
+ */
+/**
+ * 样式资源配置选项接口
+ * @description 定义样式文件的加载配置和属性信息
  */
 interface IStyleOption {
+    /** 样式代码内容 */
     code: string;
+    /** 是否来自 HTML 页面内联样式 */
     fromHtml: boolean;
+    /** 是否为初始样式 */
     initial?: boolean;
+    /** 是否预取样式资源 */
     prefetch?: boolean;
+    /** 是否预加载样式资源 */
     preload?: boolean;
+    /** 样式文件的 URL 地址 */
     url?: string;
 }
+/**
+ * 脚本资源配置选项接口
+ * @description 定义脚本文件的加载配置和属性信息
+ */
 interface IScriptOption {
+    /** 是否为异步加载脚本 */
     async: boolean;
+    /** 脚本代码内容 */
     code: string;
+    /** 是否为延迟执行脚本 */
     defer: boolean;
+    /** 是否从 HTML 页面中提取的脚本 */
     fromHtml: boolean;
+    /** 是否为初始脚本 */
     initial?: boolean;
+    /** 是否为 ES6 模块类型脚本 */
     isModule: boolean;
+    /** 脚本文件的 URL 地址 */
     url?: string;
 }
 
 /**
- * Interface for injecting window attributes.
+ * 沙箱环境配置类型定义
+ */
+/**
+ * 注入到子应用 window 对象的属性接口
+ * @description 定义了 BK WEWEB 平台注入到子应用环境中的必要属性
  */
 interface IInjectWindowAttrs {
+    /** BK WEWEB平台的应用唯一标识 */
     __BK_WEWEB_APP_KEY__: string;
+    /** BK WEWEB的附加数据 */
     __BK_WEWEB_DATA__: Record<string, unknown>;
+    /** 标识页面是否由BK WEWEB驱动 */
     __POWERED_BY_BK_WEWEB__: boolean;
+    /** 原始 document 对象的引用 */
     rawDocument: Document;
+    /** 原始 window 对象的引用 */
     rawWindow: Window;
 }
 
@@ -292,18 +725,32 @@ type FetchSourceType = (url: string, options: Record<string, unknown>) => Promis
 interface IStartOption {
     collectBaseSource?: boolean;
     fetchSource?: FetchSourceType;
-    webcomponentTag?: string;
+    webComponentTag?: string;
 }
 
+/**
+ * 激活指定应用
+ * @description 激活已失活的应用或挂载新应用，支持 keep-alive 模式的应用状态恢复
+ * @template T - 导出实例的类型
+ * @param appKey - 应用的唯一标识符
+ * @param container - 挂载容器，HTMLElement 或 ShadowRoot
+ * @param callback - 激活完成后的回调函数（可选）
+ */
 declare function activated<T>(appKey: string, container: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
+/**
+ * deactivated 指定应用
+ * @description 将指定应用设置为失活状态，根据 keep-alive 配置决定
+ */
 declare function deactivated(appKey: string): void;
 
+/** BK-WEWEB 微模块模式类 */
 declare class MicroInstanceModel implements BaseModel {
     private state;
     appCacheKey: string;
-    container?: HTMLElement | ShadowRoot;
+    container?: ContainerType;
     data: Record<string, unknown>;
+    fetchSource?: typeof fetchSource;
     initSource: SourceType;
     isPreLoad: boolean;
     keepAlive: boolean;
@@ -314,53 +761,148 @@ declare class MicroInstanceModel implements BaseModel {
     showSourceCode: boolean;
     source?: EntrySource;
     url: string;
-    fetchSource?: typeof fetchSource;
     constructor(props: IJsModelProps & {
         fetchSource?: typeof fetchSource;
     });
-    activated<T>(container: HTMLElement | ShadowRoot, callback?: (instance: BaseModel, exportInstance?: T) => void): void;
+    /** 激活微模块 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 停用微模块 */
     deactivated(): void;
-    mount<T>(container?: HTMLElement | ShadowRoot, callback?: (instance: MicroInstanceModel, exportInstance: T) => void): void;
+    /** 挂载微模块 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
     onError(): void;
+    /** 挂载处理 */
     onMount(): void;
+    /** 注册运行中的应用 */
     registerRunningApp(): void;
+    /** 启动微模块 */
     start(): Promise<void>;
+    /** 卸载微模块 */
     unmount(needDestroy?: boolean): void;
-    set status(v: AppState);
-    get status(): AppState;
+    /** 初始化ShadowRoot容器 */
+    initShadowRootContainer(): void;
+    set status(value: ValueOfAppState);
+    get status(): ValueOfAppState;
+    /** 初始化沙盒 */
+    private initializeSandBox;
+    /** 设置容器属性 */
+    private setContainerAttribute;
+    /** 转移节点到新容器 */
+    private transferNodes;
+    /** 设置容器 */
+    private setupContainer;
+    /** 执行样式 */
+    private executeStyles;
+    /** 创建实例包装器 */
+    private createInstanceWrapper;
+    /** 渲染实例 */
+    private renderInstance;
+    /** 获取脚本信息 */
+    private getScriptInfo;
+    /** 检查是否需要重新加载 */
+    private needsReload;
 }
 
+/**
+ * 根据配置模式加载相应的应用或模块实例
+ * @description 统一的加载入口，根据模式参数决定加载应用还是模块实例
+ * @param props - 基础模型配置参数
+ * @returns Promise<BaseModel> - 返回加载的模型实例
+ */
 declare function load(props: IBaseModelProps): Promise<BaseModel>;
-declare function loadApp(props: IAppModleProps): Promise<MicroAppModel>;
+/**
+ * 加载微应用
+ * @description 加载或获取已存在的微应用实例，并启动应用
+ * @param props - 应用模型配置参数
+ * @returns Promise<MicroAppModel> - 返回微应用模型实例
+ */
+declare function loadApp(props: IAppModelProps): Promise<MicroAppModel>;
+/**
+ * 加载模块实例
+ * @description 加载或获取已存在的模块实例，支持状态监听和异步等待
+ * @param props - 模块实例配置参数
+ * @returns Promise<MicroInstanceModel> - 返回模块实例模型
+ */
 declare function loadInstance(props: IJsModelProps): Promise<MicroInstanceModel>;
 
+/**
+ * 挂载应用到指定容器
+ * @description 将已加载的应用挂载到指定的 DOM 容器或 ShadowRoot 中
+ * @template T - 导出实例的类型
+ * @param appKey - 应用的唯一标识符
+ * @param container - 挂载容器，可以是 HTMLElement 或 ShadowRoot（可选）
+ * @param callback - 挂载完成后的回调函数（可选）
+ */
 declare function mount<T>(appKey: string, container?: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
+/**
+ * 卸载并删除指定应用
+ * @description 从缓存中完全删除指定的应用实例，释放相关资源
+ * @param url - 应用的 URL 标识符，用于定位要删除的应用
+ */
 declare function unload(url: string): void;
 
+/**
+ * 卸载指定应用
+ * @description 卸载指定的应用实例，并在没有活跃应用时重置全局方法
+ * @param appKey - 应用的唯一标识符
+ */
 declare function unmount(appKey: string): void;
 
 /**
- * @param options 加载模块的参数
- * @description 预加载实例
+ * 预加载模块实例
+ * @description 在浏览器空闲时预加载指定的模块实例，提前准备资源以提升后续加载性能
+ * @param options - 模块加载配置参数
+ * @param options.isPreLoad - 将被自动设置为 true，标识这是预加载操作
+ * @example
+ * ```typescript
+ * preLoadInstance({
+ *   name: 'my-module',
+ *   url: 'https://example.com/module.js'
+ * });
+ * ```
  */
 declare function preLoadInstance(options: IJsModelProps): void;
 /**
- * @param options 加载应用的参数
- * @description 预加载应用
+ * 预加载微应用
+ * @description 在浏览器空闲时预加载指定的微应用，提前准备应用资源以提升后续加载性能
+ * @param options - 应用加载配置参数
+ * @param options.isPreLoad - 将被自动设置为 true，标识这是预加载操作
+ * @example
+ * ```typescript
+ * preLoadApp({
+ *   name: 'my-app',
+ *   entry: 'https://example.com/app/'
+ * });
+ * ```
  */
-declare function preLoadApp(options: IAppModleProps): void;
+declare function preLoadApp(options: IAppModelProps): void;
 /**
- * @param sourceList 要预加载的资源列表
- * @description 预加载资源
+ * 预加载全局资源
+ * @description 在浏览器空闲时预加载指定的全局资源列表，包括样式文件、脚本文件等
+ * @param sourceList - 要预加载的资源列表，可以是单个资源或资源数组
+ * @example
+ * ```typescript
+ * // 预加载单个资源
+ * preLoadSource('https://example.com/style.css');
+ *
+ * // 预加载多个资源
+ * preLoadSource([
+ *   'https://example.com/style.css',
+ *   'https://example.com/script.js'
+ * ]);
+ * ```
  */
 declare function preLoadSource(sourceList: SourceType): void;
 
 declare class WeWeb {
     fetchSource?: FetchSourceType;
-    webcomponentTag: string;
+    webComponentTag: string;
     constructor();
+    /** 设置自定义DOM标签名 */
     setWebComponentTag(): void;
+    /** 启动WeWeb */
     start(option?: IStartOption): void;
 }
 declare const weWeb: WeWeb;