xpe 0.0.0-alpha.1 → 1.0.0

package/dist/kernel/runtime-engine.d.ts

@@ -0,0 +1,154 @@
+export { clearAssetsCache } from "./entry.js";
+import { StyleObject, ScriptAttributes } from "./template.js";
+import { lifecycle } from "./sandbox.js";
+import { EventBus } from "./event.js";
+export declare const bus: EventBus;
+export interface ScriptObjectLoader {
+    /** 脚本地址，内联为空 */
+    src?: string;
+    /** 脚本是否为module模块 */
+    module?: boolean;
+    /** 脚本是否为async执行 */
+    async?: boolean;
+    /** 脚本是否设置crossorigin */
+    crossorigin?: boolean;
+    /** 脚本crossorigin的类型 */
+    crossoriginType?: "anonymous" | "use-credentials" | "";
+    /** 脚本原始属性 */
+    attrs?: ScriptAttributes;
+    /** 内联script的代码 */
+    content?: string;
+    /** 执行回调钩子 */
+    callback?: (appWindow: Window) => any;
+    /** 子应用加载完毕事件 */
+    onload?: Function;
+}
+export interface plugin {
+    /** 处理html的loader */
+    htmlLoader?: (code: string) => string;
+    /** js排除列表 */
+    jsExcludes?: Array<string | RegExp>;
+    /** js忽略列表 */
+    jsIgnores?: Array<string | RegExp>;
+    /** 处理js加载前的loader */
+    jsBeforeLoaders?: Array<ScriptObjectLoader>;
+    /** 处理js的loader */
+    jsLoader?: (code: string, url: string, base: string) => string;
+    /** 处理js加载后的loader */
+    jsAfterLoaders?: Array<ScriptObjectLoader>;
+    /** css排除列表 */
+    cssExcludes?: Array<string | RegExp>;
+    /** css忽略列表 */
+    cssIgnores?: Array<string | RegExp>;
+    /** 处理css加载前的loader */
+    cssBeforeLoaders?: Array<StyleObject>;
+    /** 处理css的loader */
+    cssLoader?: (code: string, url: string, base: string) => string;
+    /** 处理css加载后的loader */
+    cssAfterLoaders?: Array<StyleObject>;
+    /** 子应用 window addEventListener 钩子回调 */
+    windowAddEventListenerHook?: eventListenerHook;
+    /** 子应用 window removeEventListener 钩子回调 */
+    windowRemoveEventListenerHook?: eventListenerHook;
+    /** 子应用 document addEventListener 钩子回调 */
+    documentAddEventListenerHook?: eventListenerHook;
+    /** 子应用 document removeEventListener 钩子回调 */
+    documentRemoveEventListenerHook?: eventListenerHook;
+    /** 子应用 向body、head插入元素后执行的钩子回调 */
+    appendOrInsertElementHook?: <T extends Node>(element: T, iframeWindow: Window) => void;
+    /** 子应用劫持元素的钩子回调 */
+    patchElementHook?: <T extends Node>(element: T, iframeWindow: Window) => void;
+    /** 用户自定义覆盖子应用 window 属性 */
+    windowPropertyOverride?: (iframeWindow: Window) => void;
+    /** 用户自定义覆盖子应用 document 属性 */
+    documentPropertyOverride?: (iframeWindow: Window) => void;
+}
+type eventListenerHook = (iframeWindow: Window, type: string, handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;
+export type loadErrorHandler = (url: string, e: Error) => any;
+type baseOptions = {
+    /** 唯一性用户必须保证 */
+    name: string;
+    /** 需要渲染的url */
+    url: string;
+    /** 需要渲染的html, 如果已有则无需从url请求 */
+    html?: string;
+    /** 代码替换钩子 */
+    replace?: (code: string) => string;
+    /** 自定义fetch */
+    fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /** 注入给子应用的属性 */
+    props?: {
+        [key: string]: any;
+    };
+    /** 自定义运行iframe的属性 */
+    attrs?: {
+        [key: string]: any;
+    };
+    /** 自定义降级渲染iframe的属性 */
+    degradeAttrs?: {
+        [key: string]: any;
+    };
+    /** 子应用采用fiber模式执行 */
+    fiber?: boolean;
+    /** 子应用保活，state不会丢失 */
+    alive?: boolean;
+    /** 子应用采用降级iframe方案 */
+    degrade?: boolean;
+    /** 子应用插件 */
+    plugins?: Array<plugin>;
+    /** 子应用window监听事件 */
+    iframeAddEventListeners?: Array<string>;
+    /** 子应用iframe on事件 */
+    iframeOnEvents?: Array<string>;
+    /** 子应用生命周期 */
+    beforeLoad?: lifecycle;
+    beforeMount?: lifecycle;
+    afterMount?: lifecycle;
+    beforeUnmount?: lifecycle;
+    afterUnmount?: lifecycle;
+    activated?: lifecycle;
+    deactivated?: lifecycle;
+    loadError?: loadErrorHandler;
+};
+export type preOptions = Omit<baseOptions, "url"> & {
+    /** 预执行 */
+    exec?: boolean;
+    url?: string;
+};
+export type startOptions = baseOptions & {
+    /** 渲染的容器 */
+    el: HTMLElement | string;
+    /**
+     * 路由同步开关
+     * 如果false，子应用跳转主应用路由无变化，但是主应用的history还是会增加
+     * https://html.spec.whatwg.org/multipage/history.html#the-history-interface
+     */
+    sync?: boolean;
+    /** 子应用短路径替换，路由同步时生效 */
+    prefix?: {
+        [key: string]: string;
+    };
+    /** 子应用加载时loading元素 */
+    loading?: HTMLElement;
+};
+type optionProperty = "url" | "el";
+/**
+ * 合并 preOptions 和 startOptions，并且将 url 和 el 变成可选
+ */
+export type cacheOptions = Omit<preOptions & startOptions, optionProperty> & Partial<Pick<startOptions, optionProperty>>;
+/**
+ * 缓存子应用配置
+ */
+export declare function setupApp(options: cacheOptions): void;
+/**
+ * 运行子应用
+ */
+export declare function startApp(startOptions: startOptions): Promise<Function | void>;
+/**
+ * 预加载 XPE 子应用
+ */
+export declare function preloadApp(preOptions: preOptions): void;
+/**
+ * 销毁子应用
+ */
+export declare function destroyApp(id: string): Promise<void>;

package/dist/kernel/runtime-engine.js

@@ -0,0 +1,209 @@
+import importHTML, { processCssLoader } from "./entry.js";
+export { clearAssetsCache } from "./entry.js";
+import RuntimeSandbox from "./sandbox.js";
+import { defineRuntimeWebComponent, addLoading, removeLoading } from "./shadow.js";
+import { getPlugins } from "./plugin.js";
+import { runtimeDomSupport, mergeOptions, isFunction, requestIdleCallback, isMatchSyncQueryById, getContainer, warn, stopMainAppRun, } from "./utils.js";
+import { getSandboxById, getOptionsById, addSandboxCacheWithOptions } from "./common.js";
+import { EventBus } from "./event.js";
+import { XPE_TIPS_NOT_SUPPORTED } from "./constant.js";
+import { getXpeInternalSandbox, getXpeMount, isPoweredByXpe } from "./xpe-bridge.js";
+export const bus = new EventBus(Date.now().toString());
+/**
+ * 强制中断主应用运行
+ * 如果当前运行在 XPE 子应用 iframe 中，但 runtime 尚未完成启动标记，
+ * 说明主应用代码在 iframe loading 阶段混入进来了，必须中断执行。
+ */
+if (getXpeInternalSandbox(window) && !isPoweredByXpe(window)) {
+    stopMainAppRun();
+}
+// 处理子应用链接跳转
+// 定义webComponent容器
+defineRuntimeWebComponent();
+// 如果不支持则告警
+if (!runtimeDomSupport)
+    warn(XPE_TIPS_NOT_SUPPORTED);
+/**
+ * 缓存子应用配置
+ */
+export function setupApp(options) {
+    if (options.name)
+        addSandboxCacheWithOptions(options.name, options);
+}
+/**
+ * 运行子应用
+ */
+export async function startApp(startOptions) {
+    const sandbox = getSandboxById(startOptions.name);
+    const cacheOptions = getOptionsById(startOptions.name);
+    // 合并缓存配置
+    const options = mergeOptions(startOptions, cacheOptions);
+    const { name, url, html, replace, fetch, props, attrs, degradeAttrs, fiber, alive, degrade, sync, prefix, el, loading, plugins, lifecycles, iframeAddEventListeners, iframeOnEvents, } = options;
+    // 已经初始化过的应用，快速渲染
+    if (sandbox) {
+        sandbox.plugins = getPlugins(plugins);
+        sandbox.lifecycles = lifecycles;
+        if (sandbox.preload) {
+            await sandbox.preload;
+        }
+        const iframeWindow = sandbox.getLifecycleWindow();
+        if (alive) {
+            // 保活
+            await sandbox.active({ url, sync, prefix, el, props, alive, fetch, replace });
+            const activeWindow = sandbox.getLifecycleWindow();
+            if (!activeWindow)
+                return () => sandbox.destroy();
+            // 预加载但是没有执行的情况
+            if (!sandbox.execFlag) {
+                sandbox.lifecycles?.beforeLoad?.(activeWindow);
+                const { getExternalScripts } = await importHTML({
+                    url,
+                    html,
+                    opts: {
+                        fetch: fetch || window.fetch,
+                        plugins: sandbox.plugins,
+                        loadError: sandbox.lifecycles.loadError,
+                        fiber,
+                    },
+                });
+                await sandbox.start(getExternalScripts);
+            }
+            sandbox.lifecycles?.activated?.(activeWindow);
+            return () => sandbox.destroy();
+        }
+        else if (iframeWindow && isFunction(getXpeMount(iframeWindow))) {
+            /**
+             * 子应用切换会触发webcomponent的disconnectedCallback调用sandbox.unmount进行实例销毁
+             * 此处是防止没有销毁webcomponent时调用startApp的情况，需要手动调用unmount
+             */
+            await sandbox.unmount({ preserveLifecycle: true });
+            await sandbox.active({ url, sync, prefix, el, props, alive, fetch, replace });
+            const activeWindow = sandbox.getLifecycleWindow();
+            if (!activeWindow)
+                return () => sandbox.destroy();
+            // 正常加载的情况，先注入css，最后才mount。重新激活也保持同样的时序
+            sandbox.rebuildStyleSheets();
+            // 有渲染函数
+            sandbox.lifecycles?.beforeMount?.(activeWindow);
+            getXpeMount(activeWindow)?.();
+            sandbox.recoverMountedEventListeners();
+            sandbox.lifecycles?.afterMount?.(activeWindow);
+            sandbox.mountFlag = true;
+            return () => sandbox.destroy();
+        }
+        else {
+            // 没有渲染函数
+            await sandbox.destroy();
+        }
+    }
+    // 设置loading
+    addLoading(el, loading);
+    const newSandbox = new RuntimeSandbox({
+        name,
+        url,
+        attrs,
+        degradeAttrs,
+        fiber,
+        degrade,
+        plugins,
+        lifecycles,
+        iframeAddEventListeners,
+        iframeOnEvents,
+    });
+    const newSandboxWindow = newSandbox.getLifecycleWindow();
+    newSandboxWindow && newSandbox.lifecycles?.beforeLoad?.(newSandboxWindow);
+    try {
+        const { template, getExternalScripts, getExternalStyleSheets } = await importHTML({
+            url,
+            html,
+            opts: {
+                fetch: fetch || window.fetch,
+                plugins: newSandbox.plugins,
+                loadError: newSandbox.lifecycles.loadError,
+                fiber,
+            },
+        });
+        const processedHtml = await processCssLoader(newSandbox, template, getExternalStyleSheets);
+        await newSandbox.active({ url, sync, prefix, template: processedHtml, el, props, alive, fetch, replace });
+        await newSandbox.start(getExternalScripts);
+        return () => newSandbox.destroy();
+    }
+    catch (error) {
+        // 任一环节失败都要主动清理 loading，避免遮罩永久残留在容器上。
+        // 加载链路（importHTML / processCssLoader / active / start）任一步失败时，
+        // 此前 addLoading 注入的 loading 会永久残留在容器上，遮挡后续渲染。
+        // 这里统一兜底：移除 loading、上报 loadError、销毁半初始化的 sandbox，再 rethrow。
+        try {
+            removeLoading(getContainer(el));
+        }
+        catch (_) {
+            /* noop: 清理 loading 不应掩盖原始错误 */
+        }
+        newSandbox.lifecycles?.loadError?.(url, error);
+        await newSandbox.destroy().catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * 预加载 XPE 子应用
+ */
+export function preloadApp(preOptions) {
+    requestIdleCallback(() => {
+        /**
+         * 已经存在
+         * url查询参数中有子应用的id，大概率是刷新浏览器或者分享url，此时需要直接打开子应用，无需预加载
+         */
+        if (getSandboxById(preOptions.name) || isMatchSyncQueryById(preOptions.name))
+            return;
+        const cacheOptions = getOptionsById(preOptions.name);
+        // 合并缓存配置
+        const options = mergeOptions({ ...preOptions }, cacheOptions);
+        const { name, url, html, props, alive, replace, fetch, exec, attrs, degradeAttrs, fiber, degrade, prefix, plugins, lifecycles, iframeAddEventListeners, iframeOnEvents, } = options;
+        const sandbox = new RuntimeSandbox({
+            name,
+            url,
+            attrs,
+            degradeAttrs,
+            fiber,
+            degrade,
+            plugins,
+            lifecycles,
+            iframeAddEventListeners,
+            iframeOnEvents,
+        });
+        if (sandbox.preload)
+            return sandbox.preload;
+        const runPreload = async () => {
+            const sandboxWindow = sandbox.getLifecycleWindow();
+            sandboxWindow && sandbox.lifecycles?.beforeLoad?.(sandboxWindow);
+            const { template, getExternalScripts, getExternalStyleSheets } = await importHTML({
+                url,
+                html,
+                opts: {
+                    fetch: fetch || window.fetch,
+                    plugins: sandbox.plugins,
+                    loadError: sandbox.lifecycles.loadError,
+                    fiber,
+                },
+            });
+            const processedHtml = await processCssLoader(sandbox, template, getExternalStyleSheets);
+            await sandbox.active({ url, props, prefix, alive, template: processedHtml, fetch, replace });
+            if (exec) {
+                await sandbox.start(getExternalScripts);
+            }
+            else {
+                await getExternalScripts();
+            }
+        };
+        sandbox.preload = runPreload();
+    });
+}
+/**
+ * 销毁子应用
+ */
+export async function destroyApp(id) {
+    const sandbox = getSandboxById(id);
+    if (sandbox) {
+        await sandbox.destroy();
+    }
+}

package/dist/kernel/sandbox.d.ts

@@ -0,0 +1,235 @@
+import { type ElementEventRecord } from "./iframe.js";
+import { ScriptResultList } from "./entry.js";
+import { SandboxCache } from "./common.js";
+import { EventBus, EventObj } from "./event.js";
+import { EventCleanupTracker } from "./tracker.js";
+import { plugin, loadErrorHandler } from "./runtime-engine.js";
+export type lifecycle = (appWindow: Window) => any;
+type lifecycles = {
+    beforeLoad: lifecycle;
+    beforeMount: lifecycle;
+    afterMount: lifecycle;
+    beforeUnmount: lifecycle;
+    afterUnmount: lifecycle;
+    activated: lifecycle;
+    deactivated: lifecycle;
+    loadError: loadErrorHandler;
+};
+/**
+ * 基于 Proxy和iframe 实现的沙箱
+ */
+export default class RuntimeSandbox {
+    id: string;
+    /** 激活时路由地址 */
+    url: string;
+    /** 子应用保活 */
+    alive: boolean;
+    /** window代理 */
+    proxy: WindowProxy;
+    /** document代理 */
+    proxyDocument: Object;
+    /** location代理 */
+    proxyLocation: Object;
+    /**
+     * 释放 window / document / location 代理。
+     * 代理的 handler 闭包捕获了 iframe / urlElement 等 DOM 引用，destroy 时调用此函数
+     * 解除代理与 handler 的关联，斩断「主应用 → 代理闭包 → iframe」的引用链。
+     */
+    proxyRevoke: () => void;
+    /** 事件中心 */
+    bus: EventBus;
+    /** 容器 */
+    el: HTMLElement;
+    /** js沙箱 */
+    iframe: HTMLIFrameElement;
+    /** css沙箱 */
+    shadowRoot: ShadowRoot;
+    /** 子应用的template */
+    template: string;
+    /** 子应用代码替换钩子 */
+    replace: (code: string) => string;
+    /** 子应用自定义fetch */
+    fetch: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /** 子应用的生命周期 */
+    lifecycles: lifecycles;
+    /** 子应用的插件 */
+    plugins: Array<plugin>;
+    /** js沙箱ready态 */
+    iframeReady: Promise<void>;
+    /** 子应用预加载态 */
+    preload: Promise<void>;
+    /** 降级时渲染iframe的属性 */
+    degradeAttrs: {
+        [key: string]: any;
+    };
+    /** 子应用js执行队列 */
+    execQueue: Array<Function>;
+    /** 子应用执行过标志 */
+    execFlag: boolean;
+    /** 子应用激活标志 */
+    activeFlag: boolean;
+    /** 子应用mount标志 */
+    mountFlag: boolean;
+    /** 路由同步标志 */
+    sync: boolean;
+    /** 子应用短路径替换，路由同步时生效 */
+    prefix: {
+        [key: string]: string;
+    };
+    /** 子应用跳转标志 */
+    hrefFlag: boolean;
+    /** 子应用采用fiber模式执行 */
+    fiber: boolean;
+    /** 子应用降级标志 */
+    degrade: boolean;
+    /** 子应用降级document */
+    document: Document;
+    /** 子应用styleSheet元素 */
+    styleSheetElements: Array<HTMLLinkElement | HTMLStyleElement>;
+    /**
+     * 子应用通过 document.head.appendChild(<script>) 触发的动态脚本节点。
+     * 由 insertScriptToIframe 在收到 rawElement（即 effect.ts 转发的动态 script）
+     * 时登记，sandbox.destroy() 时统一从 iframe head detach 并清空。
+     */
+    dynamicScriptElements: Array<HTMLScriptElement>;
+    /**
+     * 动态 <link rel=stylesheet> 以空 href 插入（先 appendChild 后 setAttribute('href')，
+     * 如 tinymce 的 StyleSheetLoader）时，effect.ts 会注册一个 MutationObserver 监听
+     * href 的后续赋值。这些 observer 必须在 destroy 时统一 disconnect，否则游离 link
+     * 会通过 node → registered observer → callback 闭包链路把已销毁的 sandbox 钉在内存中。
+     */
+    deferredStyleObservers: Array<MutationObserver>;
+    /**
+     * 动态 <script src> 的串行执行链。每个 sandbox 独立一条，保证「同一子应用内」动态脚本
+     * 按插入顺序串行 fetch+exec；改为 per-sandbox 后，不同子应用之间不再相互阻塞，也避免
+     * 一个已销毁子应用的 pending 链把后续子应用的脚本拖在同一条全局 Promise 上。
+     */
+    dynamicScriptExecStack: Promise<void>;
+    /** 子应用head元素 */
+    head: HTMLHeadElement;
+    /** 子应用body元素 */
+    body: HTMLBodyElement;
+    /** 子应用dom监听事件留存，当降级时用于保存元素事件 */
+    elementEventCacheMap: WeakMap<Node, Array<ElementEventRecord>>;
+    /** 子应用window监听事件 */
+    iframeAddEventListeners?: Array<string>;
+    /** 子应用iframe on事件 */
+    iframeOnEvents?: Array<string>;
+    /** 销毁链路清理跟踪器：记录被转发到主应用 window/document 上的副作用，destroy 时统一回收 */
+    eventCleanupTracker: EventCleanupTracker;
+    /** 销毁状态：destroy 可能由宿主、WebComponent disconnectedCallback、降级 iframe unload 多路触发 */
+    private destroyed;
+    /** href 跳转 popstate 全局监听释放函数；由 sync.ts 引用计数保证只注册一次 */
+    private releaseHrefJumpListener;
+    /** XPE 子应用桥接对象 */
+    childBridge: {
+        bus: EventBus;
+        shadowRoot?: ShadowRoot;
+        props?: {
+            [key: string]: any;
+        };
+        location?: Object;
+    };
+    /** 子应用嵌套场景，父应用传递给子应用的数据 */
+    inject: {
+        idToSandboxMap: Map<String, SandboxCache>;
+        appEventObjMap: Map<String, EventObj>;
+        mainHostPath: string;
+    };
+    isDestroyed(): boolean;
+    getLifecycleWindow(): Window | undefined;
+    private getActiveIframeWindow;
+    private requireActiveIframeWindow;
+    private isCurrentIframeWindow;
+    private insertQueuedScriptWhenActive;
+    private insertAsyncScriptWhenActive;
+    /** 激活子应用
+     * 1、同步路由
+     * 2、动态修改iframe的fetch
+     * 3、准备shadow
+     * 4、准备子应用注入
+     */
+    active(options: {
+        url: string;
+        sync?: boolean;
+        prefix?: {
+            [key: string]: string;
+        };
+        template?: string;
+        el?: string | HTMLElement;
+        props?: {
+            [key: string]: any;
+        };
+        alive?: boolean;
+        fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+        replace?: (code: string) => string;
+    }): Promise<void>;
+    requestIdleCallback(callback: any): number;
+    /** 启动子应用
+     * 1、运行js
+     * 2、处理兼容样式
+     */
+    start(getExternalScripts: () => ScriptResultList): Promise<void>;
+    /**
+     * 框架主动发起mount，如果子应用是异步渲染实例，比如将生命周期函数放到async函数内
+     * 此时如果采用fiber模式渲染（主应用调用mount的时机也是异步不确定的），框架调用mount时可能
+     * 子应用的mount函数还没有挂载到window，所以这里封装一个mount函数，当子应用是异步渲染
+     * 实例时，子应用异步函数里面最后加上window.__XPE__.mount()来主动调用
+     */
+    mount(): void;
+    recoverMountedEventListeners(): void;
+    /** 保活模式和使用proxyLocation.href跳转链接都不应该销毁shadow */
+    unmount(options?: {
+        allowDestroyed?: boolean;
+        preserveLifecycle?: boolean;
+    }): Promise<void>;
+    /** 销毁子应用 */
+    destroy(): Promise<void>;
+    /**
+     * destroy 阶段清空 styleSheetElements，同时把节点从父节点 detach。
+     *
+     * 仅供 destroy 调用：unmount 阶段需要保留数组以便 rebuildStyleSheets 复用样式节点
+     * （子应用 JS 模块只 init 一次，模块代码不会再次生成动态样式）。
+     */
+    clearStyleSheets(): void;
+    /**
+     * destroy 阶段清空 dynamicScriptElements，同时把残留的 <script> 节点从父节点 detach。
+     * 仅供 destroy 调用，理由同 clearStyleSheets。
+     */
+    clearDynamicScripts(): void;
+    /**
+     * unmount / destroy 阶段统一 disconnect 等待 href 赋值的 MutationObserver。
+     * observer 在 href 命中或超时兜底时会自行 disconnect 并出队；
+     * 这里兜底处理「子应用先于 href 赋值被卸载/销毁」的场景。
+     */
+    clearDeferredStyleObservers(): void;
+    /** 当子应用再次激活后，只运行mount函数，样式需要重新恢复 */
+    rebuildStyleSheets(): void;
+    /**
+     * 子应用样式打补丁
+     * 1、兼容:root选择器样式到:host选择器上
+     * 2、将@font-face定义到shadowRoot外部
+     */
+    patchCssRules(): void;
+    /**
+     * @param id 子应用的id，唯一标识
+     * @param url 子应用的url，可以包含protocol、host、path、query、hash
+     */
+    constructor(options: {
+        name: string;
+        url: string;
+        attrs: {
+            [key: string]: any;
+        };
+        degradeAttrs: {
+            [key: string]: any;
+        };
+        fiber: boolean;
+        degrade: any;
+        plugins: Array<plugin>;
+        lifecycles: lifecycles;
+        iframeAddEventListeners?: Array<string>;
+        iframeOnEvents?: Array<string>;
+    });
+}
+export {};