web-extend-plugin-vue2 0.1.3 → 0.2.0

package/src/bridge.js

@@ -1,50 +0,0 @@
-/**
- * 插件通过宿主访问后端的受控通道：仅允许配置的前缀路径，默认 `/api/`；强制默认 `same-origin` 携带 Cookie。
- * 前缀列表由 `createRequestBridge({ allowedPathPrefixes })` 传入，与 `defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes` 对齐。
- *
- * @module bridge
- */
-import { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
-
-/**
- * @param {string} p
- */
-function ensureLeadingSlash(p) {
-  const t = String(p || '').trim()
-  if (!t) {
-    return '/'
-  }
-  return t.startsWith('/') ? t : `/${t}`
-}
-
-/**
- * @param {{ allowedPathPrefixes?: string[] }} [config]
- */
-export 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
-      })
-    }
-  }
-}

package/src/bridge.test.js

@@ -1,38 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { createRequestBridge } from './bridge.js'
-
-describe('createRequestBridge', () => {
-  const originalFetch = globalThis.fetch
-
-  beforeEach(() => {
-    globalThis.fetch = vi.fn(() => Promise.resolve(new Response(null, { status: 200 })))
-  })
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch
-  })
-
-  it('allows paths under /api/', async () => {
-    const bridge = createRequestBridge()
-    await bridge.request('/api/channels')
-    expect(globalThis.fetch).toHaveBeenCalledWith(
-      '/api/channels',
-      expect.objectContaining({ credentials: 'same-origin' })
-    )
-  })
-
-  it('rejects paths outside allowlist', async () => {
-    const bridge = createRequestBridge()
-    await expect(bridge.request('/fp-api/x')).rejects.toThrow(/not allowed/)
-    await expect(bridge.request('http://evil.com/api/x')).rejects.toThrow()
-  })
-
-  it('honors custom allowedPathPrefixes', async () => {
-    const bridge = createRequestBridge({ allowedPathPrefixes: ['/fp-api/'] })
-    await bridge.request('/fp-api/frontend-plugins')
-    expect(globalThis.fetch).toHaveBeenCalledWith(
-      '/fp-api/frontend-plugins',
-      expect.objectContaining({ credentials: 'same-origin' })
-    )
-  })
-})

package/src/components/ExtensionPoint.vue

@@ -1,67 +0,0 @@
-<template>
-  <div class="extension-point" :data-point-id="pointId">
-    <SlotErrorBoundary
-      v-for="item in items"
-      :key="item.key"
-      :label="item.pluginId"
-    >
-      <component :is="item.component" v-bind="forwardProps" />
-    </SlotErrorBoundary>
-  </div>
-</template>
-
-<script>
-/**
- * 在宿主布局中声明扩展点；插件通过 `hostApi.registerSlotComponents(pointId, ...)` 注入组件。
- * 使用 `Vue.observable` 注册表驱动重渲染；子树错误由边界组件捕获，避免拖垮整页。
- */
-import { registries } from '../registries.js'
-
-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')
-  }
-}
-
-export default {
-  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 || {}
-    }
-  }
-}
-</script>
-
-<style scoped>
-.extension-point {
-  min-height: 8px;
-}
-</style>

package/src/constants.js

@@ -1,5 +0,0 @@
-/**
- * 与 `web-extend-plugin-server` 返回的 `FrontendPluginsResponse.hostPluginApiVersion` 保持一致，用于契约校验。
- * @type {string}
- */
-export const HOST_PLUGIN_API_VERSION = '1.0.0'

package/src/createHostApi.js

@@ -1,189 +0,0 @@
-/**
- * 构造供插件 activator 调用的宿主 API（路由、菜单、扩展点、资源注入等）。
- * 与打包工具无关；Webpack 宿主需已配置 `vue-loader` 以编译本包内的 `.vue` 依赖。
- *
- * @module createHostApi
- */
-import Vue from 'vue'
-import { HOST_PLUGIN_API_VERSION } from './constants.js'
-import { createRequestBridge } from './bridge.js'
-import { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
-import { registries } from './registries.js'
-import { registerPluginTeardown } from './teardown-registry.js'
-
-/** 扩展点列表项 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}
- */
-export 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.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)
-      }
-    }
-  }
-}

package/src/default-runtime-config.js

@@ -1,58 +0,0 @@
-/**
- * 宿主可覆盖的默认运行时配置（路径、白名单、超时等）。
- * 使用方式：`resolveRuntimeOptions({ ...defaultWebExtendPluginRuntime, manifestListPath: '/api/my-plugins' })`
- * 或只传需要改动的字段：`resolveRuntimeOptions({ manifestListPath: '/api/my-plugins' })`。
- *
- * @module default-runtime-config
- */
-
-/**
- * @typedef {typeof defaultWebExtendPluginRuntime} WebExtendPluginDefaultRuntime
- */
-
-export 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/']
-}

package/src/dispose-plugin.js

@@ -1,56 +0,0 @@
-/**
- * 单插件卸载：与 `bootstrapPlugins` / `createHostApi` 对称，清理注册表与 DOM 副作用。
- *
- * @module dispose-plugin
- */
-import Vue from 'vue'
-import { registries } from './registries.js'
-import { runPluginTeardowns } from './teardown-registry.js'
-
-/**
- * 卸载指定 id 的插件：依次执行 teardown、移除菜单与扩展点条目、删除 activator、移除带 `data-plugin-asset` 的节点。
- *
- * **路由**：Vue Router 3 无公开 `removeRoute`，此处不改动 matcher；动态路由需整页刷新或自行维护路由表。
- *
- * @param {string} pluginId 与 manifest.id 一致
- */
-export 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.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()
-      }
-    })
-  }
-}

package/src/index.js

@@ -1,12 +0,0 @@
-/**
- * Vue 2.7 宿主 Web 扩展插件运行时公共入口。
- * @see README 中 Webpack 宿主需配置 DefinePlugin 或显式 `resolveRuntimeOptions`
- */
-export { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
-export { bootstrapPlugins, resolveRuntimeOptions } from './PluginRuntime.js'
-export { createHostApi } from './createHostApi.js'
-export { disposeWebPlugin } from './dispose-plugin.js'
-export { registries } from './registries.js'
-export { createRequestBridge } from './bridge.js'
-export { HOST_PLUGIN_API_VERSION } from './constants.js'
-export { default as ExtensionPoint } from './components/ExtensionPoint.vue'

package/src/registries.js

@@ -1,23 +0,0 @@
-/**
- * 宿主全局响应式注册表：菜单与扩展点槽位，供布局与 `ExtensionPoint` 订阅。
- *
- * @module registries
- */
-import Vue from 'vue'
-
-/**
- * @type {{
- *   menus: object[],
- *   slots: Record<string, Array<{ pluginId: string, component: import('vue').Component, priority: number, key: string }>>
- * }}
- */
-export const registries = Vue.observable({
-  menus: [],
-  /** 扩展点 id → 已注册组件列表（内容区 / 工具栏等共用模型） */
-  slots: {},
-  /**
-   * 每次变更 slots 时递增，供 ExtensionPoint 计算属性显式依赖。
-   * Vue 2 对「先访问不存在的 slots[key]、后 Vue.set 补 key」的依赖收集不可靠，会导致扩展点不刷新。
-   */
-  slotRevision: 0
-})

package/src/teardown-registry.js

@@ -1,44 +0,0 @@
-/**
- * 按 `pluginId` 收集 `onTeardown` 回调，供 `disposeWebPlugin` 统一执行。
- *
- * @module teardown-registry
- */
-
-/** @type {Map<string, Function[]>} */
-const byPlugin = new Map()
-
-/**
- * 登记插件卸载时要执行的同步回调（建议只做解绑、清定时器等轻量逻辑）。
- * @param {string} pluginId
- * @param {() => void} fn
- */
-export 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
- */
-export 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)
-    }
-  }
-}