xpe 0.0.0-alpha.1 → 1.0.0

package/dist/kernel/index.d.ts

@@ -0,0 +1,25 @@
+import { type AppBridge, type AppContext, type AppManifest, type RemoteRuntimeConfig } from "../core/index.js";
+export type RuntimeContainer = HTMLElement | string;
+export type RuntimeBridgeFactory = (options: {
+    manifest: AppManifest;
+    context: AppContext;
+}) => AppBridge;
+export type RuntimeStartOptions = {
+    manifest: AppManifest;
+    context: AppContext;
+    container: RuntimeContainer;
+    bridge: AppBridge;
+};
+export type RuntimePreloadOptions = {
+    manifest: AppManifest;
+};
+export type RuntimeDestroyOptions = {
+    appCode: string;
+    runtime: RemoteRuntimeConfig;
+};
+export type RuntimeKernel = {
+    preload(options: RuntimePreloadOptions): void;
+    start(options: RuntimeStartOptions): Promise<void>;
+    destroy(options: RuntimeDestroyOptions): Promise<void>;
+};
+export declare function createRuntimeKernel(): RuntimeKernel;

package/dist/kernel/index.js

@@ -0,0 +1,86 @@
+import { XpeRuntimeError, } from "../core/index.js";
+let runtimeEngineModule;
+let runtimeEngineModulePromise;
+export function createRuntimeKernel() {
+    return {
+        preload({ manifest }) {
+            void loadRuntimeEngine().then(({ preloadApp }) => {
+                preloadApp(toEnginePreloadOptions(manifest));
+            });
+        },
+        async start(options) {
+            const { startApp } = await loadRuntimeEngine();
+            await startApp(toEngineStartOptions(options));
+        },
+        async destroy(options) {
+            const destroy = ({ destroyApp }) => destroyApp(options.runtime.name || options.appCode);
+            if (runtimeEngineModule) {
+                await destroy(runtimeEngineModule);
+                return;
+            }
+            await loadRuntimeEngine().then(destroy);
+        },
+    };
+}
+function loadRuntimeEngine() {
+    if (runtimeEngineModule)
+        return Promise.resolve(runtimeEngineModule);
+    if (!runtimeEngineModulePromise) {
+        const runtimeEnginePath = "./runtime-engine.js";
+        runtimeEngineModulePromise = import(runtimeEnginePath).then((module) => {
+            runtimeEngineModule = module;
+            return runtimeEngineModule;
+        });
+    }
+    return runtimeEngineModulePromise;
+}
+function toEnginePreloadOptions(manifest) {
+    const { runtime } = manifest;
+    const runtimeName = runtime.name ?? manifest.appCode;
+    return {
+        name: runtimeName,
+        url: runtime.url,
+        alive: runtime.alive,
+        sync: runtime.sync,
+        prefix: toRuntimePrefix(runtime),
+        fetch: toRuntimeFetch(runtime.credentials),
+        props: {
+            appCode: manifest.appCode,
+            manifest,
+            runtime,
+        },
+    };
+}
+function toEngineStartOptions(options) {
+    const { manifest, context, bridge } = options;
+    return {
+        ...toEnginePreloadOptions(manifest),
+        el: toRuntimeContainer(options.container, manifest.appCode),
+        props: {
+            appCode: manifest.appCode,
+            context,
+            manifest,
+            runtime: manifest.runtime,
+            bridge,
+        },
+    };
+}
+function toRuntimeContainer(container, appCode) {
+    if (typeof container === "string")
+        return container;
+    if (container instanceof HTMLElement)
+        return container;
+    throw new XpeRuntimeError("XPE_CONTAINER_MISSING", "XPE 应用挂载容器必须是 HTMLElement 或选择器", {
+        appCode,
+    });
+}
+function toRuntimePrefix(runtime) {
+    if (!runtime.basename || !runtime.name)
+        return undefined;
+    return { [runtime.name]: runtime.basename };
+}
+function toRuntimeFetch(credentials) {
+    if (!credentials)
+        return undefined;
+    return (input, init) => window.fetch(input, { ...init, credentials: init?.credentials ?? credentials });
+}

package/dist/kernel/plugin.d.ts

@@ -0,0 +1,36 @@
+import { plugin } from "./runtime-engine.js";
+interface loaderOption {
+    plugins: Array<plugin>;
+    replace: (code: string) => string;
+}
+/**
+ * 获取柯里化 cssLoader
+ */
+export declare function getCssLoader({ plugins, replace }: loaderOption): (code: string, src: string, base: string) => string;
+/**
+ * 获取柯里化 jsLoader
+ */
+export declare function getJsLoader({ plugins, replace }: loaderOption): (code: string, src: string, base: string) => string;
+/**
+ * 获取预置插件
+ */
+type presetLoadersType = "cssBeforeLoaders" | "cssAfterLoaders" | "jsBeforeLoaders" | "jsAfterLoaders";
+export declare function getPresetLoaders(loaderType: presetLoadersType, plugins: Array<plugin>): plugin[presetLoadersType];
+/**
+ * 获取影响插件
+ */
+type effectLoadersType = "jsExcludes" | "cssExcludes" | "jsIgnores" | "cssIgnores";
+export declare function getEffectLoaders(loaderType: effectLoadersType, plugins: Array<plugin>): plugin[effectLoadersType];
+export declare function isMatchUrl(url: string, effectLoaders: plugin[effectLoadersType]): boolean;
+/**
+ * 转换子应用css内的相对地址成绝对地址
+ */
+declare function cssRelativePathResolve(code: string, src: string, base: string): string;
+declare const defaultPlugin: {
+    cssLoader: typeof cssRelativePathResolve;
+    cssBeforeLoaders: {
+        content: string;
+    }[];
+};
+export declare function getPlugins(plugins: Array<plugin>): Array<plugin>;
+export default defaultPlugin;

package/dist/kernel/plugin.js

@@ -0,0 +1,68 @@
+import { compose, getAbsolutePath } from "./utils.js";
+/**
+ * 获取柯里化 cssLoader
+ */
+export function getCssLoader({ plugins, replace }) {
+    return (code, src = "", base) => compose(plugins.map((plugin) => plugin.cssLoader))(replace ? replace(code) : code, src, base);
+}
+/**
+ * 获取柯里化 jsLoader
+ */
+export function getJsLoader({ plugins, replace }) {
+    return (code, src = "", base) => compose(plugins.map((plugin) => plugin.jsLoader))(replace ? replace(code) : code, src, base);
+}
+export function getPresetLoaders(loaderType, plugins) {
+    const loaders = plugins
+        .map((plugin) => plugin[loaderType])
+        .filter((loaders) => loaders?.length);
+    const res = loaders.reduce((preLoaders, curLoaders) => preLoaders.concat(curLoaders), []);
+    return loaderType === "cssBeforeLoaders" ? res.reverse() : res;
+}
+export function getEffectLoaders(loaderType, plugins) {
+    return plugins
+        .map((plugin) => plugin[loaderType])
+        .filter((loaders) => loaders?.length)
+        .reduce((preLoaders, curLoaders) => preLoaders.concat(curLoaders), []);
+}
+// 判断 url 是否符合loader的规则
+export function isMatchUrl(url, effectLoaders) {
+    return effectLoaders.some((loader) => (typeof loader === "string" ? url === loader : loader.test(url)));
+}
+/**
+ * 转换子应用css内的相对地址成绝对地址
+ */
+function cssRelativePathResolve(code, src, base) {
+    const baseUrl = src ? getAbsolutePath(src, base) : base;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/CSS/url
+     *
+     * 旧: const urlReg = /(url\((?!['"]?(?:data):)['"]?)([^'")]*)(['"]?\))/g;
+     *
+     * 这里修改一下正则匹配，先匹配url(xxx)内的xxx，需要兼容一下嵌套括号，
+     * 再判断是否为base64，不再预先忽略data:前缀，防止base64的svg内仍有url被匹配
+     *
+     * eg:
+     * background: url(data:image/svg+xml;charset=utf-8,<svg><path fill=url(#a)></path></svg>)
+     * 以上样式会匹配出#a并进行修改，svg填充的路径就出问题了。
+     *
+     *  */
+    const urlReg = /url\((['"]?)((?:[^()]+|\((?:[^()]+|\([^()]*\))*\))*)(\1)\)/g;
+    return code.replace(urlReg, (_m, pre, url, post) => {
+        const base64Regx = /^data:/;
+        const isBase64 = base64Regx.test(url);
+        /** 如果匹配到data:前缀，则认为是base64文件，直接不进行路径替换吧 */
+        if (isBase64) {
+            return _m;
+        }
+        return `url(${pre}${getAbsolutePath(url, baseUrl)}${post})`;
+    });
+}
+const defaultPlugin = {
+    cssLoader: cssRelativePathResolve,
+    // 禁用 view-transition 继承，避免子应用切换时污染宿主页面动效。
+    cssBeforeLoaders: [{ content: "html {view-transition-name: none;}" }],
+};
+export function getPlugins(plugins) {
+    return Array.isArray(plugins) ? [defaultPlugin, ...plugins] : [defaultPlugin];
+}
+export default defaultPlugin;

package/dist/kernel/proxy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 非降级情况下window、document、location代理
+ */
+export declare function proxyGenerator(iframe: HTMLIFrameElement, urlElement: HTMLAnchorElement, mainHostPath: string, appHostPath: string): {
+    proxyWindow: Window;
+    proxyDocument: Object;
+    proxyLocation: Object;
+    proxyRevoke: () => void;
+};
+/**
+ * 降级情况下document、location代理处理
+ */
+export declare function localGenerator(iframe: HTMLIFrameElement, urlElement: HTMLAnchorElement, mainHostPath: string, appHostPath: string): {
+    proxyDocument: Object;
+    proxyLocation: Object;
+    proxyRevoke: () => void;
+};

package/dist/kernel/proxy.js

@@ -0,0 +1,440 @@
+import { patchElementEffect, renderIframeReplaceApp } from "./iframe.js";
+import { renderElementToContainer } from "./shadow.js";
+import { pushUrlToWindow } from "./sync.js";
+import { documentProxyProperties, rawDocumentQuerySelector } from "./common.js";
+import { XPE_TIPS_RELOAD_DISABLED, XPE_TIPS_GET_ELEMENT_BY_ID } from "./constant.js";
+import { getTargetValue, anchorElementGenerator, getDegradeIframe, isCallable, checkProxyFunction, warn, stopMainAppRun, } from "./utils.js";
+import { getXpeInternalSandbox, getXpeRawDocumentCreateElement, getXpeRawDocumentCreateTextNode, getXpeRawDocumentHead, getXpeRawDocumentQuerySelector, getXpeRawDocumentQuerySelectorAll, } from "./xpe-bridge.js";
+/**
+ * location href 的set劫持操作
+ */
+function locationHrefSet(iframe, value, appHostPath) {
+    const iframeWindow = getIframeWindow(iframe);
+    const iframeDocument = getIframeDocument(iframe);
+    const sandbox = getActiveSandbox(getXpeInternalSandbox(iframeWindow));
+    const { shadowRoot, id, degrade, document, degradeAttrs } = sandbox;
+    let url = value;
+    if (!/^http/.test(url)) {
+        const hrefElement = anchorElementGenerator(url);
+        url = appHostPath + hrefElement.pathname + hrefElement.search + hrefElement.hash;
+    }
+    sandbox.hrefFlag = true;
+    if (degrade) {
+        const iframeBody = getHtmlElement(rawDocumentQuerySelector.call(iframeDocument, "body"));
+        const degradeContainer = getElementParent(getHtmlElement(getDegradeIframe(id)));
+        renderElementToContainer(document.documentElement, iframeBody);
+        renderIframeReplaceApp(window.decodeURIComponent(url), degradeContainer, degradeAttrs);
+    }
+    else
+        renderIframeReplaceApp(url, getElementParent(shadowRoot.host), degradeAttrs);
+    pushUrlToWindow(id, url);
+    return true;
+}
+/**
+ * 非降级情况下window、document、location代理
+ */
+export function proxyGenerator(iframe, urlElement, mainHostPath, appHostPath) {
+    const iframeWindow = getIframeWindow(iframe);
+    const iframeDocument = getIframeDocument(iframe);
+    const { proxy: proxyWindow, revoke: revokeWindow } = Proxy.revocable(iframeWindow, {
+        get: (target, p) => {
+            // location进行劫持
+            if (p === "location") {
+                return getActiveSandbox(getXpeInternalSandbox(target)).proxyLocation;
+            }
+            // 判断自身
+            if (p === "self" || (p === "window" && Object.getOwnPropertyDescriptor(window, "window").get)) {
+                return getActiveSandbox(getXpeInternalSandbox(target)).proxy;
+            }
+            // https://262.ecma-international.org/8.0/#sec-proxy-object-internal-methods-and-internal-slots-get-p-receiver
+            const descriptor = Object.getOwnPropertyDescriptor(target, p);
+            if (descriptor?.configurable === false && descriptor?.writable === false) {
+                return target[p];
+            }
+            // 修正this指针指向
+            return getTargetValue(target, p);
+        },
+        set: (target, p, value) => {
+            checkProxyFunction(target, value);
+            target[p] = value;
+            return true;
+        },
+        has: (target, p) => p in target,
+    });
+    // proxy document
+    const { proxy: proxyDocument, revoke: revokeDocument } = Proxy.revocable({}, {
+        get: function (_fakeDocument, propKey) {
+            const document = window.document;
+            const { shadowRoot, proxyLocation } = getActiveSandbox(getXpeInternalSandbox(iframeWindow));
+            // iframe初始化完成后，webcomponent还未挂在上去，此时运行了主应用代码，必须中止
+            if (!shadowRoot)
+                stopMainAppRun();
+            const rawCreateElement = getXpeRawDocumentCreateElement(iframeWindow);
+            const rawCreateTextNode = getXpeRawDocumentCreateTextNode(iframeWindow);
+            // need fix
+            if (propKey === "createElement" || propKey === "createTextNode") {
+                return new Proxy(document[propKey], {
+                    apply(_createElement, _ctx, args) {
+                        const rawCreateMethod = propKey === "createElement" ? rawCreateElement : rawCreateTextNode;
+                        const element = rawCreateMethod.apply(iframeDocument, args);
+                        patchElementEffect(element, iframeWindow);
+                        return element;
+                    },
+                });
+            }
+            if (propKey === "documentURI" || propKey === "URL") {
+                return proxyLocation.href;
+            }
+            // from shadowRoot
+            if (propKey === "getElementsByTagName" ||
+                propKey === "getElementsByClassName" ||
+                propKey === "getElementsByName") {
+                return new Proxy(shadowRoot.querySelectorAll, {
+                    apply(querySelectorAll, _ctx, args) {
+                        let arg = args[0];
+                        if (_ctx !== iframeDocument) {
+                            return getDocumentCollectionByProxyKey(_ctx, propKey, args);
+                        }
+                        if (propKey === "getElementsByTagName" && arg === "script") {
+                            return iframeDocument.scripts;
+                        }
+                        if (propKey === "getElementsByClassName")
+                            arg = "." + arg;
+                        if (propKey === "getElementsByName")
+                            arg = `[name="${arg}"]`;
+                        // FIXME: This string must be a valid CSS selector string; if it's not, a SyntaxError exception is thrown;
+                        // so we should ensure that the program can execute normally in case of exceptions.
+                        // reference: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll
+                        let res;
+                        try {
+                            res = querySelectorAll.call(shadowRoot, arg);
+                        }
+                        catch (error) {
+                            res = [];
+                        }
+                        return res;
+                    },
+                });
+            }
+            if (propKey === "getElementById") {
+                return new Proxy(shadowRoot.querySelector, {
+                    // case document.querySelector.call
+                    apply(target, ctx, args) {
+                        if (ctx !== iframeDocument) {
+                            return Document.prototype.getElementById.call(ctx, args[0]);
+                        }
+                        try {
+                            return (target.call(shadowRoot, `[id="${args[0]}"]`) ||
+                                getXpeRawDocumentQuerySelector(iframeWindow).call(iframeWindow.document, `#${args[0]}`));
+                        }
+                        catch (error) {
+                            warn(XPE_TIPS_GET_ELEMENT_BY_ID);
+                            return null;
+                        }
+                    },
+                });
+            }
+            if (propKey === "querySelector" || propKey === "querySelectorAll") {
+                const rawPropMap = {
+                    querySelector: getXpeRawDocumentQuerySelector,
+                    querySelectorAll: getXpeRawDocumentQuerySelectorAll,
+                };
+                return new Proxy(shadowRoot[propKey], {
+                    apply(target, ctx, args) {
+                        if (ctx !== iframeDocument) {
+                            return getRawDocumentQuery(propKey).call(ctx, args[0]);
+                        }
+                        // 二选一，优先shadowDom，除非采用array合并，排除base，防止对router造成影响
+                        return (target.apply(shadowRoot, args) ||
+                            (args[0] === "base"
+                                ? null
+                                : rawPropMap[propKey](iframeWindow).call(iframeWindow.document, args[0])));
+                    },
+                });
+            }
+            if (propKey === "documentElement" || propKey === "scrollingElement")
+                return shadowRoot.firstElementChild;
+            if (propKey === "forms")
+                return shadowRoot.querySelectorAll("form");
+            if (propKey === "images")
+                return shadowRoot.querySelectorAll("img");
+            if (propKey === "links")
+                return shadowRoot.querySelectorAll("a");
+            const { ownerProperties, shadowProperties, shadowMethods, documentProperties, documentMethods } = documentProxyProperties;
+            if (ownerProperties.concat(shadowProperties).includes(propKey.toString())) {
+                if (propKey === "activeElement" && shadowRoot.activeElement === null)
+                    return shadowRoot.body;
+                return shadowRoot[propKey];
+            }
+            if (shadowMethods.includes(propKey.toString())) {
+                return getTargetValue(shadowRoot, propKey) ?? getTargetValue(document, propKey);
+            }
+            // from window.document
+            if (documentProperties.includes(propKey.toString())) {
+                return document[propKey];
+            }
+            if (documentMethods.includes(propKey.toString())) {
+                return getTargetValue(document, propKey);
+            }
+            // 兜底：未分类属性（title / cookie / domain / designMode 等）回退到子应用自身 document，
+            // 与下方 set trap 保持同一归属，保证读写往返一致；缺失此兜底时一律返回 undefined。
+            return getTargetValue(iframeDocument, propKey);
+        },
+        set: function (_fakeDocument, propKey, value) {
+            // 写操作转发到子应用自身的 iframe document，避免落到空对象后静默丢失
+            // （document.title / document.cookie / document.domain / designMode 等可写属性）。
+            iframeDocument[propKey] = value;
+            return true;
+        },
+        has: function (_fakeDocument, propKey) {
+            // 让 'cookie' in document、'title' in document 等特性探测反映真实 document。
+            return propKey in window.document;
+        },
+        ownKeys: function () {
+            // 让 Object.keys(document) / Reflect.ownKeys(document) 反映真实 document 的自有键。
+            return Reflect.ownKeys(window.document);
+        },
+        getOwnPropertyDescriptor: function (_fakeDocument, propKey) {
+            const descriptor = Object.getOwnPropertyDescriptor(window.document, propKey) ||
+                Object.getOwnPropertyDescriptor(Document.prototype, propKey);
+            if (!descriptor)
+                return undefined;
+            // fake target 上无对应键，必须 configurable 才能满足 Proxy 不变量。
+            return { ...descriptor, configurable: true };
+        },
+    });
+    // proxy location
+    const { proxy: proxyLocation, revoke: revokeLocation } = Proxy.revocable({}, {
+        get: function (_fakeLocation, propKey) {
+            const location = iframe.contentWindow.location;
+            if (propKey === "host" ||
+                propKey === "hostname" ||
+                propKey === "protocol" ||
+                propKey === "port" ||
+                propKey === "origin") {
+                return urlElement[propKey];
+            }
+            if (propKey === "href") {
+                return location[propKey].replace(mainHostPath, appHostPath);
+            }
+            if (propKey === "reload") {
+                warn(XPE_TIPS_RELOAD_DISABLED);
+                return () => null;
+            }
+            if (propKey === "replace") {
+                return new Proxy(location[propKey], {
+                    apply(replace, _ctx, args) {
+                        return replace.call(location, args[0]?.replace(appHostPath, mainHostPath));
+                    },
+                });
+            }
+            return getTargetValue(location, propKey);
+        },
+        set: function (_fakeLocation, propKey, value) {
+            // 如果是跳转链接的话重开一个iframe
+            if (propKey === "href") {
+                return locationHrefSet(iframe, value, appHostPath);
+            }
+            iframeWindow.location[propKey] = value;
+            return true;
+        },
+        ownKeys: function () {
+            return Object.keys(iframeWindow.location).filter((key) => key !== "reload");
+        },
+        getOwnPropertyDescriptor: function (_target, key) {
+            // 取真实 iframe location 上的值，而非 handler 自身属性（this 指向 handler 会导致全部失真）。
+            return { enumerable: true, configurable: true, value: iframeWindow.location[key] };
+        },
+    });
+    // revoke 后引擎清空代理的 [[ProxyTarget]] / [[ProxyHandler]]，使捕获了 iframe / urlElement
+    // 的 handler 闭包不可达，从而释放对 iframe 的强引用
+    const proxyRevoke = () => {
+        revokeWindow();
+        revokeDocument();
+        revokeLocation();
+    };
+    return { proxyWindow, proxyDocument, proxyLocation, proxyRevoke };
+}
+/**
+ * 降级情况下document、location代理处理
+ */
+export function localGenerator(iframe, urlElement, mainHostPath, appHostPath) {
+    const iframeWindow = getIframeWindow(iframe);
+    // 降级模式无法使用 Proxy.revocable，改用可清空的引用：getter 闭包统一通过 iframeRef /
+    // sandboxRef / locationRef 这三个 let 绑定访问 DOM，proxyRevoke 时置 null，闭包即丢失
+    // 对 iframe 的强引用，斩断「主应用 → 代理闭包 → iframe」的引用链。
+    let iframeRef = iframe;
+    let sandboxRef = getActiveSandbox(getXpeInternalSandbox(iframeWindow));
+    let locationRef = iframeWindow.location;
+    // 代理 document
+    const proxyDocument = {};
+    // 特殊处理
+    Object.defineProperties(proxyDocument, {
+        createElement: {
+            get: () => {
+                return function (...args) {
+                    const activeIframe = getActiveIframe(iframeRef);
+                    const activeWindow = getIframeWindow(activeIframe);
+                    const activeDocument = getIframeDocument(activeIframe);
+                    const element = getXpeRawDocumentCreateElement(activeWindow).apply(activeDocument, args);
+                    patchElementEffect(element, activeWindow);
+                    return element;
+                };
+            },
+        },
+        createTextNode: {
+            get: () => {
+                return function (...args) {
+                    const activeIframe = getActiveIframe(iframeRef);
+                    const activeWindow = getIframeWindow(activeIframe);
+                    const activeDocument = getIframeDocument(activeIframe);
+                    const element = getXpeRawDocumentCreateTextNode(activeWindow).apply(activeDocument, args);
+                    patchElementEffect(element, activeWindow);
+                    return element;
+                };
+            },
+        },
+        documentURI: {
+            get: () => sandboxRef?.proxyLocation?.href,
+        },
+        URL: {
+            get: () => sandboxRef?.proxyLocation?.href,
+        },
+        getElementsByTagName: {
+            get() {
+                return function (...args) {
+                    const activeIframe = getActiveIframe(iframeRef);
+                    const activeDocument = getIframeDocument(activeIframe);
+                    const activeSandbox = getActiveSandbox(sandboxRef);
+                    const tagName = args[0];
+                    if (tagName === "script") {
+                        return activeDocument.scripts;
+                    }
+                    return activeSandbox.document.getElementsByTagName(tagName);
+                };
+            },
+        },
+        getElementById: {
+            get() {
+                return function (...args) {
+                    const activeIframe = getActiveIframe(iframeRef);
+                    const activeWindow = getIframeWindow(activeIframe);
+                    const activeSandbox = getActiveSandbox(sandboxRef);
+                    const id = args[0];
+                    return (activeSandbox.document.getElementById(id) ||
+                        getXpeRawDocumentHead(activeWindow).querySelector(`#${id}`));
+                };
+            },
+        },
+    });
+    // 普通处理
+    const { modifyLocalProperties, modifyProperties, ownerProperties, shadowProperties, shadowMethods, documentProperties, documentMethods, } = documentProxyProperties;
+    modifyProperties
+        .filter((key) => !modifyLocalProperties.includes(key))
+        .concat(ownerProperties, shadowProperties, shadowMethods, documentProperties, documentMethods)
+        .forEach((key) => {
+        Object.defineProperty(proxyDocument, key, {
+            get: () => {
+                const activeSandbox = getActiveSandbox(sandboxRef);
+                const value = activeSandbox.document?.[key];
+                return isCallable(value) ? value.bind(activeSandbox.document) : value;
+            },
+        });
+    });
+    // 代理 location
+    const proxyLocation = {};
+    const locationKeys = Object.keys(locationRef);
+    const constantKey = ["host", "hostname", "port", "protocol", "port"];
+    constantKey.forEach((key) => {
+        proxyLocation[key] = urlElement[key];
+    });
+    Object.defineProperties(proxyLocation, {
+        href: {
+            get: () => getActiveLocation(locationRef).href.replace(mainHostPath, appHostPath),
+            set: (value) => {
+                locationHrefSet(getActiveIframe(iframeRef), value, appHostPath);
+            },
+        },
+        reload: {
+            get() {
+                warn(XPE_TIPS_RELOAD_DISABLED);
+                return () => null;
+            },
+        },
+    });
+    locationKeys
+        .filter((key) => !constantKey.concat(["href", "reload"]).includes(key))
+        .forEach((key) => {
+        Object.defineProperty(proxyLocation, key, {
+            get: () => {
+                const activeLocation = getActiveLocation(locationRef);
+                const value = activeLocation[key];
+                return isCallable(value) ? value.bind(activeLocation) : value;
+            },
+        });
+    });
+    // 置空捕获的 DOM 引用，斩断 getter 闭包对 iframe / location / sandbox 的强引用
+    const proxyRevoke = () => {
+        iframeRef = null;
+        sandboxRef = null;
+        locationRef = null;
+    };
+    return { proxyDocument, proxyLocation, proxyRevoke };
+}
+function getIframeWindow(iframe) {
+    if (!iframe.contentWindow) {
+        throw new Error("XPE runtime iframe window is unavailable");
+    }
+    return iframe.contentWindow;
+}
+function getIframeDocument(iframe) {
+    if (!iframe.contentDocument) {
+        throw new Error("XPE runtime iframe document is unavailable");
+    }
+    return iframe.contentDocument;
+}
+function getActiveSandbox(sandbox) {
+    if (!sandbox) {
+        throw new Error("XPE runtime sandbox is unavailable");
+    }
+    return sandbox;
+}
+function getActiveIframe(iframe) {
+    if (!iframe) {
+        throw new Error("XPE runtime iframe has been released");
+    }
+    return iframe;
+}
+function getActiveLocation(location) {
+    if (!location) {
+        throw new Error("XPE runtime location has been released");
+    }
+    return location;
+}
+function getElementParent(element) {
+    if (!(element.parentElement instanceof HTMLElement)) {
+        throw new Error("XPE runtime render container is unavailable");
+    }
+    return element.parentElement;
+}
+function getHtmlElement(element) {
+    if (!(element instanceof HTMLElement)) {
+        throw new Error("XPE runtime target element is unavailable");
+    }
+    return element;
+}
+function getRawDocumentQuery(propKey) {
+    return propKey === "querySelector" ? Document.prototype.querySelector : Document.prototype.querySelectorAll;
+}
+function getDocumentCollectionByProxyKey(ctx, propKey, args) {
+    if (propKey === "getElementsByTagName") {
+        return Document.prototype.getElementsByTagName.call(ctx, args[0]);
+    }
+    if (propKey === "getElementsByClassName") {
+        return Document.prototype.getElementsByClassName.call(ctx, args[0]);
+    }
+    if (propKey === "getElementsByName") {
+        return Document.prototype.getElementsByName.call(ctx, args[0]);
+    }
+    return [];
+}