@zero-bits/kernel 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @zero-bits/kernel
+
+一个面向微前端架构的高性能、零防备、框架无关的内核引擎。
+
+## 特性
+
+- 🏗 **框架无关**：核心层（Core）不依赖任何 UI 框架，支持 Vue/React/Svelte 等任意架构。
+- ⚛️ **原生 React 支持**：提供专门的 React 绑定层，内置 `PluginSlot` 插槽组件和 `Context` 实例分发。
+- 🛡 **极佳容错与并发**：
+  - 自带多实例全局并发锁，同一个插件在多实例下只会加载一次网络请求。
+  - 自动缓存失效处理（基于 URL）。
+  - 内置超时控制（Timeout）与指数退避重试（Retry）。
+- 🔌 **干净的 API 与自定义命名空间**：支持隔离多个引擎在同一页面的内核变量，防止命名空间污染。
+
+## 安装
+
+```bash
+npm install @zero-bits/kernel
+```
+
+## 导出说明
+
+本包采用 `exports` 子路径导出设计，彻底隔离框架核心与视图层依赖：
+
+- `@zero-bits/kernel` (只包含纯核心逻辑，无 React 依赖)
+- `@zero-bits/kernel/react` (包含 React 插槽与上下文层，需在宿主安装 React)
+
+## 快速使用 (React 环境)
+
+### 1. 注册核心实例
+
+在主应用入口或 Context 顶层，初始化并提供 `Kernel` 实例：
+
+```tsx
+import React from 'react'
+import { createKernel } from '@zero-bits/kernel'
+import { KernelProvider } from '@zero-bits/kernel/react'
+
+const kernel = createKernel({
+  timeout: 5000,
+  retryCount: 3,
+  namespace: '__MY_APP__' // 隔离多内核实例冲突
+})
+
+// 注入共享依赖供子插件使用
+kernel.regSharedModule('react', React)
+
+export function App() {
+  return (
+    <KernelProvider kernel={kernel}>
+      <MainLayout />
+    </KernelProvider>
+  )
+}
+```
+
+### 2. 在业务组件中加载远端插件
+
+直接使用 `PluginSlot` 占位，它会自动从上下文中获取 Kernel 并渲染远端组件。
+
+```tsx
+import { PluginSlot } from '@zero-bits/kernel/react'
+import { Spin } from 'antd'
+
+export default function Dashboard() {
+  return (
+    <PluginSlot
+      pluginName="user-dashboard"
+      url="https://cdn.example.com/plugins/user-dashboard.js"
+      styleUrls={["https://cdn.example.com/plugins/user-dashboard.css"]}
+      fallback={<Spin spinning>Loading Plugin...</Spin>}
+      renderError={(err, retry) => (
+        <div style={{ color: 'red' }}>
+          {err.message} <button onClick={retry}>重试</button>
+        </div>
+      )}
+    />
+  )
+}
+```
+
+## 原生使用 (非 React)
+
+对于 Vue 或原生 JS 开发者，可以直接使用核心加载器：
+
+```ts
+import { createKernel } from '@zero-bits/kernel'
+
+const kernel = createKernel()
+kernel.regSharedModule('vue', Vue)
+
+kernel.loadPlugin('my-vue-plugin', {
+  url: 'https://...',
+  styleUrls: ['https://...']
+}).then(mod => {
+  // mod.default 即为插件导出的根组件/函数
+  mod.default.mount('#app')
+})
+```
+
+## 核心 API
+
+### `createKernel(options?: KernelOptions)`
+
+创建并返回一个新的内核实例。
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `timeout` | `number` | `10000` | 加载超时时间（毫秒） |
+| `retryCount` | `number` | `2` | 网络失败自动重试次数 |
+| `namespace` | `string` | `'__SMART_HUB__'` | 全局拦截器的命名空间前缀 |
+| `debug` | `boolean` | `true` | 是否输出内核 warn/log |
+
+### `KernelInstance`
+
+- `regSharedModule(name, instance, options)`: 注册主应用的共享依赖。
+- `loadPlugin(pluginName, options)`: 请求加载远端插件。
+- `unloadPlugin(pluginName)`: 卸载并在内存中清除某插件记录。
+- `destroy()`: 销毁整个内核实例并回收内存。

package/dist/chunk-D4E5XKWD.js

@@ -0,0 +1,482 @@
+// src/core/types.ts
+var PluginError = class extends Error {
+  constructor(pluginName, message) {
+    super(message);
+    this.name = "PluginError";
+    this.pluginName = pluginName;
+  }
+};
+var PluginNetworkError = class extends PluginError {
+  constructor(pluginName, url, cause) {
+    super(pluginName, `[Kernel] \u63D2\u4EF6 [${pluginName}] \u7F51\u7EDC\u52A0\u8F7D\u5931\u8D25\uFF0CURL: ${url}`);
+    this.name = "PluginNetworkError";
+    if (cause) this.cause = cause;
+  }
+};
+var PluginTimeoutError = class extends PluginError {
+  constructor(pluginName, timeout) {
+    super(pluginName, `[Kernel] \u63D2\u4EF6 [${pluginName}] \u52A0\u8F7D\u8D85\u65F6\uFF08>${timeout}ms\uFF09`);
+    this.name = "PluginTimeoutError";
+  }
+};
+var PluginDependencyError = class extends PluginError {
+  constructor(pluginName, dependency) {
+    super(pluginName, `[Kernel] \u63D2\u4EF6 [${pluginName}] \u7F3A\u5C11\u4F9D\u8D56: [${dependency}]\uFF0C\u8BF7\u786E\u4FDD\u5DF2\u8C03\u7528 regSharedModule \u6CE8\u5165`);
+    this.name = "PluginDependencyError";
+    this.dependency = dependency;
+  }
+};
+var PluginExecutionError = class extends PluginError {
+  constructor(pluginName, cause) {
+    super(pluginName, `[Kernel] \u63D2\u4EF6 [${pluginName}] \u6267\u884C\u521D\u59CB\u5316\u5931\u8D25`);
+    this.name = "PluginExecutionError";
+    if (cause) this.cause = cause;
+  }
+};
+var KernelNotInitializedError = class extends Error {
+  constructor() {
+    super("[Kernel] \u5185\u6838\u5F15\u64CE\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 initKernel() \u6216 createKernel()");
+    this.name = "KernelNotInitializedError";
+  }
+};
+
+// src/core/core.ts
+function toPluginError(pluginName, err) {
+  if (err instanceof PluginError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new PluginError(pluginName, message);
+}
+function withTimeout(promise, ms, error) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(error), ms);
+  });
+  promise.catch(() => {
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+var Kernel = class {
+  /**
+   * 构造函数
+   * @param options 内核配置
+   * @default timeout: 10000
+   * @default retryCount: 2
+   * @default nonce: ''
+   * @default debug: true
+   * @default namespace: ''
+   * @default logger: console
+   * @default onLoadStart: () => {}
+   * @default onLoadSuccess: () => {}
+   * @default onLoadError: () => {}
+   */
+  constructor(options) {
+    this.modules = /* @__PURE__ */ new Map();
+    this.ownHandlers = /* @__PURE__ */ new Map();
+    this.initialized = false;
+    if (!options?.namespace) {
+      throw new Error("[SmartHub] \u5FC5\u987B\u914D\u7F6E namespace \u5168\u79F0 (\u4F8B\u5982: __SMART_HUB___DEFINE)");
+    }
+    this.logger = options?.logger || console;
+    this.config = {
+      timeout: options?.timeout ?? 1e4,
+      retryCount: options?.retryCount ?? 2,
+      nonce: options?.nonce ?? "",
+      debug: options?.debug ?? true,
+      namespace: options.namespace,
+      logger: this.logger,
+      onLoadStart: options?.onLoadStart ?? (() => {
+      }),
+      onLoadSuccess: options?.onLoadSuccess ?? (() => {
+      }),
+      onLoadError: options?.onLoadError ?? (() => {
+      })
+    };
+    this.initGlobalInterceptor();
+  }
+  /**
+   * 获取全局Pending Map
+   * @returns 全局Pending Map
+   */
+  get globalPendingMap() {
+    if (typeof window === "undefined") return void 0;
+    const defineFn = window[this.config.namespace];
+    return defineFn ? defineFn._pendingMap : void 0;
+  }
+  /**
+   * 获取全局资源并发锁
+   */
+  get globalLocks() {
+    if (typeof window === "undefined") return /* @__PURE__ */ new Map();
+    const nsLocks = `${this.config.namespace}_LOCKS`;
+    if (!window[nsLocks]) {
+      window[nsLocks] = /* @__PURE__ */ new Map();
+    }
+    return window[nsLocks];
+  }
+  /**
+   * 初始化全局拦截器
+   */
+  initGlobalInterceptor() {
+    if (typeof window === "undefined") return;
+    const ns = this.config.namespace;
+    if (!window[ns]) {
+      const defineFn = (pluginName, deps, factory) => {
+        const handlers = defineFn._pendingMap?.get(pluginName);
+        if (handlers && handlers.size > 0) {
+          handlers.forEach((handler) => handler(deps, factory));
+          handlers.clear();
+        } else {
+          console.warn(`[SmartHub] \u6536\u5230\u672A\u77E5\u7684\u63D2\u4EF6 [${pluginName}] define \u8C03\u7528`);
+        }
+      };
+      defineFn._pendingMap = /* @__PURE__ */ new Map();
+      window[ns] = defineFn;
+    }
+    this.initialized = true;
+  }
+  /**
+   * 判断内核是否已初始化
+   * @returns true 如果内核已初始化，否则 false
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+  /**
+   * 注册共享模块
+   * @param name 模块名称
+   * @param instance 模块实例
+   * @param options 模块配置
+   * @default force: false
+   */
+  regSharedModule(name, instance, options) {
+    if (this.modules.has(name) && !options?.force) {
+      if (this.config.debug) {
+        this.logger.warn(`[SmartHub] \u5171\u4EAB\u6A21\u5757 [${name}] \u5DF2\u6CE8\u518C\uFF0C\u5982\u9700\u8986\u76D6\u8BF7\u4F20\u5165 { force: true }`);
+      }
+      return;
+    }
+    this.modules.set(name, {
+      module: instance,
+      _promise: Promise.resolve(instance),
+      status: "resolved"
+    });
+  }
+  /**
+   * 注入脚本（带自毁机制与并发锁）
+   * @param url 脚本地址
+   * @param pluginName 插件名称
+   * @returns Promise对象
+   */
+  injectScript(url, pluginName) {
+    const locks = this.globalLocks;
+    if (locks.has(url)) return locks.get(url);
+    const promise = new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = url;
+      script.async = true;
+      if (this.config.nonce) script.nonce = this.config.nonce;
+      const cleanup = () => {
+        script.onload = null;
+        script.onerror = null;
+        locks.delete(url);
+        if (script.parentNode) script.parentNode.removeChild(script);
+      };
+      script.onload = () => {
+        cleanup();
+        resolve();
+      };
+      script.onerror = (event) => {
+        cleanup();
+        reject(new PluginNetworkError(pluginName, url, event));
+      };
+      document.head.appendChild(script);
+    });
+    locks.set(url, promise);
+    return promise;
+  }
+  /**
+   * 注入样式（带并发锁，防止 FOUC）
+   * @param url 样式地址
+   * @param pluginName 插件名称
+   * @returns Promise对象
+   */
+  injectStyle(url, pluginName) {
+    const locks = this.globalLocks;
+    if (locks.has(url)) return locks.get(url);
+    const existing = document.querySelector(`link[href="${url}"][rel="stylesheet"]`);
+    if (existing) return Promise.resolve();
+    const promise = new Promise((resolve, reject) => {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = url;
+      if (this.config.nonce) link.nonce = this.config.nonce;
+      const cleanup = () => {
+        link.onload = null;
+        link.onerror = null;
+        locks.delete(url);
+      };
+      link.onload = () => {
+        cleanup();
+        resolve();
+      };
+      link.onerror = (event) => {
+        cleanup();
+        if (link.parentNode) link.parentNode.removeChild(link);
+        reject(new PluginNetworkError(pluginName, url, event));
+      };
+      document.head.appendChild(link);
+    });
+    locks.set(url, promise);
+    return promise;
+  }
+  /**
+   * 带重试的函数执行器
+   * @param fn 需要执行的函数
+   * @param pluginName 插件名称
+   * @returns Promise对象
+   */
+  async withRetry(fn, pluginName) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.retryCount; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = err;
+        if (attempt < this.config.retryCount) {
+          await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
+          if (this.config.debug) {
+            this.logger.warn(`[SmartHub] \u63D2\u4EF6 [${pluginName}] \u7B2C ${attempt + 1} \u6B21\u91CD\u8BD5\u52A0\u8F7D...`);
+          }
+        }
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * 解析工厂函数（支持异步依赖树）
+   * @param pluginName 插件名称
+   * @param deps 依赖项
+   * @param factory 工厂函数
+   * @returns Promise对象
+   */
+  async resolveFactory(pluginName, deps, factory) {
+    let resolvedDeps;
+    try {
+      resolvedDeps = await Promise.all(deps.map((dep) => {
+        const entry = this.modules.get(dep);
+        if (!entry) throw new PluginDependencyError(pluginName, dep);
+        return entry._promise;
+      }));
+    } catch (err) {
+      throw err;
+    }
+    try {
+      return factory(...resolvedDeps);
+    } catch (err) {
+      throw new PluginExecutionError(pluginName, err);
+    }
+  }
+  /**
+   * 注册待处理函数
+   * @param pluginName 插件名称
+   * @returns Promise对象
+   */
+  registerPendingHandler(pluginName) {
+    const handler = (deps, factory) => {
+      const entry = this.modules.get(pluginName);
+      if (entry) entry._defineCalled = true;
+      this.resolveFactory(pluginName, deps, factory).then((mod) => {
+        const entry2 = this.modules.get(pluginName);
+        if (entry2) {
+          entry2.module = mod;
+          entry2.status = "resolved";
+          entry2._resolve?.(mod);
+        }
+      }).catch((err) => {
+        const entry2 = this.modules.get(pluginName);
+        if (entry2) {
+          entry2.status = "rejected";
+          entry2._reject?.(err);
+        }
+      });
+      this.ownHandlers.delete(pluginName);
+    };
+    const ns = this.config.namespace;
+    const defineFn = window[ns];
+    if (!defineFn) throw new Error(`[SmartHub] \u5168\u5C40\u62E6\u622A\u5668 ${ns} \u672A\u521D\u59CB\u5316`);
+    if (!defineFn._pendingMap) {
+      defineFn._pendingMap = /* @__PURE__ */ new Map();
+    }
+    const globalMap = defineFn._pendingMap;
+    if (!globalMap.has(pluginName)) {
+      globalMap.set(pluginName, /* @__PURE__ */ new Set());
+    }
+    globalMap.get(pluginName).add(handler);
+    this.ownHandlers.set(pluginName, handler);
+    return handler;
+  }
+  /**
+   * 加载插件
+   * @param pluginName 插件名称
+   * @param options 插件配置
+   * @returns Promise对象
+   */
+  async loadPlugin(pluginName, options) {
+    if (!this.initialized) throw new KernelNotInitializedError();
+    const url = typeof options === "string" ? options : options.url;
+    const styleUrls = typeof options === "string" ? [] : options.styleUrls || [];
+    const cached = this.modules.get(pluginName);
+    if (cached && (cached.status === "resolved" || cached.status === "pending") && cached.url === url) {
+      return cached._promise;
+    }
+    if (cached && cached.url !== url) this.unloadPlugin(pluginName);
+    this.config.onLoadStart(pluginName);
+    const deferred = createDeferred();
+    this.modules.set(pluginName, {
+      module: null,
+      _promise: deferred.promise,
+      _resolve: deferred.resolve,
+      _reject: deferred.reject,
+      status: "pending",
+      _defineCalled: false,
+      url
+    });
+    let handler;
+    try {
+      handler = this.registerPendingHandler(pluginName);
+      await this.withRetry(
+        () => withTimeout(
+          Promise.all([
+            this.injectScript(url, pluginName),
+            ...styleUrls.map((styleUrl) => this.injectStyle(styleUrl, pluginName))
+          ]),
+          this.config.timeout,
+          new PluginTimeoutError(pluginName, this.config.timeout)
+        ),
+        pluginName
+      );
+      const entry = this.modules.get(pluginName);
+      if (!entry._defineCalled) {
+        throw new PluginExecutionError(pluginName, `Plugin script loaded but ${this.config.namespace} was not called.`);
+      }
+      const mod = await withTimeout(
+        entry._promise,
+        this.config.timeout,
+        new PluginTimeoutError(pluginName, this.config.timeout)
+      );
+      this.config.onLoadSuccess(pluginName);
+      return mod;
+    } catch (err) {
+      this.globalPendingMap?.get(pluginName)?.delete(handler);
+      this.ownHandlers.delete(pluginName);
+      const entry = this.modules.get(pluginName);
+      if (entry) {
+        entry.status = "rejected";
+        entry._reject?.(err);
+      }
+      const pluginErr = toPluginError(pluginName, err);
+      this.config.onLoadError(pluginName, pluginErr);
+      throw pluginErr;
+    }
+  }
+  /**
+   * 卸载插件
+   * @param pluginName 插件名称
+   */
+  unloadPlugin(pluginName) {
+    this.modules.delete(pluginName);
+    const handler = this.ownHandlers.get(pluginName);
+    if (handler) {
+      this.globalPendingMap?.get(pluginName)?.delete(handler);
+      this.ownHandlers.delete(pluginName);
+    }
+  }
+  /**
+   * 预加载远端插件资源到浏览器缓存（不执行）
+   * @param options 插件地址或配置
+   */
+  preloadPlugin(options) {
+    if (typeof document === "undefined") return;
+    const url = typeof options === "string" ? options : options.url;
+    const styleUrls = typeof options === "string" ? [] : options.styleUrls || [];
+    const preloadResource = (href, as) => {
+      if (document.querySelector(`link[href="${href}"][rel="preload"]`)) return;
+      const link = document.createElement("link");
+      link.rel = "preload";
+      link.href = href;
+      link.as = as;
+      if (this.config.nonce) link.nonce = this.config.nonce;
+      document.head.appendChild(link);
+    };
+    if (url) preloadResource(url, "script");
+    styleUrls.forEach((styleUrl) => preloadResource(styleUrl, "style"));
+  }
+  /**
+   * 销毁内核实例
+   */
+  destroy() {
+    this.ownHandlers.forEach((handler, pluginName) => {
+      this.globalPendingMap?.get(pluginName)?.delete(handler);
+    });
+    this.ownHandlers.clear();
+    this.modules.clear();
+    this.initialized = false;
+  }
+};
+function createKernel(options) {
+  return new Kernel(options);
+}
+
+// src/core/index.ts
+var globalKernel = null;
+function initKernel(options) {
+  if (globalKernel) return console.warn("[SmartHub] initKernel() \u5DF2\u6267\u884C\u8FC7\uFF0C\u8BF7\u52FF\u91CD\u590D\u8C03\u7528");
+  globalKernel = createKernel(options);
+}
+function regSharedModule(name, instance, options) {
+  if (!globalKernel) {
+    console.warn(`[SmartHub] \u5168\u5C40\u5185\u6838\u672A\u521D\u59CB\u5316\uFF0C\u81EA\u52A8\u4EE5\u9ED8\u8BA4\u914D\u7F6E\u521D\u59CB\u5316...`);
+    globalKernel = createKernel();
+  }
+  globalKernel.regSharedModule(name, instance, options);
+}
+async function loadRemotePlugin(pluginName, options) {
+  if (!globalKernel) {
+    throw new Error("[SmartHub] \u5185\u6838\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 initKernel()");
+  }
+  return globalKernel.loadPlugin(pluginName, options);
+}
+function preloadRemotePlugin(options) {
+  if (!globalKernel) {
+    console.warn("[SmartHub] \u5168\u5C40\u5185\u6838\u672A\u521D\u59CB\u5316\uFF0C\u81EA\u52A8\u4EE5\u9ED8\u8BA4\u914D\u7F6E\u521D\u59CB\u5316...");
+    globalKernel = createKernel();
+  }
+  globalKernel.preloadPlugin(options);
+}
+function getGlobalKernel() {
+  return globalKernel;
+}
+
+export {
+  PluginError,
+  PluginNetworkError,
+  PluginTimeoutError,
+  PluginDependencyError,
+  PluginExecutionError,
+  KernelNotInitializedError,
+  createKernel,
+  initKernel,
+  regSharedModule,
+  loadRemotePlugin,
+  preloadRemotePlugin,
+  getGlobalKernel
+};