xpe 0.0.0-alpha.1 → 1.0.0

package/dist/child/app-client.d.ts

@@ -0,0 +1,44 @@
+import { type AppBridge, type AppContext, type AppEventHandler, type AppNavigationTarget, type HostNavigationTarget, type RuntimeInfo, type RouteMode, type Unsubscribe } from "../core/index.js";
+export type CreateAppClientOptions = {
+    appCode: string;
+    basename: string;
+    routeMode?: RouteMode;
+    devHost?: AppBridge & {
+        runtime?: RuntimeInfo;
+    };
+    targetWindow?: Window;
+};
+export type RouterSyncRoute = {
+    fullPath?: string;
+    path?: string;
+};
+export type RouterSyncAdapter = {
+    currentRoute?: RouterSyncRoute | {
+        value: RouterSyncRoute;
+    };
+    push(path: string): void | Promise<unknown>;
+    replace(path: string): void | Promise<unknown>;
+    afterEach(handler: (to: RouterSyncRoute) => void): Unsubscribe;
+    isReady?: () => Promise<unknown>;
+};
+export type RouterSyncOptions = {
+    initialPath?: string;
+    getCurrentPath?: () => string;
+    targetWindow?: Window;
+};
+export type AppClient = {
+    isHosted(): boolean;
+    getRuntime(): RuntimeInfo | null;
+    getContext(): AppContext;
+    onContextChange(handler: AppEventHandler<AppContext>): Unsubscribe;
+    hasPermission(permissionCode: string): boolean;
+    emit<TPayload = unknown>(eventName: string, payload: TPayload): void;
+    on<TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>): Unsubscribe;
+    off<TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>): void;
+    navigate(target: string | AppNavigationTarget): void;
+    navigateHost(target: string | HostNavigationTarget): void;
+    reportRouteChange(path: string): void;
+    onRouteChange(handler: AppEventHandler<string>): Unsubscribe;
+    syncRouter(router: RouterSyncAdapter, options?: RouterSyncOptions): Promise<Unsubscribe>;
+};
+export declare function createAppClient(options: CreateAppClientOptions): AppClient;

package/dist/child/app-client.js

@@ -0,0 +1,151 @@
+import { getRuntimeWindow, XPE_ROUTE_CHANGE_EVENT, XpeRuntimeError, } from "../core/index.js";
+export function createAppClient(options) {
+    const runtimeWindow = getRuntimeWindow(options.targetWindow);
+    const bridge = options.devHost ?? runtimeWindow.__XPE__;
+    const runtime = options.devHost?.runtime ?? runtimeWindow.__XPE_RUNTIME__;
+    function getContext() {
+        const context = bridge?.getContext?.() ?? bridge?.context;
+        if (!context) {
+            throw new XpeRuntimeError("XPE_CONTEXT_MISSING", "XPE 应用上下文不存在", {
+                appCode: options.appCode,
+            });
+        }
+        return context;
+    }
+    return {
+        isHosted() {
+            return Boolean(runtime?.poweredByXpe || bridge);
+        },
+        getRuntime() {
+            return runtime ?? null;
+        },
+        getContext,
+        onContextChange(handler) {
+            return bridge?.onContextChange?.(handler) ?? (() => undefined);
+        },
+        hasPermission(permissionCode) {
+            return getContext().permissions.includes(permissionCode);
+        },
+        emit(eventName, payload) {
+            bridge?.emit?.(eventName, payload);
+        },
+        on(eventName, handler) {
+            return bridge?.on?.(eventName, handler) ?? (() => undefined);
+        },
+        off(eventName, handler) {
+            bridge?.off?.(eventName, handler);
+        },
+        navigate(target) {
+            if (bridge?.navigate) {
+                bridge.navigate(target);
+                return;
+            }
+            runtimeWindow.location.href = assertAllowedNavigationTarget(typeof target === "string" ? target : formatStandaloneNavigationTarget(target));
+        },
+        navigateHost(target) {
+            if (bridge?.navigateHost) {
+                bridge.navigateHost(target);
+                return;
+            }
+            runtimeWindow.location.href = assertAllowedNavigationTarget(typeof target === "string" ? target : formatStandaloneNavigationTarget(target));
+        },
+        reportRouteChange(path) {
+            bridge?.reportRouteChange?.(path);
+        },
+        onRouteChange(handler) {
+            return bridge?.on?.(XPE_ROUTE_CHANGE_EVENT, handler) ?? (() => undefined);
+        },
+        async syncRouter(router, syncOptions = {}) {
+            // 用「待抑制的 host 路径」而非布尔标志做回声抑制：host 驱动的 replace 会触发
+            // afterEach，需要跳过这一次上报，避免把 host→child 的同步又回报给 host。
+            // 旧实现用布尔 syncingFromHost，依赖 afterEach 必然触发来复位；但 replace 在
+            // 同路径 / 去重 / 守卫拒绝时不触发 afterEach，标志就永久卡在 true，后续真实
+            // 用户导航被静默吞掉、永不上报。改为按路径比对 + finally 兜底清理，两个问题都解。
+            let pendingHostPath = null;
+            const getCurrentPath = syncOptions.getCurrentPath ?? (() => getCurrentRouterPath(router));
+            const initialPath = syncOptions.initialPath ?? getInitialRoutePath(syncOptions.targetWindow ?? runtimeWindow);
+            await router.push(initialPath);
+            await router.isReady?.();
+            this.reportRouteChange(getCurrentPath());
+            const removeRouteHook = router.afterEach((to) => {
+                const toPath = to.fullPath ?? to.path ?? getCurrentPath();
+                if (pendingHostPath !== null && toPath === pendingHostPath) {
+                    // 这一次导航是 host 驱动的回声，吞掉不回报，并清除待抑制标记。
+                    pendingHostPath = null;
+                    return;
+                }
+                this.reportRouteChange(toPath);
+            });
+            const unsubscribeRouteChange = this.onRouteChange((path) => {
+                pendingHostPath = path;
+                // replace 若未触发 afterEach（同路径/去重/守卫拒绝），用 finally 清除残留标记，
+                // 防止下一次真实用户导航被错误抑制。
+                Promise.resolve(router.replace(path)).finally(() => {
+                    if (pendingHostPath === path)
+                        pendingHostPath = null;
+                });
+            });
+            return () => {
+                removeRouteHook();
+                unsubscribeRouteChange();
+            };
+        },
+    };
+}
+function getInitialRoutePath(targetWindow) {
+    return targetWindow.location.hash.replace(/^#/, "") || "/";
+}
+function getCurrentRouterPath(router) {
+    const route = unwrapCurrentRoute(router.currentRoute);
+    return route.fullPath ?? route.path ?? "/";
+}
+function unwrapCurrentRoute(route) {
+    if (!route)
+        return {};
+    if ("value" in route)
+        return route.value;
+    return route;
+}
+function formatStandaloneNavigationTarget(target) {
+    const search = formatQuery(target.query);
+    return `${target.path}${search}`;
+}
+function assertAllowedNavigationTarget(target) {
+    if (isAllowedNavigationTarget(target))
+        return target;
+    throw new XpeRuntimeError("XPE_NAVIGATION_BLOCKED", "XPE 导航目标协议不被允许", { target });
+}
+function isAllowedNavigationTarget(target) {
+    const trimmed = target.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed.startsWith("/") ||
+        trimmed.startsWith("./") ||
+        trimmed.startsWith("../") ||
+        trimmed.startsWith("#") ||
+        trimmed.startsWith("?")) {
+        return true;
+    }
+    try {
+        const url = new URL(trimmed, "http://xpe.local");
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch (_) {
+        return false;
+    }
+}
+function formatQuery(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    Object.entries(query).forEach(([key, value]) => {
+        const values = Array.isArray(value) ? value : [value];
+        values.forEach((item) => {
+            if (item === null || item === undefined)
+                return;
+            params.append(key, String(item));
+        });
+    });
+    const queryString = params.toString();
+    return queryString ? `?${queryString}` : "";
+}

package/dist/child/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./app-client.js";
+export * from "./lifecycle.js";
+export * from "./mock-host.js";

package/dist/child/index.js

@@ -0,0 +1,3 @@
+export * from "./app-client.js";
+export * from "./lifecycle.js";
+export * from "./mock-host.js";

package/dist/child/lifecycle.d.ts

@@ -0,0 +1,12 @@
+import { type AppClient } from "./app-client.js";
+import { type AppContext, type RouteMode } from "../core/index.js";
+export type AppLifecycleMountResult = void | (() => void | Promise<void>);
+export type DefineAppLifecycleOptions = {
+    appCode?: string;
+    basename?: string;
+    routeMode?: RouteMode;
+    targetWindow?: Window;
+    defaultContainer?: string | Element;
+    mount: (container: Element, context: AppContext, client: AppClient) => AppLifecycleMountResult | Promise<AppLifecycleMountResult>;
+};
+export declare function defineAppLifecycle(options: DefineAppLifecycleOptions): void;

package/dist/child/lifecycle.js

@@ -0,0 +1,47 @@
+import { createAppClient } from "./app-client.js";
+import { getRuntimeWindow, XpeRuntimeError } from "../core/index.js";
+export function defineAppLifecycle(options) {
+    const runtimeWindow = getRuntimeWindow(options.targetWindow);
+    let cleanup;
+    const mount = async () => {
+        const clientOptions = {
+            appCode: options.appCode ?? runtimeWindow.__XPE_RUNTIME__?.appCode ?? "standalone",
+            basename: options.basename ?? runtimeWindow.__XPE_RUNTIME__?.basename ?? "/",
+            routeMode: options.routeMode ?? runtimeWindow.__XPE_RUNTIME__?.routeMode,
+            targetWindow: runtimeWindow,
+        };
+        const appClient = createAppClient(clientOptions);
+        const container = resolveContainer(options.defaultContainer, runtimeWindow.__XPE__);
+        cleanup = await options.mount(container, appClient.getContext(), appClient);
+    };
+    const unmount = async () => {
+        if (typeof cleanup === "function") {
+            await cleanup();
+            cleanup = undefined;
+        }
+        // 卸载后清除挂载全局，避免闭包（cleanup/client/container）随 window 长期保活，
+        // 也防止宿主在 teardown 后重读 __XPE_MOUNT__ 拿到 stale 挂载函数。delete 而非赋
+        // undefined，与 clearRuntimeBridge 一致，彻底断开属性引用。
+        delete runtimeWindow.__XPE_MOUNT__;
+        delete runtimeWindow.__XPE_UNMOUNT__;
+    };
+    if (runtimeWindow.__XPE_RUNTIME__) {
+        runtimeWindow.__XPE_MOUNT__ = mount;
+        runtimeWindow.__XPE_UNMOUNT__ = unmount;
+        return;
+    }
+    void mount();
+}
+function resolveContainer(container, bridge) {
+    if (container instanceof Element)
+        return container;
+    const selector = container ?? "#app";
+    const element = bridge?.resolveContainer?.(selector) ?? document.querySelector(selector);
+    if (!element) {
+        // 与 dev-shell 统一使用 typed error，容器缺失在宿主与子应用两侧是同一种失败。
+        throw new XpeRuntimeError("XPE_CONTAINER_MISSING", `XPE 子应用挂载容器不存在：${selector}`, {
+            selector,
+        });
+    }
+    return element;
+}

package/dist/child/mock-host.d.ts

@@ -0,0 +1,8 @@
+import { type AppBridge, type AppContext, type RuntimeInfo } from "../core/index.js";
+export type MockHostOptions = {
+    context: AppContext;
+    runtime?: Partial<RuntimeInfo>;
+};
+export declare function createMockHost(options: MockHostOptions): AppBridge & {
+    runtime: RuntimeInfo;
+};

package/dist/child/mock-host.js

@@ -0,0 +1,41 @@
+import { createEventHub } from "../core/index.js";
+export function createMockHost(options) {
+    let currentContext = options.context;
+    const contextEvents = createEventHub();
+    const appEvents = createEventHub();
+    const runtime = {
+        poweredByXpe: true,
+        appCode: currentContext.appCode,
+        // 与真实 host 的 getRuntimeName 对齐（appCode 原样），避免 dev 与 prod 下
+        // runtime.name 不一致，导致按 name 键的实例复用行为分叉。
+        name: currentContext.appCode,
+        basename: currentContext.basePath,
+        routeMode: "hash",
+        ...options.runtime,
+    };
+    return {
+        runtime,
+        get context() {
+            return currentContext;
+        },
+        getContext() {
+            return currentContext;
+        },
+        setContext(nextContext) {
+            currentContext = nextContext;
+            contextEvents.emit("context-change", nextContext);
+        },
+        onContextChange(handler) {
+            return contextEvents.on("context-change", handler);
+        },
+        emit(eventName, payload) {
+            appEvents.emit(eventName, payload);
+        },
+        on(eventName, handler) {
+            return appEvents.on(eventName, handler);
+        },
+        off(eventName, handler) {
+            appEvents.off(eventName, handler);
+        },
+    };
+}

package/dist/core/bridge.d.ts

@@ -0,0 +1,28 @@
+import type { AppContext, AppEventHandler, AppNavigationTarget, HostNavigationTarget, RuntimeInfo, Unsubscribe } from "./types.js";
+export type AppBridge = {
+    context?: AppContext;
+    getContext?: () => AppContext | undefined;
+    setContext?: (context: AppContext) => void;
+    onContextChange?: (handler: AppEventHandler<AppContext>) => Unsubscribe;
+    emit?: <TPayload = unknown>(eventName: string, payload: TPayload) => void;
+    on?: <TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>) => Unsubscribe;
+    off?: <TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>) => void;
+    navigate?: (target: string | AppNavigationTarget) => void;
+    navigateHost?: (target: string | HostNavigationTarget) => void;
+    reportRouteChange?: (path: string) => void;
+    syncRoute?: (path: string) => void;
+    mount?: () => void | Promise<void>;
+    resolveContainer?: (selector?: string) => Element | null;
+};
+export type XpeRuntimeWindow = Window & typeof globalThis & {
+    __XPE_RUNTIME__?: RuntimeInfo;
+    __XPE__?: AppBridge;
+    __XPE_MOUNT__?: () => void | Promise<void>;
+    __XPE_UNMOUNT__?: () => void | Promise<void>;
+};
+export declare function getRuntimeWindow(targetWindow?: Window): XpeRuntimeWindow;
+export declare function installRuntimeBridge(targetWindow: Window, options: {
+    runtime: RuntimeInfo;
+    bridge?: AppBridge;
+}): void;
+export declare function clearRuntimeBridge(targetWindow: Window): void;

package/dist/core/bridge.js

@@ -0,0 +1,19 @@
+export function getRuntimeWindow(targetWindow = window) {
+    return targetWindow;
+}
+export function installRuntimeBridge(targetWindow, options) {
+    const runtimeWindow = getRuntimeWindow(targetWindow);
+    runtimeWindow.__XPE_RUNTIME__ = options.runtime;
+    if (options.bridge) {
+        runtimeWindow.__XPE__ = options.bridge;
+    }
+}
+export function clearRuntimeBridge(targetWindow) {
+    const runtimeWindow = getRuntimeWindow(targetWindow);
+    // 用 delete 真正移除属性，而非赋 undefined：后者会在 window 上留下持有 undefined 的
+    // 自有属性，`in` 探测与 ownKeys 仍会命中，且无法回收闭包引用；delete 彻底断开。
+    delete runtimeWindow.__XPE_RUNTIME__;
+    delete runtimeWindow.__XPE__;
+    delete runtimeWindow.__XPE_MOUNT__;
+    delete runtimeWindow.__XPE_UNMOUNT__;
+}

package/dist/core/events.d.ts

@@ -0,0 +1,13 @@
+import type { AppEventHandler, Unsubscribe } from "./types.js";
+import { XpeRuntimeError } from "./types.js";
+export declare const XPE_ROUTE_CHANGE_EVENT = "xpe:route-change";
+export type EventMap = Map<string, Set<AppEventHandler>>;
+export type CreateEventHubOptions = {
+    onError?: (error: XpeRuntimeError) => void;
+};
+export declare function createEventHub(options?: CreateEventHubOptions): {
+    on: <TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>) => Unsubscribe;
+    off: <TPayload = unknown>(eventName: string, handler: AppEventHandler<TPayload>) => void;
+    emit: <TPayload = unknown>(eventName: string, payload: TPayload) => void;
+    clear: () => void;
+};

package/dist/core/events.js

@@ -0,0 +1,56 @@
+import { XpeRuntimeError } from "./types.js";
+export const XPE_ROUTE_CHANGE_EVENT = "xpe:route-change";
+export function createEventHub(options = {}) {
+    const events = new Map();
+    const { onError } = options;
+    function on(eventName, handler) {
+        const handlers = events.get(eventName) ?? new Set();
+        handlers.add(handler);
+        events.set(eventName, handlers);
+        return () => {
+            off(eventName, handler);
+        };
+    }
+    function off(eventName, handler) {
+        const handlers = events.get(eventName);
+        if (!handlers)
+            return;
+        handlers.delete(handler);
+        if (handlers.size === 0)
+            events.delete(eventName);
+    }
+    function emit(eventName, payload) {
+        const handlers = events.get(eventName);
+        if (!handlers)
+            return;
+        // 先快照再派发：handler 内部 on/off 会改动原 Set，迭代期增删会漏发或重复发；
+        // 同时逐个 try/catch，单个 handler 抛错不阻断其余订阅者，错误包装为 XPE_EVENT_FAILED
+        // 交由 onError，未提供时落到 console.error，避免静默吞掉。
+        for (const handler of [...handlers]) {
+            try {
+                handler(payload);
+            }
+            catch (error) {
+                const wrapped = new XpeRuntimeError("XPE_EVENT_FAILED", `XPE 事件处理器执行失败：${eventName}`, {
+                    eventName,
+                    cause: error,
+                });
+                if (onError) {
+                    onError(wrapped);
+                }
+                else {
+                    console.error(wrapped);
+                }
+            }
+        }
+    }
+    function clear() {
+        events.clear();
+    }
+    return {
+        on,
+        off,
+        emit,
+        clear,
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./bridge.js";
+export * from "./events.js";
+export * from "./types.js";

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export * from "./bridge.js";
+export * from "./events.js";
+export * from "./types.js";

package/dist/core/types.d.ts

@@ -0,0 +1,102 @@
+export type RuntimeMode = "xpe";
+export type RouteMode = "hash" | "history";
+export type AccessStatus = "enterable" | "no_permission" | "not_opened" | "expired";
+export type RuntimeCredentials = "include" | "omit";
+export type MenuNodeType = "directory" | "menu" | "action";
+export type MenuNode = {
+    id: string;
+    appCode: string;
+    parentId: string | null;
+    name: string;
+    path: string;
+    component?: string | null;
+    icon: string | null;
+    permissionCode: string | null;
+    type?: MenuNodeType;
+    visible?: boolean;
+    children: MenuNode[];
+};
+export type RemoteRuntimeConfig = {
+    mode?: RuntimeMode;
+    name?: string;
+    url: string;
+    basename?: string;
+    routeMode?: RouteMode;
+    alive?: boolean;
+    sync?: boolean;
+    credentials?: RuntimeCredentials;
+    degradeToExternalLink?: boolean;
+};
+export type AppManifest = {
+    appCode: string;
+    appName: string;
+    shortName?: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    basePath: string;
+    entryPath?: string;
+    runtimeMode?: "xpe";
+    runtime: RemoteRuntimeConfig;
+    menus?: MenuNode[];
+    permissions?: string[];
+    version?: string;
+};
+export type CurrentUser = {
+    memberId: string;
+    userId: string;
+    realName: string;
+    phone: string;
+};
+export type CurrentTenant = {
+    tenantId: string;
+    tenantCode: string;
+    tenantName: string;
+};
+export type CurrentOrganization = {
+    orgId: string;
+    orgPath: string | null;
+} | null;
+export type AppContext = {
+    appCode: string;
+    appName: string;
+    description?: string;
+    basePath: string;
+    entryPath: string;
+    defaultPath: string;
+    accessStatus: AccessStatus;
+    reason?: string;
+    currentUser: CurrentUser;
+    currentTenant: CurrentTenant;
+    currentOrganization: CurrentOrganization;
+    menus: MenuNode[];
+    permissions: string[];
+};
+export type RuntimeInfo = {
+    poweredByXpe: true;
+    appCode: string;
+    name: string;
+    basename: string;
+    routeMode: RouteMode;
+};
+export type RuntimeErrorCode = "XPE_APP_NOT_REGISTERED" | "XPE_APP_NOT_ENTERABLE" | "XPE_CONTEXT_MISSING" | "XPE_CONTAINER_MISSING" | "XPE_NAVIGATION_BLOCKED" | "XPE_RUNTIME_LOAD_FAILED" | "XPE_LIFECYCLE_FAILED" | "XPE_EVENT_FAILED";
+export type RuntimeErrorDetails = Record<string, unknown>;
+export type RouteQueryValue = string | number | boolean | null | undefined;
+export type AppNavigationTarget = {
+    appCode?: string;
+    path: string;
+    query?: Record<string, RouteQueryValue | RouteQueryValue[]>;
+    replace?: boolean;
+};
+export type HostNavigationTarget = {
+    path: string;
+    query?: Record<string, RouteQueryValue | RouteQueryValue[]>;
+    replace?: boolean;
+};
+export declare class XpeRuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+    readonly details?: RuntimeErrorDetails;
+    constructor(code: RuntimeErrorCode, message: string, details?: RuntimeErrorDetails);
+}
+export type AppEventHandler<TPayload = unknown> = (payload: TPayload) => void;
+export type Unsubscribe = () => void;

package/dist/core/types.js

@@ -0,0 +1,20 @@
+export class XpeRuntimeError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "XpeRuntimeError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/dev-shell/index.d.ts

@@ -0,0 +1,26 @@
+import { type AppBridge, type AppContext, type RuntimeInfo } from "../core/index.js";
+export type DevShellOptions = {
+    context: AppContext;
+    runtime?: Partial<RuntimeInfo>;
+    mountSelector?: string;
+    targetWindow?: Window;
+};
+export type DevShell = {
+    bridge: AppBridge & {
+        runtime: RuntimeInfo;
+    };
+    runtime: RuntimeInfo;
+    /**
+     * dev-shell 解析到的展示用容器。惰性解析：仅在访问时按 mountSelector 查询，
+     * 构造 createDevShell 时不再急切要求 DOM 就绪。实际挂载仍由子应用自身的
+     * defineAppLifecycle.resolveContainer 负责（默认 #app 或 app 的 defaultContainer），
+     * 二者不一致时以子应用的 defaultContainer 为准。
+     */
+    readonly container: Element | null;
+    install(): void;
+    mount(): Promise<void>;
+    unmount(): Promise<void>;
+    updateContext(context: AppContext): void;
+    destroy(): Promise<void>;
+};
+export declare function createDevShell(options: DevShellOptions): DevShell;

package/dist/dev-shell/index.js

@@ -0,0 +1,56 @@
+import { createMockHost } from "../child/index.js";
+import { clearRuntimeBridge, getRuntimeWindow, installRuntimeBridge, XpeRuntimeError, } from "../core/index.js";
+export function createDevShell(options) {
+    const targetWindow = options.targetWindow ?? window;
+    const runtimeWindow = getRuntimeWindow(targetWindow);
+    const bridge = createMockHost({
+        context: options.context,
+        runtime: options.runtime,
+    });
+    function install() {
+        installRuntimeBridge(runtimeWindow, {
+            runtime: bridge.runtime,
+            bridge,
+        });
+    }
+    async function mount() {
+        install();
+        if (runtimeWindow.__XPE_MOUNT__) {
+            await runtimeWindow.__XPE_MOUNT__();
+        }
+    }
+    async function unmount() {
+        if (runtimeWindow.__XPE_UNMOUNT__) {
+            await runtimeWindow.__XPE_UNMOUNT__();
+        }
+    }
+    async function destroy() {
+        await unmount();
+        clearRuntimeBridge(runtimeWindow);
+    }
+    return {
+        bridge,
+        runtime: bridge.runtime,
+        // 惰性解析：仅在访问 container 时才查询 DOM。避免 createDevShell 构造期
+        // 就硬要求容器存在（实际挂载走 child 的 __XPE_MOUNT__ + 自身 resolveContainer）。
+        get container() {
+            return resolveContainer(targetWindow, options.mountSelector);
+        },
+        install,
+        mount,
+        unmount,
+        updateContext(context) {
+            bridge.setContext?.(context);
+        },
+        destroy,
+    };
+}
+function resolveContainer(targetWindow, selector = "#app") {
+    const container = targetWindow.document.querySelector(selector);
+    if (!container) {
+        throw new XpeRuntimeError("XPE_CONTAINER_MISSING", "XPE dev shell 挂载容器不存在", {
+            selector,
+        });
+    }
+    return container;
+}