web-extend-plugin-vue2 0.3.0 → 0.3.1

package/dist/index.mjs

@@ -1,23 +1,15 @@
 import Vue from 'vue';
 
 /**
- * 对外配置单一入口：`resolveRuntimeOptions` / 文档 / 其它模块的默认值与环境键名均由此引用。
- * 宿主通过 `resolveRuntimeOptions(partial)` 覆盖的对象形状见 `defaultWebExtendPluginRuntime`。
+ * Public constants and runtime defaults consumed by resolveRuntimeOptions and
+ * other runtime modules.
  */
-/** 与 `package.json` 的 peer 下限一致；`npm run test:peer-min` / CI matrix 须与此保持同步 */
 const peerMinimumVersions = {
-    vue: '2.6.14',
-    vueRouter: '3.5.4'
+    vue: '2.6.0',
+    vueRouter: '3.5.0'
 };
-// ---------------------------------------------------------------------------
-// 协议与品牌（发布契约；与清单 `hostPluginApiVersion` 对齐 semver 主版本，一般不随宿主覆盖）
-// ---------------------------------------------------------------------------
 const HOST_PLUGIN_API_VERSION = '1.0.0';
-/** 控制台日志与首次引导横幅使用的短名称 */
 const RUNTIME_CONSOLE_LABEL = 'web-extend-plugin-vue2';
-// ---------------------------------------------------------------------------
-// 与 `build-env` / `resolveBundledEnv` 配套的键名（单一事实来源，便于检索与文档）
-// ---------------------------------------------------------------------------
 const webExtendPluginEnvKeys = {
     manifestBase: 'VITE_FRONTEND_PLUGIN_BASE',
     manifestListPath: 'VITE_WEB_PLUGIN_MANIFEST_PATH',
@@ -38,27 +30,14 @@ const webExtendPluginEnvKeys = {
     webPluginDevIds: 'VITE_WEB_PLUGIN_DEV_IDS',
     webPluginDevMap: 'VITE_WEB_PLUGIN_DEV_MAP',
     pluginsBootstrapSummary: 'VITE_PLUGINS_BOOTSTRAP_SUMMARY',
-    /** 清单路径备选：部分宿主单独使用 */
     manifestPathAlt: 'VUE_APP_WEB_PLUGIN_MANIFEST_PATH'
 };
-// ---------------------------------------------------------------------------
-// `manifestMode` 未配置且环境未指定时的默认值
-// ---------------------------------------------------------------------------
 const defaultManifestMode = 'api';
-// ---------------------------------------------------------------------------
-// `manifest-fetch-composer` 中间件默认（中间件 options 可逐项覆盖）
-// ---------------------------------------------------------------------------
 const defaultManifestFetchCache = {
     storageKeyPrefix: 'wep.manifestFetch.v1',
     maxEntries: 50
 };
-// ---------------------------------------------------------------------------
-// 路由合成名前缀（`createHostApi` 为无 name 的路由生成 `__wep_${pluginId}_${seq}`）
-// ---------------------------------------------------------------------------
 const routeSynthNamePrefix = '__wep_';
-// ---------------------------------------------------------------------------
-// 宿主可通过 `resolveRuntimeOptions` 覆盖的运行时默认值（与 README / index.d.ts 描述一致）
-// ---------------------------------------------------------------------------
 const defaultWebExtendPluginRuntime = {
     manifestBase: '/fp-api',
     manifestListPath: '/api/frontend-plugins',
@@ -70,11 +49,7 @@ const defaultWebExtendPluginRuntime = {
     defaultImplicitDevPluginIds: [],
     allowedScriptHosts: ['localhost', '127.0.0.1', '::1'],
     bridgeAllowedPathPrefixes: ['/api/'],
-    /** 与 `hostLayoutComponent` 同时使用时默认父路由 name */
-    pluginRoutesParentName: '__wepPluginHost',
-    /** 插件壳路径（与菜单、ensurePluginHostRoute 一致） */
     pluginMountPath: '/plugin',
-    /** `manifestMode=api` 且开发环境下，API 失败或 plugins 为空时尝试的静态 JSON（可放于 `public/web-plugins/`） */
     devFallbackStaticManifestUrl: '/web-plugins/plugins.manifest.json'
 };
 
@@ -411,6 +386,9 @@ function resolveRuntimeOptions$1(user = {}) {
         ...(typeof user.adaptRouteDeclarations === 'function'
             ? { adaptRouteDeclarations: user.adaptRouteDeclarations }
             : {}),
+        ...(typeof user.onPluginRoutesContributed === 'function'
+            ? { onPluginRoutesContributed: user.onPluginRoutesContributed }
+            : {}),
         ...(user.hostContext !== undefined &&
             user.hostContext !== null &&
             typeof user.hostContext === 'object' &&
@@ -3202,7 +3180,7 @@ var semverExports = requireSemver();
 var semver = /*@__PURE__*/getDefaultExportFromCjs(semverExports);
 
 /**
- * 引导时注入的 router 引用，供 disposeWebPlugin 按插件批量 removeRoute。
+ * 引导时注入的 router 引用，供 disposeWebPlugin 卸载插件动态路由。
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let bootstrapRouter;
@@ -3216,6 +3194,206 @@ function getPluginBootstrapRouter() {
     return bootstrapRouter;
 }
 
+/**
+ * 记录各插件通过 registerRoutes 挂到 router 上的顶层路由，
+ * 优先使用官方 `addRoute()` 返回的 disposer 做卸载；仅在 disposer 不可用时回退到 name。
+ */
+const pluginIdToTopRoutes = new Map();
+function recordPluginTopRoutes(pluginId, routes) {
+    if (!pluginId || routes.length === 0) {
+        return;
+    }
+    const normalized = routes.filter((route) => route && route.name);
+    if (normalized.length === 0) {
+        return;
+    }
+    const cur = pluginIdToTopRoutes.get(pluginId) || [];
+    pluginIdToTopRoutes.set(pluginId, cur.concat(normalized));
+}
+function tryRemoveRouteByName(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+router, pluginId, name) {
+    if (!router || typeof router.removeRoute !== 'function') {
+        console.warn('[wep] route disposer unavailable，且 router.removeRoute 不可用，动态路由可能残留', pluginId, name);
+        return;
+    }
+    try {
+        router.removeRoute(name);
+    }
+    catch (e) {
+        console.warn('[wep] removeRoute fallback failed', name, e);
+    }
+}
+/**
+ * 从 matcher 移除该插件登记过的顶层路由（含其子树）。
+ * 优先走 `router.addRoute()` 返回的 disposer；仅在 disposer 不可用时回退 `router.removeRoute(name)`。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function removeRegisteredRoutesForPlugin(router, pluginId) {
+    const routes = pluginIdToTopRoutes.get(pluginId);
+    if (!routes || routes.length === 0) {
+        return;
+    }
+    for (let i = routes.length - 1; i >= 0; i--) {
+        const route = routes[i];
+        if (typeof route.dispose === 'function') {
+            try {
+                route.dispose();
+                continue;
+            }
+            catch (e) {
+                console.warn('[wep] route disposer failed', route.name, e);
+            }
+        }
+        tryRemoveRouteByName(router, pluginId, route.name);
+    }
+    pluginIdToTopRoutes.delete(pluginId);
+}
+/** 调试或宿主高级场景：查询已登记 name（勿依赖顺序语义） */
+function getRegisteredTopRouteNamesForPlugin(pluginId) {
+    return (pluginIdToTopRoutes.get(pluginId) || []).map((route) => route.name);
+}
+
+/**
+ * 宿主侧响应式注册表：扩展点槽位（供布局与 `ExtensionPoint` 消费）。
+ * 菜单/侧栏树完全由宿主基于路由快照自行映射，框架不维护平行菜单列表。
+ */
+const registries = Vue.observable({
+    slots: {},
+    slotRevision: 0
+});
+
+/**
+ * 按插件 id 收集 `onTeardown` 回调，供 `disposeWebPlugin` 统一执行。
+ */
+const _byPlugin = new Map();
+function registerPluginTeardown(pluginId, fn) {
+    if (typeof fn !== 'function') {
+        return;
+    }
+    let list = _byPlugin.get(pluginId);
+    if (!list) {
+        list = [];
+        _byPlugin.set(pluginId, list);
+    }
+    list.push(fn);
+}
+function runPluginTeardowns(pluginId) {
+    const list = _byPlugin.get(pluginId);
+    if (!list) {
+        return;
+    }
+    _byPlugin.delete(pluginId);
+    for (const fn of list) {
+        try {
+            fn();
+        }
+        catch (e) {
+            console.warn('[wep] teardown failed', pluginId, e);
+        }
+    }
+}
+
+/**
+ * 动态加载脚本（去重与并发合并）。
+ */
+const loadScriptMemo = new Map();
+function markScriptOwnership(script, pluginId) {
+    if (pluginId) {
+        script.setAttribute('data-plugin-asset', pluginId);
+    }
+}
+function clearLoadedScriptMemo(src) {
+    if (typeof src === 'string' && src) {
+        loadScriptMemo.delete(src);
+        return;
+    }
+    loadScriptMemo.clear();
+}
+function loadScript(src, pluginId) {
+    if (typeof document === 'undefined') {
+        return Promise.reject(new Error('loadScript: no document'));
+    }
+    if (loadScriptMemo.has(src)) {
+        return loadScriptMemo.get(src);
+    }
+    const p = new Promise((resolve, reject) => {
+        const scripts = document.getElementsByTagName('script');
+        for (let i = 0; i < scripts.length; i++) {
+            const el = scripts[i];
+            if (el.src === src) {
+                markScriptOwnership(el, pluginId);
+                if (el.getAttribute('data-wep-loaded') === 'true') {
+                    resolve();
+                    return;
+                }
+                el.addEventListener('load', () => {
+                    el.setAttribute('data-wep-loaded', 'true');
+                    resolve();
+                }, { once: true });
+                el.addEventListener('error', () => reject(new Error('loadScript failed: ' + src)), { once: true });
+                return;
+            }
+        }
+        const s = document.createElement('script');
+        s.async = true;
+        s.src = src;
+        markScriptOwnership(s, pluginId);
+        s.onload = () => {
+            s.setAttribute('data-wep-loaded', 'true');
+            resolve();
+        };
+        s.onerror = () => reject(new Error('loadScript failed: ' + src));
+        document.head.appendChild(s);
+    });
+    loadScriptMemo.set(src, p);
+    p.catch(() => loadScriptMemo.delete(src));
+    return p;
+}
+
+/**
+ * 卸载单个插件：执行 teardown、移除该插件登记的动态路由、清理注册表与 activator、移除带 `data-plugin-asset` 的 DOM。
+ * 优先使用 `addRoute()` 返回的 disposer；必要时回退 `router.removeRoute(name)`。
+ */
+function disposeWebPlugin(pluginId) {
+    if (!pluginId || typeof pluginId !== 'string') {
+        return;
+    }
+    runPluginTeardowns(pluginId);
+    removeRegisteredRoutesForPlugin(getPluginBootstrapRouter(), pluginId);
+    const slots = registries.slots;
+    for (const pointId of Object.keys(slots)) {
+        const list = slots[pointId];
+        if (!Array.isArray(list)) {
+            continue;
+        }
+        const next = list.filter((x) => x.pluginId !== pluginId);
+        if (next.length === 0) {
+            Vue.delete(slots, pointId);
+        }
+        else if (next.length !== list.length) {
+            Vue.set(slots, pointId, next);
+        }
+    }
+    registries.slotRevision++;
+    if (typeof window !== 'undefined' && window.__PLUGIN_ACTIVATORS__) {
+        delete window.__PLUGIN_ACTIVATORS__[pluginId];
+    }
+    if (typeof document !== 'undefined') {
+        document.querySelectorAll('[data-plugin-asset]').forEach((el) => {
+            if (el.getAttribute('data-plugin-asset') === pluginId) {
+                if (el.tagName === 'SCRIPT') {
+                    const src = el.src;
+                    if (src) {
+                        clearLoadedScriptMemo(src);
+                    }
+                }
+                el.remove();
+            }
+        });
+    }
+}
+
 /**
  * 开发模式插件 URL 映射（显式 JSON + 隐式 dev 探测）。
  */
@@ -3378,49 +3556,6 @@ function startPluginDevSseForMap(devMap, isDev, hostSet, ssePath) {
     }
 }
 
-/**
- * 动态加载脚本（去重与并发合并）。
- */
-const loadScriptMemo = new Map();
-function loadScript(src) {
-    if (typeof document === 'undefined') {
-        return Promise.reject(new Error('loadScript: no document'));
-    }
-    if (loadScriptMemo.has(src)) {
-        return loadScriptMemo.get(src);
-    }
-    const p = new Promise((resolve, reject) => {
-        const scripts = document.getElementsByTagName('script');
-        for (let i = 0; i < scripts.length; i++) {
-            const el = scripts[i];
-            if (el.src === src) {
-                if (el.getAttribute('data-wep-loaded') === 'true') {
-                    resolve();
-                    return;
-                }
-                el.addEventListener('load', () => {
-                    el.setAttribute('data-wep-loaded', 'true');
-                    resolve();
-                }, { once: true });
-                el.addEventListener('error', () => reject(new Error('loadScript failed: ' + src)), { once: true });
-                return;
-            }
-        }
-        const s = document.createElement('script');
-        s.async = true;
-        s.src = src;
-        s.onload = () => {
-            s.setAttribute('data-wep-loaded', 'true');
-            resolve();
-        };
-        s.onerror = () => reject(new Error('loadScript failed: ' + src));
-        document.head.appendChild(s);
-    });
-    loadScriptMemo.set(src, p);
-    p.catch(() => loadScriptMemo.delete(src));
-    return p;
-}
-
 let _printed = false;
 /** 在首次引导插件时打印一行运行时标识（非大块 ASCII art）。 */
 function printRuntimeBannerOnce() {
@@ -3569,6 +3704,29 @@ function resolveStaticManifestUrlForFetch(url, origin) {
     }
 }
 
+/**
+ * 记录当前已成功激活的插件 id，供宿主做只读观测。
+ */
+const activatedPluginIds = new Set();
+function clearActivatedPluginIds() {
+    activatedPluginIds.clear();
+}
+function markPluginActivated(pluginId) {
+    if (!pluginId) {
+        return;
+    }
+    activatedPluginIds.add(pluginId);
+}
+function markPluginDeactivated(pluginId) {
+    if (!pluginId) {
+        return;
+    }
+    activatedPluginIds.delete(pluginId);
+}
+function getActivatedPluginIds$1() {
+    return [...activatedPluginIds];
+}
+
 /**
  * 拉取插件清单、加载入口脚本并调用各插件 `activator`。
  */
@@ -3604,7 +3762,7 @@ async function loadPluginEntry(p, entryUrl, devMap, hostSet) {
         catch (e) {
             console.warn('[wep] dev import failed, trying manifest entryUrl', p.id, e);
             if (entryUrl && isScriptHostAllowed(entryUrl, hostSet)) {
-                await loadScript(entryUrl);
+                await loadScript(entryUrl, p.id);
             }
             return;
         }
@@ -3614,7 +3772,40 @@ async function loadPluginEntry(p, entryUrl, devMap, hostSet) {
         console.warn('[wep] skip (entryUrl not allowed)', p.id, entryUrl);
         return;
     }
-    await loadScript(entryUrl);
+    await loadScript(entryUrl, p.id);
+}
+function coercePriority(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function sortByPriority(plugins) {
+    return plugins
+        .map((entry, index) => ({
+        entry,
+        priority: coercePriority(entry.priority),
+        index
+    }))
+        .sort((a, b) => {
+        const aHas = a.priority !== null;
+        const bHas = b.priority !== null;
+        if (!aHas && !bHas) {
+            return a.index - b.index;
+        }
+        if (!aHas) {
+            return 1;
+        }
+        if (!bHas) {
+            return -1;
+        }
+        if (a.priority !== b.priority) {
+            return a.priority - b.priority;
+        }
+        return a.index - b.index;
+    })
+        .map((decorated) => decorated.entry);
 }
 async function bootstrapPlugins$1(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -3626,6 +3817,7 @@ createHostApiFactory, runtimeOptions) {
         return;
     }
     printRuntimeBannerOnce();
+    clearActivatedPluginIds();
     const opts = resolveRuntimeOptions$1(runtimeOptions || {});
     setPluginBootstrapRouter(router);
     ensurePluginHostRoute$1(router, opts);
@@ -3704,6 +3896,9 @@ createHostApiFactory, runtimeOptions) {
             : {}),
         ...(typeof opts.adaptRouteDeclarations === 'function'
             ? { adaptRouteDeclarations: opts.adaptRouteDeclarations }
+            : {}),
+        ...(typeof opts.onPluginRoutesContributed === 'function'
+            ? { onPluginRoutesContributed: opts.onPluginRoutesContributed }
             : {})
     };
     if (!manifestResult.ok) {
@@ -3732,22 +3927,30 @@ createHostApiFactory, runtimeOptions) {
         const maj = coerced ? coerced.major : 0;
         const range = `^${maj}.0.0`;
         if (!semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
-            console.warn('[wep] host API version mismatch', {
+            console.warn('[wep] manifest host API version mismatch; skip bootstrap', {
                 host: HOST_PLUGIN_API_VERSION,
                 manifest: apiVer
             });
+            if (shouldShowBootstrapSummary(opts)) {
+                console.info('[wep] bootstrap_summary', {
+                    ok: false,
+                    reason: 'manifest_host_api_version_mismatch'
+                });
+            }
+            return;
         }
     }
     window.__PLUGIN_ACTIVATORS__ = window.__PLUGIN_ACTIVATORS__ || {};
-    const plugins = data.plugins || [];
+    const originalPlugins = data.plugins || [];
+    const plugins = sortByPriority(originalPlugins);
     if (plugins.length === 0) {
         const hint = isStatic ? 'check static JSON file and plugins[]' : 'check backend and URL';
         console.info('[wep] empty plugin manifest — ' + hint, manifestUrlUsed);
     }
     const summary = {
-        manifestCount: plugins.length,
+        manifestCount: originalPlugins.length,
         activated: 0,
-        skipEngines: 0,
+        skipApiVersion: 0,
         skipLoad: 0,
         skipNoActivator: 0,
         activateFail: 0
@@ -3755,8 +3958,10 @@ createHostApiFactory, runtimeOptions) {
     for (const p of plugins) {
         const range = p.engines && p.engines.host;
         if (range && !semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
-            console.warn('[wep] skip plugin (engines.host)', p.id, range);
-            summary.skipEngines++;
+            console.warn('[wep] skip plugin (engines.host)', p.id, range, {
+                host: HOST_PLUGIN_API_VERSION
+            });
+            summary.skipApiVersion++;
             continue;
         }
         const entryUrl = p.entryUrl;
@@ -3792,6 +3997,11 @@ createHostApiFactory, runtimeOptions) {
         const hostApi = createHostApiFactory(p.id, router, hostKit);
         try {
             await Promise.resolve(activator(hostApi, { pluginRecord }));
+            markPluginActivated(p.id);
+            const teardownCapableHostApi = hostApi;
+            if (typeof teardownCapableHostApi.onTeardown === 'function') {
+                teardownCapableHostApi.onTeardown(p.id, () => markPluginDeactivated(p.id));
+            }
             summary.activated++;
             if (typeof opts.onAfterPluginActivate === 'function') {
                 await Promise.resolve(opts.onAfterPluginActivate({
@@ -3804,6 +4014,12 @@ createHostApiFactory, runtimeOptions) {
         }
         catch (e) {
             console.error('[wep] activate failed', p.id, e);
+            try {
+                disposeWebPlugin(p.id);
+            }
+            catch (disposeErr) {
+                console.warn('[wep] rollback failed after activation error', p.id, disposeErr);
+            }
             summary.activateFail++;
             if (typeof opts.onPluginActivateError === 'function') {
                 try {
@@ -3834,6 +4050,7 @@ var pluginRuntime = /*#__PURE__*/Object.freeze({
     bootstrapPlugins: bootstrapPlugins$1,
     defaultFetchWebPluginManifest: defaultFetchWebPluginManifest$1,
     ensurePluginHostRoute: ensurePluginHostRoute$1,
+    getActivatedPluginIds: getActivatedPluginIds$1,
     resolveRuntimeOptions: resolveRuntimeOptions$1
 });
 
@@ -3992,48 +4209,40 @@ var manifestComposer = /*#__PURE__*/Object.freeze({
 });
 
 /**
- * 宿主侧响应式注册表：扩展点槽位（供布局与 `ExtensionPoint` 消费）。
- * 菜单由宿主从路由 `meta` 推导（见 `buildMenuDescriptorsFromRoutes`），框架不维护平行菜单列表。
- */
-const registries = Vue.observable({
-    slots: {},
-    slotRevision: 0
-});
-
-/**
- * 按插件 id 收集 `onTeardown` 回调，供 `disposeWebPlugin` 统一执行。
+ * 插件访问后端的受控通道：`fetch` 仅允许落在配置的路径前缀下（默认 `/api/`），默认 `credentials: 'same-origin'`。
  */
-const _byPlugin = new Map();
-function registerPluginTeardown(pluginId, fn) {
-    if (typeof fn !== 'function') {
-        return;
+function normalizeBridgePath(input) {
+    if (typeof window === 'undefined') {
+        throw new Error('[wep:bridge] window is unavailable');
     }
-    let list = _byPlugin.get(pluginId);
-    if (!list) {
-        list = [];
-        _byPlugin.set(pluginId, list);
+    if (typeof input !== 'string' || !input.startsWith('/')) {
+        throw new Error('[wep:bridge] path must start with /');
     }
-    list.push(fn);
-}
-function runPluginTeardowns(pluginId) {
-    const list = _byPlugin.get(pluginId);
-    if (!list) {
-        return;
+    if (input.includes('\\')) {
+        throw new Error('[wep:bridge] path must not contain backslashes');
     }
-    _byPlugin.delete(pluginId);
-    for (const fn of list) {
+    const url = new URL(input, window.location.origin);
+    if (url.origin !== window.location.origin) {
+        throw new Error('[wep:bridge] cross-origin path is not allowed');
+    }
+    const normalized = url.pathname;
+    const decodedPath = (() => {
         try {
-            fn();
+            return decodeURIComponent(normalized);
         }
-        catch (e) {
-            console.warn('[wep] teardown failed', pluginId, e);
+        catch {
+            return normalized;
         }
-    }
+    })();
+    const hasTraversalSegment = decodedPath
+        .split('/')
+        .filter(Boolean)
+        .some((segment) => segment === '.' || segment === '..');
+    if (hasTraversalSegment) {
+        throw new Error('[wep:bridge] path traversal is not allowed');
+    }
+    return normalized + url.search;
 }
-
-/**
- * 插件访问后端的受控通道：`fetch` 仅允许落在配置的路径前缀下（默认 `/api/`），默认 `credentials: 'same-origin'`。
- */
 function createRequestBridge(config = {}) {
     const raw = Array.isArray(config.allowedPathPrefixes) && config.allowedPathPrefixes.length > 0
         ? config.allowedPathPrefixes
@@ -4041,14 +4250,13 @@ function createRequestBridge(config = {}) {
     const allowedPathPrefixes = raw.map((p) => ensureLeadingPath(p));
     return {
         async request(path, init = {}) {
-            if (typeof path !== 'string' || !path.startsWith('/')) {
-                throw new Error('[wep:bridge] path must start with /');
-            }
-            const allowed = allowedPathPrefixes.some((p) => path.startsWith(p));
+            const normalizedPath = normalizeBridgePath(path);
+            const pathnameOnly = normalizedPath.split('?')[0];
+            const allowed = allowedPathPrefixes.some((p) => pathnameOnly === p || pathnameOnly.startsWith(`${p.replace(/\/$/, '')}/`));
             if (!allowed) {
-                throw new Error('[wep:bridge] path not allowed: ' + path);
+                throw new Error('[wep:bridge] path not allowed: ' + normalizedPath);
             }
-            return fetch(path, {
+            return fetch(normalizedPath, {
                 credentials: 'same-origin',
                 ...init
             });
@@ -4057,51 +4265,83 @@ function createRequestBridge(config = {}) {
 }
 
 /**
- * 记录各插件通过 registerRoutes 挂到 router 上的顶层 route name，便于 dispose 时 removeRoute。
+ * 按插件记录已贡献路由的可序列化快照，避免宿主依赖 router 内部 matcher 形态。
  */
-const pluginIdToRouteNames = new Map();
-function recordPluginTopRouteNames(pluginId, names) {
-    if (!pluginId || names.length === 0) {
-        return;
+const contributedRoutesByPlugin = new Map();
+function sanitizeValue(value) {
+    if (value == null) {
+        return value;
     }
-    const cur = pluginIdToRouteNames.get(pluginId) || [];
-    pluginIdToRouteNames.set(pluginId, cur.concat(names));
-}
-/**
- * 从 matcher 移除该插件登记过的顶层路由（含其子树）。
- * 需 vue-router ≥3.5 的 removeRoute；否则静默跳过。
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function removeRegisteredRoutesForPlugin(router, pluginId) {
-    const names = pluginIdToRouteNames.get(pluginId);
-    if (!names || names.length === 0) {
-        return;
+    if (typeof value === 'function') {
+        return undefined;
     }
-    if (!router || typeof router.removeRoute !== 'function') {
-        console.warn('[wep] router.removeRoute 不可用，跳过动态路由卸载', pluginId);
-        pluginIdToRouteNames.delete(pluginId);
-        return;
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => sanitizeValue(item))
+            .filter((item) => item !== undefined);
     }
-    for (let i = names.length - 1; i >= 0; i--) {
-        try {
-            router.removeRoute(names[i]);
+    if (typeof value !== 'object') {
+        return value;
+    }
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (key === 'component' || key === 'components') {
+            continue;
         }
-        catch (e) {
-            console.warn('[wep] removeRoute failed', names[i], e);
+        const sanitized = sanitizeValue(raw);
+        if (sanitized !== undefined) {
+            out[key] = sanitized;
         }
     }
-    pluginIdToRouteNames.delete(pluginId);
+    return out;
 }
-/** 测试或宿主高级场景：查询已登记 name（勿依赖顺序语义） */
-function getRegisteredTopRouteNamesForPlugin(pluginId) {
-    return [...(pluginIdToRouteNames.get(pluginId) || [])];
+function sanitizeContributedRoutes(routes) {
+    return routes
+        .map((route) => sanitizeValue(route))
+        .filter((route) => !!route && typeof route === 'object');
+}
+function recordContributedRoutesForPlugin(pluginId, routes) {
+    const sanitized = sanitizeContributedRoutes(routes);
+    const current = contributedRoutesByPlugin.get(pluginId) || [];
+    const next = current.concat(sanitized);
+    contributedRoutesByPlugin.set(pluginId, next);
+    return next.map((route) => sanitizeValue(route));
+}
+function getContributedRoutesForPlugin(pluginId) {
+    const routes = contributedRoutesByPlugin.get(pluginId) || [];
+    return routes.map((route) => sanitizeValue(route));
+}
+function clearContributedRoutesForPlugin(pluginId) {
+    contributedRoutesByPlugin.delete(pluginId);
 }
 
 /**
- * 构造插件 `activator(hostApi)` 使用的宿主 API：路由、菜单、扩展点、资源与受控请求桥。
+ * 构造插件 `activator(hostApi)` 使用的宿主 API：路由、扩展点、资源与受控请求桥。
  */
 let slotItemKeySeq = 0;
 let routeSynthSeq = 0;
+function decorateRouteTreeWithPluginMeta(pluginId, route) {
+    const meta = route.meta && typeof route.meta === 'object' && !Array.isArray(route.meta)
+        ? route.meta
+        : {};
+    const wepMeta = meta.__wep && typeof meta.__wep === 'object' && !Array.isArray(meta.__wep)
+        ? meta.__wep
+        : {};
+    const nextChildren = Array.isArray(route.children)
+        ? route.children.map((child) => decorateRouteTreeWithPluginMeta(pluginId, child))
+        : route.children;
+    return {
+        ...route,
+        meta: {
+            ...meta,
+            __wep: {
+                ...wepMeta,
+                pluginId
+            }
+        },
+        ...(nextChildren ? { children: nextChildren } : {})
+    };
+}
 function analyzeRouteInputTree(nodes) {
     let hasDecl = false;
     let hasCfg = false;
@@ -4143,26 +4383,71 @@ function createHostApi(pluginId, router, hostKitOptions = {}) {
     const parentName = typeof hostKitOptions.pluginRoutesParentName === 'string'
         ? hostKitOptions.pluginRoutesParentName.trim()
         : '';
+    function rollbackRegisteredTopRoutes(routes) {
+        for (let i = routes.length - 1; i >= 0; i--) {
+            const route = routes[i];
+            if (typeof route.dispose === 'function') {
+                try {
+                    route.dispose();
+                    continue;
+                }
+                catch (e) {
+                    console.warn('[wep] rollback route disposer failed', route.name, e);
+                }
+            }
+            if (typeof router.removeRoute === 'function') {
+                try {
+                    router.removeRoute(route.name);
+                }
+                catch (e) {
+                    console.warn('[wep] rollback removeRoute failed', route.name, e);
+                }
+            }
+        }
+    }
     function applyInternalRegister(rawRouteConfigs) {
         const wrapped = rawRouteConfigs.map((r) => ({
-            ...r,
-            name: r.name || `${routeSynthNamePrefix}${pluginId}_${routeSynthSeq++}`,
-            meta: { ...(r.meta || {}), pluginId }
+            ...decorateRouteTreeWithPluginMeta(pluginId, r),
+            name: r.name || `${routeSynthNamePrefix}${pluginId}_${routeSynthSeq++}`
         }));
         if (typeof router.addRoute !== 'function') {
             throw new Error('[wep] vue-router 3.5+ 必需：请使用 router.addRoute（不再支持 addRoutes）');
         }
-        recordPluginTopRouteNames(pluginId, wrapped.map((r) => String(r.name)));
-        if (parentName) {
-            for (const r of wrapped) {
-                router.addRoute(parentName, r);
+        const registeredTopRoutes = [];
+        try {
+            if (parentName) {
+                for (const r of wrapped) {
+                    const dispose = router.addRoute(parentName, r);
+                    registeredTopRoutes.push({
+                        name: String(r.name),
+                        dispose: typeof dispose === 'function' ? dispose : undefined
+                    });
+                }
             }
-        }
-        else {
-            for (const r of wrapped) {
-                router.addRoute(r);
+            else {
+                for (const r of wrapped) {
+                    const dispose = router.addRoute(r);
+                    registeredTopRoutes.push({
+                        name: String(r.name),
+                        dispose: typeof dispose === 'function' ? dispose : undefined
+                    });
+                }
             }
         }
+        catch (e) {
+            rollbackRegisteredTopRoutes(registeredTopRoutes);
+            throw e;
+        }
+        recordPluginTopRoutes(pluginId, registeredTopRoutes);
+        const contributedRoutes = recordContributedRoutesForPlugin(pluginId, wrapped);
+        if (contributedRoutes.length > 0 && typeof hostKitOptions.onPluginRoutesContributed === 'function') {
+            hostKitOptions.onPluginRoutesContributed({
+                pluginId,
+                router,
+                routes: wrapped,
+                contributedRoutes
+            });
+        }
     }
     function injectStylesheet(href) {
         const link = document.createElement('link');
@@ -4185,6 +4470,9 @@ function createHostApi(pluginId, router, hostKitOptions = {}) {
     const hostContext = hostKitOptions.hostContext != null && typeof hostKitOptions.hostContext === 'object'
         ? hostKitOptions.hostContext
         : Object.freeze({});
+    registerPluginTeardown(pluginId, () => {
+        clearContributedRoutesForPlugin(pluginId);
+    });
     return {
         hostPluginApiVersion: HOST_PLUGIN_API_VERSION,
         /** 宿主注入的只读依赖（store、router、开放能力等），见 `resolveRuntimeOptions.hostContext` */
@@ -4265,6 +4553,7 @@ function createHostApi(pluginId, router, hostKitOptions = {}) {
         registerSanitizedHtmlSnippet() {
             throw new Error('registerSanitizedHtmlSnippet is not enabled');
         },
+        getContributedRoutes: () => getContributedRoutesForPlugin(pluginId),
         getBridge: () => bridge,
         onTeardown(_pluginId, fn) {
             if (typeof fn === 'function') {
@@ -4274,112 +4563,6 @@ function createHostApi(pluginId, router, hostKitOptions = {}) {
     };
 }
 
-/**
- * 卸载单个插件：执行 teardown、按登记 name 批量 removeRoute、清理注册表与 activator、移除带 `data-plugin-asset` 的 DOM。
- * 依赖 vue-router ≥3.5 的 removeRoute；引导时由 bootstrapPlugins 注入 router。
- */
-function disposeWebPlugin(pluginId) {
-    if (!pluginId || typeof pluginId !== 'string') {
-        return;
-    }
-    runPluginTeardowns(pluginId);
-    removeRegisteredRoutesForPlugin(getPluginBootstrapRouter(), pluginId);
-    const slots = registries.slots;
-    for (const pointId of Object.keys(slots)) {
-        const list = slots[pointId];
-        if (!Array.isArray(list)) {
-            continue;
-        }
-        const next = list.filter((x) => x.pluginId !== pluginId);
-        if (next.length === 0) {
-            Vue.delete(slots, pointId);
-        }
-        else if (next.length !== list.length) {
-            Vue.set(slots, pointId, next);
-        }
-    }
-    registries.slotRevision++;
-    if (typeof window !== 'undefined' && window.__PLUGIN_ACTIVATORS__) {
-        delete window.__PLUGIN_ACTIVATORS__[pluginId];
-    }
-    if (typeof document !== 'undefined') {
-        document.querySelectorAll('[data-plugin-asset]').forEach((el) => {
-            if (el.getAttribute('data-plugin-asset') === pluginId) {
-                el.remove();
-            }
-        });
-    }
-}
-
-/**
- * 从路由配置（含 meta）推导侧栏/目录用菜单描述，与 registerRoutes 入参同源。
- *
- * 约定：
- * - `meta.menu === false`：该节点及其子树不参与菜单
- * - 节点出现条件：`meta.title` 或 `meta.menuTitle` 非空字符串，或存在非空的子菜单列表
- * - `meta.order` 数字越小越靠前；缺省为 0
- * - 可选：`meta.icon`、`meta.permission`、`meta.hidden`、`meta.external`
- */
-function pickTitle(meta, route) {
-    if (typeof meta.menuTitle === 'string' && meta.menuTitle) {
-        return meta.menuTitle;
-    }
-    if (typeof meta.title === 'string' && meta.title) {
-        return meta.title;
-    }
-    if (route.name != null && String(route.name)) {
-        return String(route.name);
-    }
-    return String(route.path || '');
-}
-function sortDescriptors(items) {
-    items.sort((a, b) => a.order - b.order || a.path.localeCompare(b.path));
-    for (const x of items) {
-        if (x.children && x.children.length) {
-            sortDescriptors(x.children);
-        }
-    }
-}
-/**
- * 从插件侧 RouteConfig 树构建菜单描述（不含 component，便于并入宿主菜单 state）。
- */
-function buildMenuDescriptorsFromRoutes(routes, pluginId) {
-    const out = [];
-    function walk(route) {
-        const meta = (route.meta || {});
-        if (meta.menu === false) {
-            return null;
-        }
-        const chIn = Array.isArray(route.children) ? route.children : [];
-        const childMenus = chIn.map(walk).filter(Boolean);
-        const hasTitle = typeof meta.title === 'string' || typeof meta.menuTitle === 'string';
-        if (!hasTitle && childMenus.length === 0) {
-            return null;
-        }
-        const item = {
-            path: String(route.path || ''),
-            name: route.name,
-            title: pickTitle(meta, route),
-            order: meta.order != null ? Number(meta.order) : 0,
-            ...(pluginId ? { pluginId } : {}),
-            ...(meta.icon !== undefined ? { icon: meta.icon } : {}),
-            ...(meta.permission !== undefined ? { permission: meta.permission } : {}),
-            ...(meta.hidden === true ? { hidden: true } : {}),
-            ...(meta.external === true ? { external: true } : {}),
-            ...(childMenus.length ? { children: childMenus } : {})
-        };
-        return item;
-    }
-    for (const r of routes) {
-        const m = walk(r);
-        if (m) {
-            out.push(m);
-        }
-    }
-    sortDescriptors(out);
-    return out;
-}
-
 /**
  * 布局中的扩展点占位；插件通过 `hostApi.registerSlotComponents(pointId, ...)` 注入组件。
  * 样式由宿主全局 CSS 覆盖 `.extension-point` / `.plugin-point-error`。
@@ -4432,31 +4615,15 @@ var ExtensionPoint = Vue.extend({
     }
 });
 
-/**
- * 注册全局 `ExtensionPoint` 并异步拉取清单、激活插件。
- */
-/**
- * @param Vue Vue 构造函数
- * @param router vue-router 实例
- * @param options 传给 `resolveRuntimeOptions`；可含 `env` 以读取 `VITE_*`
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function installWebExtendPluginVue2(Vue, router, options) {
-    const opts = options || {};
-    const { env: injectedEnv, ...runtimeUser } = opts;
-    if (injectedEnv && typeof injectedEnv === 'object') {
-        setWebExtendPluginEnv(injectedEnv);
-    }
     if (Vue && ExtensionPoint) {
         Vue.component('ExtensionPoint', ExtensionPoint);
     }
-    const runtime = resolveRuntimeOptions$1(runtimeUser);
+    const runtime = resolveRuntimeOptions$1(options || {});
     return bootstrapPlugins$1(router, (id, r, kit) => createHostApi(id, r, kit || {}), runtime);
 }
 
-/**
- * Vue CLI + 统一 axios（如 RuoYi `utils/request`）场景的 `install` 预设。
- */
 function resolveManifestPathUnderApiBase(manifestUrl, apiBase) {
     const base = String(apiBase !== undefined
         ? apiBase
@@ -4466,18 +4633,13 @@ function resolveManifestPathUnderApiBase(manifestUrl, apiBase) {
     if (typeof window === 'undefined') {
         return '/api/frontend-plugins';
     }
-    const u = new URL(manifestUrl, window.location.origin);
-    let path = u.pathname + u.search;
+    const url = new URL(manifestUrl, window.location.origin);
+    let path = url.pathname + url.search;
     if (base && path.startsWith(base)) {
         path = path.slice(base.length) || '/';
     }
     return path;
 }
-/**
- * 常见 Java 清单路径：与 `VUE_APP_BASE_API` 拼接为 `${base}/frontend-plugins`。
- * 若后端使用 `/api/frontend-plugins` 段，请在 extra 中显式传入 `manifestListPath`。
- */
-const defaultVueCliJavaManifestListPath = '/frontend-plugins';
 function bridgePrefixesFromVueCliEnv() {
     const base = (typeof process !== 'undefined' && process.env && process.env.VUE_APP_BASE_API
         ? String(process.env.VUE_APP_BASE_API)
@@ -4498,13 +4660,10 @@ function createVueCliAxiosInstallOptions(deps, extra = {}) {
         ? String(extra.manifestBase).replace(/\/$/, '')
         : '';
     const stripBase = userBase || envBase;
-    const manifestMode = resolveManifestModeFromInputs(extraManifestMode);
-    const staticManifestUrl = resolveStaticManifestUrlFromInputs(extraStaticManifestUrl);
     const fetchManifestApi = async (ctx) => {
         try {
-            const url = resolveManifestPathUnderApiBase(ctx.manifestUrl, stripBase);
             const body = await request({
-                url,
+                url: resolveManifestPathUnderApiBase(ctx.manifestUrl, stripBase),
                 method: 'get'
             });
             const data = unwrapNestedManifestBody(body);
@@ -4517,17 +4676,18 @@ function createVueCliAxiosInstallOptions(deps, extra = {}) {
             }
             return { ok: true, data };
         }
-        catch (e) {
-            return { ok: false, error: e, data: null };
+        catch (error) {
+            return { ok: false, error, data: null };
         }
     };
-    const fetchManifestStatic = (ctx) => fetchStaticManifestViaHttp(ctx);
+    const manifestMode = resolveManifestModeFromInputs(extraManifestMode);
+    const staticManifestUrl = resolveStaticManifestUrlFromInputs(extraStaticManifestUrl);
     const fetchManifest = typeof userFetchManifest === 'function'
         ? userFetchManifest
         : manifestMode === 'static'
-            ? fetchManifestStatic
+            ? fetchStaticManifestViaHttp
             : fetchManifestApi;
-    const opts = {
+    const options = {
         manifestBase: stripBase || undefined,
         bridgeAllowedPathPrefixes: bridgePrefixesFromVueCliEnv(),
         manifestMode,
@@ -4538,106 +4698,14 @@ function createVueCliAxiosInstallOptions(deps, extra = {}) {
     const listPath = typeof process !== 'undefined' &&
         process.env &&
         process.env[webExtendPluginEnvKeys.manifestPathAlt];
-    if (listPath && opts.manifestListPath === undefined && extra.manifestListPath === undefined) {
-        opts.manifestListPath = String(process.env[webExtendPluginEnvKeys.manifestPathAlt]);
+    if (listPath && options.manifestListPath === undefined && extra.manifestListPath === undefined) {
+        options.manifestListPath = String(process.env[webExtendPluginEnvKeys.manifestPathAlt]);
     }
-    return opts;
-}
-/**
- * 少样板接入：`hostContext` 自动含 `router`（及可选 `store`）、`isDev` 与常见 `manifestListPath` 默认值。
- * 更多运行时字段仍可通过 `extra` 覆盖。
- */
-function createVueCliAxiosQuickInstallOptions(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-router, deps, extra = {}) {
-    const { request, hostLayoutComponent, store, hostContext: depHostContext } = deps;
-    const { hostContext: extraHostContext, isDev: extraIsDev, manifestListPath: extraListPath, ...restExtra } = extra;
-    const hostContext = {
-        router,
-        ...(store !== undefined ? { store } : {}),
-        ...(depHostContext && typeof depHostContext === 'object' ? depHostContext : {}),
-        ...(extraHostContext && typeof extraHostContext === 'object' ? extraHostContext : {})
-    };
-    const manifestListPath = extraListPath !== undefined && String(extraListPath).trim() !== ''
-        ? String(extraListPath)
-        : defaultVueCliJavaManifestListPath;
-    return createVueCliAxiosInstallOptions({ request }, {
-        hostLayoutComponent,
-        hostContext,
-        isDev: extraIsDev !== undefined ? Boolean(extraIsDev) : resolveBundledIsDev(),
-        manifestListPath,
-        ...restExtra
-    });
-}
-const presetVueCliAxios = Object.freeze({
-    id: 'vue-cli-axios',
-    description: 'Vue CLI + axios request for API manifest; optional manifestMode=static uses fetch',
-    createInstallOptions: createVueCliAxiosInstallOptions,
-    createQuickInstallOptions: createVueCliAxiosQuickInstallOptions,
-    defaultJavaManifestListPath: defaultVueCliJavaManifestListPath,
-    manifestPathForApiBase: resolveManifestPathUnderApiBase,
-    unwrapManifestBody: unwrapNestedManifestBody
-});
-
-/**
- * Vue CLI + axios 场景的一键安装：合并 hostContext、默认清单路径与 IIFE 全局 Vue。
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function installVueCliAxiosWebPlugins(Vue, router, deps, extra) {
-    /** 避免输出 `?.`：Vue CLI 4 / Webpack 4 默认不转译 node_modules */
-    const exposeGlobalVue = extra == null || extra.exposeGlobalVue !== false;
-    if (exposeGlobalVue && typeof window !== 'undefined') {
-        window.Vue = Vue;
-    }
-    const { exposeGlobalVue: _skip, ...restExtra } = extra || {};
-    const opts = createVueCliAxiosQuickInstallOptions(router, deps, restExtra);
-    return installWebExtendPluginVue2(Vue, router, opts);
+    return options;
 }
 
-/**
- * 包对外稳定导出与 `WebExtendPluginVue2` 命名空间。
- */
-const { bootstrapPlugins, defaultFetchWebPluginManifest, resolveRuntimeOptions, ensurePluginHostRoute } = pluginRuntime;
+const { bootstrapPlugins, defaultFetchWebPluginManifest, resolveRuntimeOptions, ensurePluginHostRoute, getActivatedPluginIds } = pluginRuntime;
 const { composeManifestFetch, manifestFetchCacheMiddleware, wrapManifestFetchWithCache } = manifestComposer;
-const WebExtendPluginVue2 = Object.freeze({
-    install: installWebExtendPluginVue2,
-    runtime: Object.freeze({
-        bootstrapPlugins: bootstrapPlugins$1,
-        resolveRuntimeOptions: resolveRuntimeOptions$1,
-        ensurePluginHostRoute: ensurePluginHostRoute$1,
-        defaultFetchWebPluginManifest: defaultFetchWebPluginManifest$1,
-        composeManifestFetch: composeManifestFetch$1,
-        manifestFetchCacheMiddleware: manifestFetchCacheMiddleware$1,
-        wrapManifestFetchWithCache: wrapManifestFetchWithCache$1
-    }),
-    host: Object.freeze({
-        createHostApi,
-        disposeWebPlugin,
-        createRequestBridge,
-        registries,
-        buildMenuDescriptorsFromRoutes,
-        getRegisteredTopRouteNamesForPlugin
-    }),
-    config: Object.freeze({
-        defaultWebExtendPluginRuntime,
-        setWebExtendPluginEnv,
-        webExtendPluginEnvKeys,
-        defaultManifestFetchCache,
-        defaultManifestMode,
-        routeSynthNamePrefix,
-        peerMinimumVersions
-    }),
-    constants: Object.freeze({
-        HOST_PLUGIN_API_VERSION,
-        RUNTIME_CONSOLE_LABEL
-    }),
-    components: Object.freeze({
-        ExtensionPoint
-    }),
-    presets: Object.freeze({
-        vueCliAxios: presetVueCliAxios
-    })
-});
 
-export { ExtensionPoint, HOST_PLUGIN_API_VERSION, RUNTIME_CONSOLE_LABEL, WebExtendPluginVue2, bootstrapPlugins, buildMenuDescriptorsFromRoutes, composeManifestFetch, createHostApi, createRequestBridge, createVueCliAxiosInstallOptions, createVueCliAxiosQuickInstallOptions, defaultFetchWebPluginManifest, defaultManifestFetchCache, defaultManifestMode, defaultVueCliJavaManifestListPath, defaultWebExtendPluginRuntime, disposeWebPlugin, ensurePluginHostRoute, getRegisteredTopRouteNamesForPlugin, installVueCliAxiosWebPlugins, installWebExtendPluginVue2, manifestFetchCacheMiddleware, peerMinimumVersions, presetVueCliAxios, registries, resolveManifestPathUnderApiBase, resolveRuntimeOptions, routeSynthNamePrefix, setWebExtendPluginEnv, unwrapNestedManifestBody, webExtendPluginEnvKeys, wrapManifestFetchWithCache };
+export { ExtensionPoint, HOST_PLUGIN_API_VERSION, RUNTIME_CONSOLE_LABEL, bootstrapPlugins, composeManifestFetch, createHostApi, createRequestBridge, createVueCliAxiosInstallOptions, defaultFetchWebPluginManifest, defaultManifestFetchCache, defaultManifestMode, defaultWebExtendPluginRuntime, disposeWebPlugin, ensurePluginHostRoute, getActivatedPluginIds, getContributedRoutesForPlugin, getRegisteredTopRouteNamesForPlugin, installWebExtendPluginVue2, manifestFetchCacheMiddleware, peerMinimumVersions, registries, resolveRuntimeOptions, routeSynthNamePrefix, setWebExtendPluginEnv, webExtendPluginEnvKeys, wrapManifestFetchWithCache };
 //# sourceMappingURL=index.mjs.map