web-extend-plugin-vue2 0.1.3 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1307 @@
+'use strict';
+
+var semver = require('semver');
+var Vue = require('vue');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Vue__default = /*#__PURE__*/_interopDefault(Vue);
+
+/**
+ * 宿主可覆盖的默认运行时配置（路径、白名单、超时等）。
+ * 使用方式：`resolveRuntimeOptions({ ...defaultWebExtendPluginRuntime, manifestListPath: '/api/my-plugins' })`
+ * 或只传需要改动的字段：`resolveRuntimeOptions({ manifestListPath: '/api/my-plugins' })`。
+ *
+ * @module default-runtime-config
+ */
+
+/**
+ * @typedef {typeof defaultWebExtendPluginRuntime} WebExtendPluginDefaultRuntime
+ */
+
+const defaultWebExtendPluginRuntime = {
+  /** 清单 HTTP 服务前缀（与后端 context-path 对齐），不含尾部 `/` */
+  manifestBase: '/fp-api',
+
+  /**
+   * 拉取插件清单的 **路径段**（以 `/` 开头），拼在 `manifestBase` 之后。
+   * 完整 URL：`{manifestBase}{manifestListPath}` → 默认 `/fp-api/api/frontend-plugins`
+   */
+  manifestListPath: '/api/frontend-plugins',
+
+  /** 清单 `fetch` 的 `credentials`，需 Cookie 会话时用 `include` */
+  manifestFetchCredentials: 'include',
+
+  /** 插件 dev 服务存活探测路径（拼在 `webPluginDevOrigin` 后） */
+  devPingPath: '/__web_plugin_dev_ping',
+
+  /** 插件 dev 热更新 SSE 路径（拼在插件 dev 的 origin 后） */
+  devReloadSsePath: '/__web_plugin_reload_stream',
+
+  /** 隐式 dev 映射里，每个 id 对应的入口路径（相对插件 dev origin） */
+  webPluginDevEntryPath: '/src/plugin-entry.js',
+
+  /** `fetch(devPingUrl)` 超时毫秒数 */
+  devPingTimeoutMs: 500,
+
+  /**
+   * **隐式 dev 映射**（可选）：开发模式下若 `webPluginDevOrigin` 上 ping 成功，运行时会为若干插件 id 自动生成
+   * `{ id → origin + webPluginDevEntryPath }`，从而用 dev 服务入口替代清单里的 dist，便于热更新联调。
+   *
+   * 插件 id 来源优先级：`webPluginDevIds`（或 `VITE_WEB_PLUGIN_DEV_IDS`）→ 本字段。**默认 `[]`**，
+   * 避免把仓库示例 id 写进通用宿主；联调时在 `.env` 里设 `VITE_WEB_PLUGIN_DEV_IDS=com.xxx,com.yyy`，
+   * 或 `resolveRuntimeOptions({ defaultImplicitDevPluginIds: ['com.xxx'] })` 即可。
+   */
+  defaultImplicitDevPluginIds: [],
+
+  /**
+   * 允许通过 `<script>` / 动态 `import()` 加载的插件脚本所在主机名（小写），防误配公网 URL。
+   */
+  allowedScriptHosts: ['localhost', '127.0.0.1', '::1'],
+
+  /**
+   * `hostApi.getBridge().request(path)` 允许的 path 前缀；须以 `/` 开头。
+   * 需与后端实际 API 前缀一致。
+   */
+  bridgeAllowedPathPrefixes: ['/api/']
+};
+
+/**
+ * 不依赖 `import.meta`，兼容 Webpack 4/5、Vue CLI、Vite、Rspack 等宿主。
+ * - Webpack / Vue CLI：依赖构建时注入的 `process.env`（如 `VUE_APP_*`、`DefinePlugin` 注入的 `VITE_*`）。
+ * - Vite：在入口调用 `setWebExtendPluginEnv(import.meta.env)`，或 `installWebExtendPluginVue2(..., { env: import.meta.env })`。
+ * - 也可在入口前设置 `globalThis.__WEP_ENV__ = import.meta.env`（与 setWebExtendPluginEnv 二选一即可）。
+ *
+ * @module bundled-env
+ */
+
+/** @type {Record<string, unknown> | null} */
+let _explicitEnv = null;
+
+/**
+ * 显式注入与 `import.meta.env` 同形态的对象（推荐 Vite 宿主在入口调用一次）。
+ * @param {Record<string, unknown> | null | undefined} env
+ */
+function setWebExtendPluginEnv(env) {
+  _explicitEnv = env && typeof env === 'object' ? env : null;
+}
+
+/**
+ * @returns {Record<string, unknown> | null}
+ */
+function getInjectedEnvObject() {
+  if (_explicitEnv) {
+    return _explicitEnv
+  }
+  try {
+    const g = typeof globalThis !== 'undefined' ? globalThis : undefined;
+    if (g && g.__WEP_ENV__ && typeof g.__WEP_ENV__ === 'object') {
+      return g.__WEP_ENV__
+    }
+  } catch (_) {}
+  return null
+}
+
+/**
+ * 从注入环境读取字符串配置键（`VITE_*` / `PLUGIN_*` 等）。
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+function readInjectedEnvKey(key) {
+  const o = getInjectedEnvObject();
+  if (!o || !(key in o)) {
+    return undefined
+  }
+  const v = o[key];
+  if (v === undefined || v === '') {
+    return undefined
+  }
+  return String(v)
+}
+
+/**
+ * @returns {boolean}
+ */
+function readInjectedEnvDev() {
+  const o = getInjectedEnvObject();
+  return !!(o && o.DEV === true)
+}
+
+/**
+ * 与 `plugin-web-starter`（WebPluginsResponse）返回的 `hostPluginApiVersion` 保持一致，用于契约校验。
+ * @type {string}
+ */
+const HOST_PLUGIN_API_VERSION = '1.0.0';
+
+/**
+ * 宿主侧插件引导：拉取清单、dev 映射、加载入口脚本、调用 activator。
+ * 路径与白名单等默认值见 `defaultWebExtendPluginRuntime`，可通过 `resolveRuntimeOptions` / 环境变量覆盖。
+ *
+ * **Webpack 宿主**：用 `DefinePlugin` 注入 `process.env.VITE_*` 或 **`PLUGIN_*`**（等价键），或 `resolveRuntimeOptions` 显式传参。
+ * **Vite 宿主**：入口调用 `setWebExtendPluginEnv(import.meta.env)`，或 `installWebExtendPluginVue2(..., { env: import.meta.env })`。
+ *
+ * @module PluginRuntime
+ */
+
+const DEF = defaultWebExtendPluginRuntime;
+
+/**
+ * @typedef {object} WebExtendPluginRuntimeOptions
+ * @property {string} [manifestBase] 清单服务 URL 前缀
+ * @property {string} [manifestListPath] 清单接口路径（以 `/` 开头），拼在 manifestBase 后
+ * @property {RequestCredentials} [manifestFetchCredentials] 清单 fetch 的 credentials
+ * @property {boolean} [isDev] 开发模式
+ * @property {string} [webPluginDevOrigin] 插件 dev origin
+ * @property {string} [webPluginDevIds] 逗号分隔 id，隐式 dev 映射
+ * @property {string} [webPluginDevMapJson] 显式 dev 映射 JSON
+ * @property {string} [webPluginDevEntryPath] 隐式 dev 入口路径（相对插件 dev origin）
+ * @property {string} [devPingPath] dev 存活探测路径
+ * @property {string} [devReloadSsePath] dev 热更新 SSE 路径
+ * @property {number} [devPingTimeoutMs] 探测超时
+ * @property {string[]} [defaultImplicitDevPluginIds] 无 `webPluginDevIds`/env 时用于隐式 dev 的 id；包内默认 `[]`
+ * @property {string[]} [allowedScriptHosts] 允许加载脚本的主机名
+ * @property {string[]} [bridgeAllowedPathPrefixes] bridge.request 白名单前缀
+ * @property {boolean} [bootstrapSummary] bootstrap 结束是否打印摘要
+ */
+
+/**
+ * 从 Webpack `DefinePlugin` 等注入的 `process.env` 读取。
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+function readProcessEnv(key) {
+  try {
+    if (typeof process !== 'undefined' && process.env && key in process.env) {
+      const v = process.env[key];
+      if (v !== undefined && v !== '') {
+        return String(v)
+      }
+    }
+  } catch (_) {}
+  return undefined
+}
+
+/**
+ * `VITE_*` 的并列命名：同值可读 `PLUGIN_*`（`VITE_WEB_PLUGIN_X` → `PLUGIN_WEB_PLUGIN_X`）。
+ * Vite 需在 `defineConfig({ envPrefix: ['VITE_', 'PLUGIN_'] })` 中暴露 `PLUGIN_`；Webpack 用 DefinePlugin 注入即可。
+ * @param {string} viteStyleKey 以 `VITE_` 开头的键名
+ * @returns {string|null}
+ */
+function viteKeyToPluginAlternate(viteStyleKey) {
+  if (typeof viteStyleKey !== 'string' || !viteStyleKey.startsWith('VITE_')) {
+    return null
+  }
+  return `PLUGIN_${viteStyleKey.slice(5)}`
+}
+
+/**
+ * 先读注入环境（`setWebExtendPluginEnv` / `__WEP_ENV__`）中的 `VITE_*` 与并列 `PLUGIN_*`，再读 `process.env`，最后 `fallback`。
+ * @param {string} key 仍以 `VITE_*` 为逻辑名（与文档一致）
+ * @param {string} [fallback='']
+ */
+function resolveBundledEnv(key, fallback = '') {
+  const alt = viteKeyToPluginAlternate(key);
+  const fromInjected =
+    readInjectedEnvKey(key) ?? (alt ? readInjectedEnvKey(alt) : undefined);
+  const fromProcess =
+    readProcessEnv(key) ?? (alt ? readProcessEnv(alt) : undefined);
+  return fromInjected ?? fromProcess ?? fallback
+}
+
+/**
+ * @returns {boolean}
+ */
+function resolveBundledIsDev() {
+  try {
+    if (readInjectedEnvDev()) {
+      return true
+    }
+  } catch (_) {}
+  try {
+    if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'development') {
+      return true
+    }
+  } catch (_) {}
+  return false
+}
+
+/**
+ * @param {string} p
+ */
+function ensureLeadingPath(p) {
+  const t = String(p || '').trim();
+  if (!t) {
+    return '/'
+  }
+  return t.startsWith('/') ? t : `/${t}`
+}
+
+/**
+ * 解析 `include` | `omit` | `same-origin`，非法时回退默认值。
+ * @param {string|undefined} userVal
+ * @param {string} envKey
+ * @param {RequestCredentials} fallback
+ */
+function resolveManifestCredentials(userVal, envKey, fallback) {
+  if (userVal !== undefined && userVal !== '') {
+    const s = String(userVal);
+    if (s === 'include' || s === 'omit' || s === 'same-origin') {
+      return s
+    }
+  }
+  const e = resolveBundledEnv(envKey, '');
+  if (e === 'include' || e === 'omit' || e === 'same-origin') {
+    return e
+  }
+  return fallback
+}
+
+/**
+ * @param {number|undefined} userVal
+ * @param {string} envKey
+ * @param {number} fallback
+ */
+function resolvePositiveInt(userVal, envKey, fallback) {
+  if (typeof userVal === 'number' && Number.isFinite(userVal) && userVal > 0) {
+    return Math.floor(userVal)
+  }
+  const raw = resolveBundledEnv(envKey, '');
+  const n = raw ? parseInt(raw, 10) : NaN;
+  if (Number.isFinite(n) && n > 0) {
+    return n
+  }
+  return fallback
+}
+
+/**
+ * 合并用户、环境变量与 `defaultWebExtendPluginRuntime`，得到完整运行时选项（宿主可只传需要覆盖的字段）。
+ * @param {WebExtendPluginRuntimeOptions} [user]
+ * @returns {object}
+ */
+function resolveRuntimeOptions(user = {}) {
+  const manifestBaseRaw =
+    user.manifestBase !== undefined && user.manifestBase !== ''
+      ? String(user.manifestBase)
+      : resolveBundledEnv('VITE_FRONTEND_PLUGIN_BASE', DEF.manifestBase) || DEF.manifestBase;
+
+  const manifestListPath = ensureLeadingPath(
+    user.manifestListPath !== undefined && user.manifestListPath !== ''
+      ? user.manifestListPath
+      : resolveBundledEnv('VITE_WEB_PLUGIN_MANIFEST_PATH', DEF.manifestListPath)
+  );
+
+  const defaultImplicitDevPluginIds =
+    Array.isArray(user.defaultImplicitDevPluginIds)
+      ? user.defaultImplicitDevPluginIds.map(String).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_IMPLICIT_DEV_IDS', '');
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => s.trim())
+              .filter(Boolean)
+          }
+          return [...DEF.defaultImplicitDevPluginIds]
+        })();
+
+  const allowedScriptHosts =
+    Array.isArray(user.allowedScriptHosts) && user.allowedScriptHosts.length > 0
+      ? user.allowedScriptHosts.map((h) => normalizeHost(String(h))).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_ALLOWED_SCRIPT_HOSTS', '');
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => normalizeHost(s.trim()))
+              .filter(Boolean)
+          }
+          return [...DEF.allowedScriptHosts]
+        })();
+
+  const bridgeAllowedPathPrefixes =
+    Array.isArray(user.bridgeAllowedPathPrefixes) && user.bridgeAllowedPathPrefixes.length > 0
+      ? user.bridgeAllowedPathPrefixes.map((p) => ensureLeadingPath(p)).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_BRIDGE_PREFIXES', '');
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => ensureLeadingPath(s.trim()))
+              .filter(Boolean)
+          }
+          return [...DEF.bridgeAllowedPathPrefixes]
+        })();
+
+  return {
+    manifestBase: manifestBaseRaw.replace(/\/$/, '') || DEF.manifestBase.replace(/\/$/, ''),
+    manifestListPath,
+    manifestFetchCredentials: resolveManifestCredentials(
+      user.manifestFetchCredentials,
+      'VITE_WEB_PLUGIN_MANIFEST_CREDENTIALS',
+      DEF.manifestFetchCredentials
+    ),
+    isDev: user.isDev !== undefined ? user.isDev : resolveBundledIsDev(),
+    webPluginDevOrigin:
+      user.webPluginDevOrigin !== undefined ? user.webPluginDevOrigin : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_ORIGIN', ''),
+    webPluginDevIds:
+      user.webPluginDevIds !== undefined ? user.webPluginDevIds : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_IDS', ''),
+    webPluginDevMapJson:
+      user.webPluginDevMapJson !== undefined
+        ? user.webPluginDevMapJson
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_MAP', ''),
+    webPluginDevEntryPath: ensureLeadingPath(
+      user.webPluginDevEntryPath !== undefined && user.webPluginDevEntryPath !== ''
+        ? user.webPluginDevEntryPath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_ENTRY', DEF.webPluginDevEntryPath)
+    ),
+    devPingPath: ensureLeadingPath(
+      user.devPingPath !== undefined && user.devPingPath !== ''
+        ? user.devPingPath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_PING_PATH', DEF.devPingPath)
+    ),
+    devReloadSsePath: ensureLeadingPath(
+      user.devReloadSsePath !== undefined && user.devReloadSsePath !== ''
+        ? user.devReloadSsePath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_SSE_PATH', DEF.devReloadSsePath)
+    ),
+    devPingTimeoutMs: resolvePositiveInt(user.devPingTimeoutMs, 'VITE_WEB_PLUGIN_DEV_PING_TIMEOUT_MS', DEF.devPingTimeoutMs),
+    defaultImplicitDevPluginIds,
+    allowedScriptHosts,
+    bridgeAllowedPathPrefixes,
+    bootstrapSummary: user.bootstrapSummary
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ */
+function shouldShowBootstrapSummary(opts) {
+  if (opts.bootstrapSummary === true) {
+    return true
+  }
+  if (opts.bootstrapSummary === false) {
+    return false
+  }
+  const env = resolveBundledEnv('VITE_PLUGINS_BOOTSTRAP_SUMMARY', '');
+  if (env === '0' || env === 'false') {
+    return false
+  }
+  if (env === '1' || env === 'true') {
+    return true
+  }
+  return resolveBundledIsDev()
+}
+
+/**
+ * @param {string} hostname
+ */
+function normalizeHost(hostname) {
+  if (!hostname) {
+    return ''
+  }
+  const h = hostname.toLowerCase();
+  if (h.startsWith('[') && h.endsWith(']')) {
+    return h.slice(1, -1)
+  }
+  return h
+}
+
+/**
+ * @param {string[]} hostnames
+ * @returns {Set<string>}
+ */
+function buildAllowedScriptHostsSet(hostnames) {
+  const s = new Set();
+  for (const h of hostnames) {
+    const n = normalizeHost(h);
+    if (n) {
+      s.add(n);
+    }
+  }
+  return s
+}
+
+/**
+ * @param {string} url
+ * @param {Set<string>} hostSet
+ */
+function isScriptHostAllowed(url, hostSet) {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  try {
+    const u = new URL(url, window.location.origin);
+    const h = normalizeHost(u.hostname);
+    return hostSet.has(h)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ */
+function parseWebPluginDevMapExplicit(opts) {
+  if (!opts.isDev) {
+    return null
+  }
+  const raw = opts.webPluginDevMapJson;
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return null
+  }
+  try {
+    const map = JSON.parse(String(raw));
+    return map && typeof map === 'object' ? map : null
+  } catch {
+    console.warn('[plugins] webPluginDevMapJson / VITE_WEB_PLUGIN_DEV_MAP is not valid JSON');
+    return null
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ * @param {Set<string>} hostSet
+ */
+async function buildImplicitWebPluginDevMap(opts, hostSet) {
+  if (!opts.isDev) {
+    return {}
+  }
+  const origin =
+    opts.webPluginDevOrigin === undefined || opts.webPluginDevOrigin === null
+      ? ''
+      : String(opts.webPluginDevOrigin).trim();
+  if (!origin) {
+    return {}
+  }
+  if (!isScriptHostAllowed(`${origin}/`, hostSet)) {
+    return {}
+  }
+
+  const idsRaw = opts.webPluginDevIds;
+  const ids =
+    idsRaw !== undefined && idsRaw !== null && String(idsRaw).trim() !== ''
+      ? String(idsRaw)
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [...opts.defaultImplicitDevPluginIds];
+
+  if (ids.length === 0) {
+    return {}
+  }
+
+  const base = origin.replace(/\/$/, '');
+  const pingUrl = `${base}${opts.devPingPath}`;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.devPingTimeoutMs);
+    const r = await fetch(pingUrl, {
+      mode: 'cors',
+      cache: 'no-store',
+      signal: ctrl.signal
+    });
+    clearTimeout(timer);
+    if (!r.ok) {
+      return {}
+    }
+    const body = (await r.text()).trim();
+    if (body !== 'ok') {
+      return {}
+    }
+  } catch {
+    return {}
+  }
+
+  const pathPart = opts.webPluginDevEntryPath;
+  const map = {};
+  for (const id of ids) {
+    map[id] = `${base}${pathPart}`;
+  }
+  if (ids.length) {
+    console.info(
+      '[plugins] 已检测到插件 dev 服务（',
+      base,
+      '），下列 id 将加载隐式 dev 入口（',
+      pathPart,
+      '）而非清单 dist：',
+      ids.join(', ')
+    );
+  }
+  return map
+}
+
+/**
+ * @param {Record<string, string>} implicit
+ * @param {Record<string, string>|null} explicit
+ */
+function mergeDevMaps(implicit, explicit) {
+  const i = implicit && typeof implicit === 'object' ? implicit : {};
+  const e = explicit && typeof explicit === 'object' ? explicit : {};
+  return { ...i, ...e }
+}
+
+/** @type {Map<string, EventSource>} */
+const pluginDevEventSources = new Map();
+
+let pluginDevBeforeUnloadRegistered = false;
+
+function closeAllPluginDevEventSources() {
+  for (const es of pluginDevEventSources.values()) {
+    try {
+      es.close();
+    } catch (_) {}
+  }
+  pluginDevEventSources.clear();
+}
+
+function ensurePluginDevBeforeUnload() {
+  if (pluginDevBeforeUnloadRegistered || typeof window === 'undefined') {
+    return
+  }
+  pluginDevBeforeUnloadRegistered = true;
+  window.addEventListener('beforeunload', closeAllPluginDevEventSources);
+}
+
+/**
+ * @param {string} origin
+ * @param {Set<string>} hostSet
+ */
+function isDevOriginAllowedForSse(origin, hostSet) {
+  try {
+    const u = new URL(origin);
+    return hostSet.has(normalizeHost(u.hostname))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} origin
+ * @param {boolean} isDev
+ * @param {Set<string>} hostSet
+ * @param {string} ssePath
+ */
+function startPluginDevReloadSse(origin, isDev, hostSet, ssePath) {
+  if (!isDev || pluginDevEventSources.has(origin)) {
+    return
+  }
+  if (!isDevOriginAllowedForSse(origin, hostSet)) {
+    return
+  }
+  ensurePluginDevBeforeUnload();
+  const base = origin.replace(/\/$/, '');
+  const url = `${base}${ssePath}`;
+  try {
+    const es = new EventSource(url);
+    pluginDevEventSources.set(origin, es);
+    es.addEventListener('reload', () => {
+      window.location.reload();
+    });
+    es.onopen = () => {
+      console.info('[plugins] plugin dev reload SSE:', url);
+    };
+  } catch (e) {
+    console.warn('[plugins] EventSource failed', url, e);
+  }
+}
+
+/**
+ * @param {Record<string, string>|null|undefined} devMap
+ * @param {boolean} isDev
+ * @param {Set<string>} hostSet
+ * @param {string} ssePath
+ */
+function startPluginDevSseForMap(devMap, isDev, hostSet, ssePath) {
+  if (!isDev || !devMap || typeof window === 'undefined') {
+    return
+  }
+  const origins = new Set();
+  for (const entry of Object.values(devMap)) {
+    if (typeof entry !== 'string') {
+      continue
+    }
+    const t = entry.trim();
+    if (!t) {
+      continue
+    }
+    try {
+      origins.add(new URL(t, window.location.href).origin);
+    } catch {
+      /* skip */
+    }
+  }
+  for (const o of origins) {
+    startPluginDevReloadSse(o, 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
+}
+
+/**
+ * @param {{ id: string }} p
+ * @param {string} [entryUrl]
+ * @param {Record<string, string>|null|undefined} devMap
+ * @param {Set<string>} hostSet
+ */
+async function loadPluginEntry(p, entryUrl, devMap, hostSet) {
+  const devEntry = devMap && typeof devMap[p.id] === 'string' ? devMap[p.id].trim() : '';
+  if (devEntry) {
+    if (!isScriptHostAllowed(devEntry, hostSet)) {
+      console.warn('[plugins] dev entry URL not allowed', p.id, devEntry);
+      return
+    }
+    try {
+      await import(
+        /* webpackIgnore: true */
+        /* @vite-ignore */
+        devEntry
+      );
+    } catch (e) {
+      console.warn('[plugins] dev module import failed, try manifest entryUrl', p.id, e);
+      if (entryUrl && isScriptHostAllowed(entryUrl, hostSet)) {
+        await loadScript(entryUrl);
+      }
+      return
+    }
+    return
+  }
+  if (!entryUrl || !isScriptHostAllowed(entryUrl, hostSet)) {
+    console.warn('[plugins] skip (entryUrl not allowed)', p.id, entryUrl);
+    return
+  }
+  await loadScript(entryUrl);
+}
+
+/**
+ * @param {import('vue-router').default} router
+ * @param {(pluginId: string, router: import('vue-router').default, hostKit?: { bridgeAllowedPathPrefixes: string[] }) => object} createHostApiFactory
+ *        始终传入三个参数；单参工厂 `(id) => createHostApi(id, router)` 仍可用，后两个实参被忽略。
+ * @param {WebExtendPluginRuntimeOptions} [runtimeOptions]
+ */
+async function bootstrapPlugins(router, createHostApiFactory, runtimeOptions) {
+  if (typeof window === 'undefined') {
+    console.warn('[plugins] bootstrapPlugins skipped: requires browser (window)');
+    return
+  }
+  const opts = resolveRuntimeOptions(runtimeOptions || {});
+  const base = String(opts.manifestBase).replace(/\/$/, '');
+  const manifestUrl = `${base}${opts.manifestListPath}`;
+  const hostSet = buildAllowedScriptHostsSet(opts.allowedScriptHosts);
+  const explicit = parseWebPluginDevMapExplicit(opts);
+
+  const [manifestResult, implicit] = await Promise.all([
+    (async () => {
+      try {
+        const res = await fetch(manifestUrl, { credentials: opts.manifestFetchCredentials });
+        if (!res.ok) {
+          return { ok: false, status: res.status, data: null }
+        }
+        const data = await res.json();
+        return { ok: true, data }
+      } catch (e) {
+        return { ok: false, error: e, data: null }
+      }
+    })(),
+    buildImplicitWebPluginDevMap(opts, hostSet)
+  ]);
+
+  const devMap = mergeDevMaps(implicit, explicit);
+  startPluginDevSseForMap(devMap, opts.isDev, hostSet, opts.devReloadSsePath);
+
+  const hostKit = { bridgeAllowedPathPrefixes: opts.bridgeAllowedPathPrefixes };
+
+  if (!manifestResult.ok) {
+    if (manifestResult.error) {
+      console.warn('[plugins] fetch manifest failed', manifestResult.error);
+    } else {
+      console.warn('[plugins] manifest HTTP', manifestResult.status, manifestUrl);
+    }
+    if (shouldShowBootstrapSummary(opts)) {
+      console.info('[plugins] bootstrap_summary', { ok: false, reason: 'manifest_fetch' });
+    }
+    return
+  }
+  /** @type {{ hostPluginApiVersion?: string, plugins?: object[] }} */
+  const data = manifestResult.data;
+  if (!data) {
+    if (shouldShowBootstrapSummary(opts)) {
+      console.info('[plugins] bootstrap_summary', { ok: false, reason: 'manifest_empty_body' });
+    }
+    return
+  }
+
+  const apiVer = data.hostPluginApiVersion;
+  if (apiVer) {
+    const coerced = semver.coerce(apiVer);
+    const maj = coerced ? coerced.major : 0;
+    const range = `^${maj}.0.0`;
+    if (!semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
+      console.warn(
+        '[plugins] host API version mismatch: host implements',
+        HOST_PLUGIN_API_VERSION,
+        'server declares',
+        apiVer
+      );
+    }
+  }
+
+  window.__PLUGIN_ACTIVATORS__ = window.__PLUGIN_ACTIVATORS__ || {};
+
+  const plugins = data.plugins || [];
+  if (plugins.length === 0) {
+    console.info(
+      '[plugins] 清单为空。请检查：① 后端清单服务（plugin-web-starter）是否已接入；② web-plugin.web-plugins-dir 是否指向含各插件子目录及 manifest.json 的路径；③ 浏览器直接访问',
+      manifestUrl,
+      '是否返回 plugins 条目。'
+    );
+  }
+
+  const summary = {
+    manifestCount: plugins.length,
+    activated: 0,
+    skipEngines: 0,
+    skipLoad: 0,
+    skipNoActivator: 0,
+    activateFail: 0
+  };
+
+  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('[plugins] skip (engines.host)', p.id, range);
+      summary.skipEngines++;
+      continue
+    }
+    const entryUrl = p.entryUrl;
+    try {
+      await loadPluginEntry(p, entryUrl, devMap, hostSet);
+    } catch (e) {
+      console.warn('[plugins] script load failed', p.id, e);
+      summary.skipLoad++;
+      continue
+    }
+    const activator = window.__PLUGIN_ACTIVATORS__[p.id];
+    if (typeof activator !== 'function') {
+      console.warn('[plugins] no activator for', p.id);
+      summary.skipNoActivator++;
+      continue
+    }
+    const hostApi = createHostApiFactory(p.id, router, hostKit);
+    try {
+      activator(hostApi);
+      summary.activated++;
+    } catch (e) {
+      console.error('[plugins] activate failed', p.id, e);
+      summary.activateFail++;
+    }
+  }
+
+  if (shouldShowBootstrapSummary(opts)) {
+    console.info('[plugins] bootstrap_summary', { ok: true, ...summary });
+  }
+}
+
+/**
+ * 插件通过宿主访问后端的受控通道：仅允许配置的前缀路径，默认 `/api/`；强制默认 `same-origin` 携带 Cookie。
+ * 前缀列表由 `createRequestBridge({ allowedPathPrefixes })` 传入，与 `defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes` 对齐。
+ *
+ * @module bridge
+ */
+
+/**
+ * @param {string} p
+ */
+function ensureLeadingSlash(p) {
+  const t = String(p || '').trim();
+  if (!t) {
+    return '/'
+  }
+  return t.startsWith('/') ? t : `/${t}`
+}
+
+/**
+ * @param {{ allowedPathPrefixes?: string[] }} [config]
+ */
+function createRequestBridge(config = {}) {
+  const raw =
+    Array.isArray(config.allowedPathPrefixes) && config.allowedPathPrefixes.length > 0
+      ? config.allowedPathPrefixes
+      : defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes;
+  const allowedPathPrefixes = raw.map((p) => ensureLeadingSlash(p));
+
+  return {
+    /**
+     * 发起受控 `fetch`。
+     * @param {string} path 必须以 `/` 开头，且匹配某一 `allowedPathPrefixes` 前缀
+     * @param {RequestInit} [init] 会与默认 `{ credentials: 'same-origin' }` 合并（后者可被覆盖）
+     */
+    async request(path, init = {}) {
+      if (typeof path !== 'string' || !path.startsWith('/')) {
+        throw new Error('[bridge] path must be a string starting with /')
+      }
+      const allowed = allowedPathPrefixes.some((p) => path.startsWith(p));
+      if (!allowed) {
+        throw new Error('[bridge] path not allowed: ' + path)
+      }
+      return fetch(path, {
+        credentials: 'same-origin',
+        ...init
+      })
+    }
+  }
+}
+
+/**
+ * 宿主全局响应式注册表：菜单与扩展点槽位，供布局与 `ExtensionPoint` 订阅。
+ *
+ * @module registries
+ */
+
+/**
+ * @type {{
+ *   menus: object[],
+ *   slots: Record<string, Array<{ pluginId: string, component: import('vue').Component, priority: number, key: string }>>
+ * }}
+ */
+const registries = Vue__default.default.observable({
+  menus: [],
+  /** 扩展点 id → 已注册组件列表（内容区 / 工具栏等共用模型） */
+  slots: {},
+  /**
+   * 每次变更 slots 时递增，供 ExtensionPoint 计算属性显式依赖。
+   * Vue 2 对「先访问不存在的 slots[key]、后 Vue.set 补 key」的依赖收集不可靠，会导致扩展点不刷新。
+   */
+  slotRevision: 0
+});
+
+/**
+ * 按 `pluginId` 收集 `onTeardown` 回调，供 `disposeWebPlugin` 统一执行。
+ *
+ * @module teardown-registry
+ */
+
+/** @type {Map<string, Function[]>} */
+const byPlugin = new Map();
+
+/**
+ * 登记插件卸载时要执行的同步回调（建议只做解绑、清定时器等轻量逻辑）。
+ * @param {string} pluginId
+ * @param {() => void} fn
+ */
+function registerPluginTeardown(pluginId, fn) {
+  if (typeof fn !== 'function') {
+    return
+  }
+  let arr = byPlugin.get(pluginId);
+  if (!arr) {
+    arr = [];
+    byPlugin.set(pluginId, arr);
+  }
+  arr.push(fn);
+}
+
+/**
+ * 执行并清空该插件已登记的全部 teardown；调用后 Map 中不再保留该 id。
+ * @param {string} pluginId
+ */
+function runPluginTeardowns(pluginId) {
+  const arr = byPlugin.get(pluginId);
+  if (!arr) {
+    return
+  }
+  byPlugin.delete(pluginId);
+  for (const fn of arr) {
+    try {
+      fn();
+    } catch (e) {
+      console.warn('[plugins] teardown failed', pluginId, e);
+    }
+  }
+}
+
+/**
+ * 构造供插件 activator 调用的宿主 API（路由、菜单、扩展点、资源注入等）。
+ * 与打包工具无关；Webpack 宿主需已配置 `vue-loader` 以编译本包内的 `.vue` 依赖。
+ *
+ * @module createHostApi
+ */
+
+/** 扩展点列表项 key 递增，避免用 Date.now() 导致列表重排时误卸载组件 */
+let slotItemKeySeq = 0;
+/** 无 name 的动态路由合成名递增，避免多次 registerRoutes 重名 */
+let routeSynthSeq = 0;
+
+/**
+ * @typedef {object} RegisterSlotEntry
+ * @property {import('vue').Component} component
+ * @property {number} [priority]
+ */
+
+/**
+ * @typedef {object} HostApi
+ * @property {string} hostPluginApiVersion 宿主实现的协议版本
+ * @property {(routes: import('vue-router').RouteConfig[]) => void} registerRoutes 注册路由；无 `name` 时自动生成稳定合成名；优先 `router.addRoute`
+ * @property {(items: object[]) => void} registerMenuItems 注册菜单并按 `order` 排序
+ * @property {(pointId: string, components: RegisterSlotEntry[]) => void} registerSlotComponents 向扩展点挂载组件
+ * @property {(urls?: string[]) => void} registerStylesheetUrls 注入 `link[rel=stylesheet]`，带 `data-plugin-asset`
+ * @property {(urls?: string[]) => void} registerScriptUrls 顺序注入外链脚本
+ * @property {() => void} registerSanitizedHtmlSnippet MVP 未实现，调用即抛错
+ * @property {() => ReturnType<typeof createRequestBridge>} getBridge 受控 `fetch` 代理
+ * @property {(pluginId: string, fn: () => void) => void} onTeardown 注册卸载回调；由 `disposeWebPlugin(pluginId)` 触发
+ */
+
+/**
+ * @typedef {object} HostKitOptions
+ * @property {string[]} [bridgeAllowedPathPrefixes] 覆盖 `getBridge().request` 允许的 URL 前缀；默认见 `defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes`
+ */
+
+/**
+ * 创建单个插件在宿主侧的 API 句柄，传入插件 `activator(hostApi)`。
+ *
+ * `bootstrapPlugins` 始终以 `(pluginId, router, hostKitOptions)` 调用工厂；请使用 `(id, r, kit) => createHostApi(id, r, kit)` 传入 `bridgeAllowedPathPrefixes`。
+ * 单参工厂 `(id) => createHostApi(id, router)` 仍可用（忽略后两个实参），此时 bridge 仅用包内默认前缀。
+ *
+ * @param {string} pluginId 与 manifest.id 一致
+ * @param {import('vue-router').default} router 宿主 Vue Router 实例（vue-router@3）
+ * @param {HostKitOptions} [hostKitOptions]
+ * @returns {HostApi}
+ */
+function createHostApi(pluginId, router, hostKitOptions = {}) {
+  const bridgePrefixes =
+    Array.isArray(hostKitOptions.bridgeAllowedPathPrefixes) &&
+    hostKitOptions.bridgeAllowedPathPrefixes.length > 0
+      ? hostKitOptions.bridgeAllowedPathPrefixes
+      : defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes;
+  const bridge = createRequestBridge({ allowedPathPrefixes: bridgePrefixes });
+
+  /**
+   * 注入样式表；`disposeWebPlugin` 会按 `data-plugin-asset` 移除对应节点。
+   * @param {string} href
+   */
+  function injectStylesheet(href) {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = href;
+    link.setAttribute('data-plugin-asset', pluginId);
+    document.head.appendChild(link);
+  }
+
+  /**
+   * 注入外链脚本（用于插件额外资源，非清单主入口）。
+   * @param {string} src
+   * @returns {Promise<void>}
+   */
+  function injectScript(src) {
+    return new Promise((resolve, reject) => {
+      const s = document.createElement('script');
+      s.async = true;
+      s.src = src;
+      s.setAttribute('data-plugin-asset', pluginId);
+      s.onload = () => resolve();
+      s.onerror = () => reject(new Error('script failed: ' + src));
+      document.head.appendChild(s);
+    })
+  }
+
+  return {
+    hostPluginApiVersion: HOST_PLUGIN_API_VERSION,
+
+    /**
+     * 动态注册路由。Vue Router 3.5+ 推荐 `addRoute`；若不存在则回退已弃用的 `addRoutes`。
+     * @param {import('vue-router').RouteConfig[]} routes
+     */
+    registerRoutes(routes) {
+      const wrapped = routes.map((r) => ({
+        ...r,
+        name: r.name || `__wep_${pluginId}_${routeSynthSeq++}`,
+        meta: { ...(r.meta || {}), pluginId }
+      }));
+      if (typeof router.addRoute === 'function') {
+        for (const r of wrapped) {
+          router.addRoute(r);
+        }
+      } else {
+        router.addRoutes(wrapped);
+      }
+    },
+
+    /**
+     * 写入全局菜单注册表（响应式）；按 `order` 升序排列。
+     * @param {object[]} items
+     */
+    registerMenuItems(items) {
+      for (const item of items) {
+        registries.menus.push({ ...item, pluginId });
+      }
+      registries.menus.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    },
+
+    /**
+     * 向指定扩展点 id 注册 Vue 组件；`ExtensionPoint` 按 `priority` 降序渲染。
+     * @param {string} pointId
+     * @param {RegisterSlotEntry[]} components
+     */
+    registerSlotComponents(pointId, components) {
+      if (!pointId) {
+        return
+      }
+      if (!registries.slots[pointId]) {
+        Vue__default.default.set(registries.slots, pointId, []);
+      }
+      const list = registries.slots[pointId];
+      for (const c of components) {
+        list.push({
+          pluginId,
+          component: c.component,
+          priority: c.priority ?? 0,
+          key: `${pluginId}-${pointId}-${++slotItemKeySeq}`
+        });
+      }
+      list.sort((a, b) => b.priority - a.priority);
+      registries.slotRevision++;
+    },
+
+    /**
+     * @param {string[]|undefined} urls
+     */
+    registerStylesheetUrls(urls) {
+      for (const u of urls || []) {
+        if (typeof u === 'string' && u) {
+          injectStylesheet(u);
+        }
+      }
+    },
+
+    /**
+     * 串行加载多个脚本，失败仅告警不中断宿主。
+     * @param {string[]|undefined} urls
+     */
+    registerScriptUrls(urls) {
+      const chain = (urls || []).filter((u) => typeof u === 'string' && u).reduce(
+        (p, u) => p.then(() => injectScript(u)),
+        Promise.resolve()
+      );
+      chain.catch((e) => console.warn('[plugins] registerScriptUrls', pluginId, e));
+    },
+
+    registerSanitizedHtmlSnippet() {
+      throw new Error('registerSanitizedHtmlSnippet is not enabled in MVP')
+    },
+
+    getBridge: () => bridge,
+
+    /**
+     * 插件卸载前清理逻辑；第一个参数为预留与协议对齐，实际以创建 API 时的 `pluginId` 为准。
+     * @param {string} _pluginId 预留，与 manifest.id 一致时可传入
+     * @param {() => void} fn
+     */
+    onTeardown(_pluginId, fn) {
+      if (typeof fn === 'function') {
+        registerPluginTeardown(pluginId, fn);
+      }
+    }
+  }
+}
+
+/**
+ * 单插件卸载：与 `bootstrapPlugins` / `createHostApi` 对称，清理注册表与 DOM 副作用。
+ *
+ * @module dispose-plugin
+ */
+
+/**
+ * 卸载指定 id 的插件：依次执行 teardown、移除菜单与扩展点条目、删除 activator、移除带 `data-plugin-asset` 的节点。
+ *
+ * **路由**：Vue Router 3 无公开 `removeRoute`，此处不改动 matcher；动态路由需整页刷新或自行维护路由表。
+ *
+ * @param {string} pluginId 与 manifest.id 一致
+ */
+function disposeWebPlugin(pluginId) {
+  if (!pluginId || typeof pluginId !== 'string') {
+    return
+  }
+
+  runPluginTeardowns(pluginId);
+
+  for (let i = registries.menus.length - 1; i >= 0; i--) {
+    if (registries.menus[i].pluginId === pluginId) {
+      registries.menus.splice(i, 1);
+    }
+  }
+
+  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__default.default.delete(slots, pointId);
+    } else if (next.length !== list.length) {
+      Vue__default.default.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();
+      }
+    });
+  }
+}
+
+/**
+ * 在宿主布局中声明扩展点；插件通过 `hostApi.registerSlotComponents(pointId, ...)` 注入组件。
+ * 使用纯 render 函数，便于 Rollup 发布 dist，宿主无需再转译 .vue。
+ */
+
+const SlotErrorBoundary = {
+  name: 'SlotErrorBoundary',
+  props: { label: String },
+  data() {
+    return { error: null }
+  },
+  errorCaptured(err) {
+    this.error = err && err.message ? err.message : String(err);
+    console.error('[ExtensionPoint] render error in', this.label, err);
+    return false
+  },
+  render(h) {
+    if (this.error) {
+      return h(
+        'div',
+        { class: 'plugin-point-error', style: { color: '#c00', fontSize: '12px' } },
+        `[插件 ${this.label}] 渲染失败`
+      )
+    }
+    const d = this.$slots.default;
+    return d && d[0] ? d[0] : h('span')
+  }
+};
+
+var ExtensionPoint = {
+  name: 'ExtensionPoint',
+  components: { SlotErrorBoundary },
+  props: {
+    pointId: { type: String, required: true },
+    slotProps: { type: Object, default: () => ({}) }
+  },
+  computed: {
+    items() {
+      void registries.slotRevision;
+      return registries.slots[this.pointId] || []
+    },
+    forwardProps() {
+      return this.slotProps || {}
+    }
+  },
+  render(h) {
+    return h(
+      'div',
+      {
+        class: 'extension-point',
+        style: { minHeight: '8px' },
+        attrs: { 'data-point-id': this.pointId }
+      },
+      this.items.map((item) =>
+        h(
+          SlotErrorBoundary,
+          {
+            key: item.key,
+            props: { label: item.pluginId }
+          },
+          [h(item.component, { props: this.forwardProps })]
+        )
+      )
+    )
+  }
+};
+
+/**
+ * 一键接入：注册 `ExtensionPoint` 并执行 `bootstrapPlugins`。
+ * @module install
+ */
+
+/**
+ * 注册全局组件 `ExtensionPoint` 并异步引导插件清单。
+ *
+ * @param {*} Vue
+ * @param {*} router  vue-router 实例
+ * @param {Record<string, unknown>} [options] 传给 `resolveRuntimeOptions` 的字段；可含 `env`（Vite 传入 `import.meta.env`）以读取 `VITE_*`。
+ * @returns {Promise<void>}
+ */
+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(runtimeUser);
+  return bootstrapPlugins(router, (id, r, kit) => createHostApi(id, r, kit), runtime)
+}
+
+exports.ExtensionPoint = ExtensionPoint;
+exports.HOST_PLUGIN_API_VERSION = HOST_PLUGIN_API_VERSION;
+exports.bootstrapPlugins = bootstrapPlugins;
+exports.createHostApi = createHostApi;
+exports.createRequestBridge = createRequestBridge;
+exports.defaultWebExtendPluginRuntime = defaultWebExtendPluginRuntime;
+exports.disposeWebPlugin = disposeWebPlugin;
+exports.installWebExtendPluginVue2 = installWebExtendPluginVue2;
+exports.registries = registries;
+exports.resolveRuntimeOptions = resolveRuntimeOptions;
+exports.setWebExtendPluginEnv = setWebExtendPluginEnv;
+//# sourceMappingURL=index.cjs.map