@fulgurjs/federation 5.2.5 → 5.3.0

package/dist/bridge-core.d.ts

@@ -0,0 +1,51 @@
+import { AppContext } from './context.js';
+
+/** 子应用桥接契约（远程 ./bridge 模块的默认导出；任务书 §3.2） */
+interface BridgeApp {
+    /** 首次根提交完成时才算挂载成功；同一容器未卸载前重复 mount 是契约违例 */
+    mount(el: HTMLElement, props?: Record<string, unknown>): void | Promise<void>;
+    /** 同步使当前挂载代次失效并清理已创建的 root；未知容器为 no-op */
+    unmount(el: HTMLElement): void;
+}
+/** 远程模块 → 契约校验（默认导出须含函数类型的 mount/unmount，否则 MFU-015） */
+declare function assertBridgeContract(spec: string, mod: unknown): BridgeApp;
+/**
+ * 登记一个受控会话代次；页面已有不同 sessionKey 的活跃桥接实例时拒绝（MFU-017）。
+ * 同一会话的多实例并存合法（计数递增）。
+ */
+declare function acquireBridgeSession(spec: string, sessionKey: string): void;
+/** 释放一个受控会话代次（unmount/换代/失败清理时调用；幂等） */
+declare function releaseBridgeSession(sessionKey: string): void;
+interface BridgeContextResolution {
+    /** 校验通过后需要由桥接层写入全局的快照；undefined = 复用现有 AppContext，无需写入 */
+    provide?: Partial<AppContext> & Record<string, unknown>;
+}
+/**
+ * 挂载前校验会话与上下文快照（同步、无副作用；只在全部通过后由调用方 provide）。
+ *
+ * - getter 抛错/返回非对象/thenable → MFU-016（phase: getContext）；
+ * - 受控 sessionKey 与快照或现有 AppContext 不一致 → MFU-017（不写任何全局状态）；
+ * - 新会话（与全局当前 sessionKey 不同）先 clearAppContext 清旧账号残留，
+ *   避免 provideAppContext 顶层 merge 留下旧账号独有字段（BR06）。
+ *
+ * 会话登记（acquireBridgeSession/releaseBridgeSession）由宿主适配器在代次边界管理，
+ * 本函数不重复登记——重试同会话不得叠加计数。
+ *
+ * controlled 语义：非空字符串 = 受控校验；undefined = 不启用受控校验（快照照常提供，
+ * 远程 onSession 由 runtime 按 AppContext.sessionKey 判定）；null 由调用方先行短路。
+ */
+declare function resolveBridgeContext(spec: string, controlled: string | undefined, getContext: (() => Partial<AppContext> & Record<string, unknown>) | undefined): BridgeContextResolution;
+/** 受控 sessionKey 受控值合法性：只接受 undefined / null / 非空字符串（任务书 BN10） */
+declare function assertControlledSessionKey(spec: string, value: unknown): void;
+/** 适配层参数校验（与 vue/react 适配器同口径：retries 0-10 整数、timeout 正有限数） */
+declare function assertBridgeOptions(source: string, opts: {
+    retries?: number;
+    timeout?: number;
+}): void;
+/**
+ * 桥接加载等待上限（与 React remoteComponent.timeout 同语义）：
+ * 只结束本次等待，不取消已发出的共享 loadRemote 请求；迟到的成功/失败一律丢弃。
+ */
+declare function withBridgeTimeout<T>(p: Promise<T>, ms: number, spec: string): Promise<T>;
+
+export { type BridgeApp, type BridgeContextResolution, acquireBridgeSession, assertBridgeContract, assertBridgeOptions, assertControlledSessionKey, releaseBridgeSession, resolveBridgeContext, withBridgeTimeout };

package/dist/bridge-core.js

@@ -0,0 +1,21 @@
+import {
+  acquireBridgeSession,
+  assertBridgeContract,
+  assertBridgeOptions,
+  assertControlledSessionKey,
+  releaseBridgeSession,
+  resolveBridgeContext,
+  withBridgeTimeout
+} from "./chunk-LWJBHUJQ.js";
+import "./chunk-E55P4TIY.js";
+import "./chunk-TSYLDY6H.js";
+import "./chunk-OF2JCXTZ.js";
+export {
+  acquireBridgeSession,
+  assertBridgeContract,
+  assertBridgeOptions,
+  assertControlledSessionKey,
+  releaseBridgeSession,
+  resolveBridgeContext,
+  withBridgeTimeout
+};

package/dist/bridge-errors.cjs

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bridge-errors.ts
+var bridge_errors_exports = {};
+__export(bridge_errors_exports, {
+  BridgeErrorCodes: () => BridgeErrorCodes,
+  bridgeLifecycleError: () => bridgeLifecycleError,
+  bridgeSessionMismatchError: () => bridgeSessionMismatchError,
+  invalidBridgeContractError: () => invalidBridgeContractError,
+  invalidSessionKeyError: () => invalidSessionKeyError
+});
+module.exports = __toCommonJS(bridge_errors_exports);
+
+// src/runtime/errors.ts
+var FgError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details, options) {
+    super(`[fulgurjs:${code}] ${message}`, options);
+    this.name = "FgError";
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/bridge-errors.ts
+var BridgeErrorCodes = {
+  /** 桥接契约非法（./bridge 默认导出缺 mount/unmount 或不是函数） */
+  BRIDGE_INVALID_CONTRACT: "MFU-015",
+  /** 桥接准备或生命周期失败（details.phase = getContext | mount | unmount） */
+  BRIDGE_LIFECYCLE_FAILED: "MFU-016",
+  /** 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾） */
+  BRIDGE_SESSION_MISMATCH: "MFU-017"
+};
+function invalidBridgeContractError(spec, mod) {
+  const actual = mod === null ? "null" : typeof mod;
+  const missing = [];
+  if (typeof mod?.mount !== "function") missing.push("mount");
+  if (typeof mod?.unmount !== "function") missing.push("unmount");
+  return new FgError(
+    BridgeErrorCodes.BRIDGE_INVALID_CONTRACT,
+    `\u73B0\u8C61\uFF1A\u8FDC\u7A0B\u6A21\u5757 "${spec}" \u7684\u9ED8\u8BA4\u5BFC\u51FA\u4E0D\u662F\u5408\u6CD5\u7684\u6865\u63A5\u5951\u7EA6\uFF08BridgeApp\uFF09\u3002
+  \u6839\u56E0: \u5BFC\u51FA\u503C\u4E3A ${actual}` + (missing.length ? `\uFF0C\u7F3A\u5C11\u51FD\u6570\u7C7B\u578B\u7684 ${missing.map((m) => `"${m}"`).join(" / ")} \u5BFC\u51FA\u3002` : "\u3002") + `
+  \u4FEE\u6CD5: \u8FDC\u7A0B\u4FA7\u7528 defineBridgeApp(...) \u521B\u5EFA\u5951\u7EA6\u5E76\u4F5C\u4E3A\u6A21\u5757\u9ED8\u8BA4\u5BFC\u51FA\u2014\u2014
+        Vue \u5B50\u5E94\u7528: import { defineBridgeApp } from '@fulgurjs/federation/runtime'\uFF1B
+        React \u5B50\u5E94\u7528: import { defineBridgeApp } from '@fulgurjs/federation/react'\u3002
+        \u5951\u7EA6\u5FC5\u987B\u5305\u542B mount(el, props?) \u4E0E unmount(el) \u4E24\u4E2A\u51FD\u6570\u3002`,
+    { spec, missing, actual }
+  );
+}
+function bridgeLifecycleError(phase, spec, cause, extra) {
+  const raw = cause instanceof Error ? cause.message : String(cause ?? "unknown");
+  const fixes = {
+    getContext: "\u4FEE\u6CD5: \u2460 getContext \u5FC5\u987B\u662F\u540C\u6B65\u3001\u65E0\u526F\u4F5C\u7528\u7684 getter\uFF08\u4E0D\u5F97\u8FD4\u56DE Promise/thenable\uFF09\uFF1B\n        \u2461 \u8FD4\u56DE\u503C\u987B\u662F\u5305\u542B\u672C\u6B21\u4F1A\u8BDD\u5FEB\u7167\u7684\u5BF9\u8C61\uFF08\u53D7\u63A7 sessionKey \u65F6\u987B\u542B\u76F8\u540C sessionKey\uFF09\uFF1B\n        \u2462 \u5F02\u6B65\u83B7\u53D6\u7528\u6237\u8D44\u6599\u8BF7\u5728\u5BBF\u4E3B\u5B8C\u6210\u540E\u518D\u8BA9\u6865\u63A5\u7EC4\u4EF6\u8FDB\u5165\u53EF\u6302\u8F7D\u72B6\u6001\u3002",
+    mount: "\u4FEE\u6CD5: \u2460 \u67E5\u770B\u6839\u56E0\u4E2D\u5B50\u5E94\u7528 mount \u7684\u539F\u59CB\u9519\u8BEF\uFF08\u5DE5\u5382\u629B\u9519\u6216\u9996\u6B21\u6E32\u67D3\u5931\u8D25\uFF09\uFF1B\n        \u2461 \u540C\u4E00\u5BB9\u5668\u672A\u5378\u8F7D\u524D\u91CD\u590D mount \u662F\u5951\u7EA6\u8FDD\u4F8B\u2014\u2014\u5148 unmount \u518D mount\uFF1B\n        \u2462 \u4FEE\u590D\u540E\u70B9\u51FB\u300C\u91CD\u8BD5\u52A0\u8F7D\u300D\u5728\u540C\u9875\u91CD\u5EFA\u6302\u8F7D\u3002",
+    unmount: "\u4FEE\u6CD5: \u2460 \u6839\u56E0\u6765\u81EA\u5B50\u5E94\u7528 unmount \u5B9E\u73B0\uFF08app.unmount/root.unmount \u629B\u9519\uFF09\uFF1B\n        \u2461 \u8BE5\u5BB9\u5668\u6E05\u7406\u72B6\u6001\u4E0D\u786E\u5B9A\u2014\u2014\u4E0D\u8981\u76F4\u63A5\u5728\u540C\u4E00 el \u4E0A\u542F\u52A8\u65B0\u5B9E\u4F8B\uFF1B\n        \u2462 \u5237\u65B0\u9875\u9762\u53EF\u5F7B\u5E95\u6E05\u7406\uFF0C\u6B8B\u7559\u8D44\u6E90\u8BF7\u5982\u5B9E\u6392\u67E5\uFF08\u4E8B\u4EF6\u8BA2\u9605/\u5B9A\u65F6\u5668/\u5168\u5C40\u526F\u4F5C\u7528\uFF09\u3002"
+  };
+  return new FgError(
+    BridgeErrorCodes.BRIDGE_LIFECYCLE_FAILED,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 ${phase} \u9636\u6BB5\u5931\u8D25\u3002
+  \u6839\u56E0: ${raw}
+` + fixes[phase],
+    { phase, spec, cause: String(raw), ...extra },
+    { cause }
+  );
+}
+function bridgeSessionMismatchError(spec, controlled, actual, extra) {
+  const actualText = actual === void 0 ? "undefined\uFF08\u9875\u9762\u5C1A\u65E0 AppContext\uFF09" : typeof actual === "string" ? `"${actual}"` : String(actual);
+  return new FgError(
+    BridgeErrorCodes.BRIDGE_SESSION_MISMATCH,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684\u53D7\u63A7 sessionKey\uFF08"${controlled}"\uFF09\u4E0E\u5F53\u524D\u4F1A\u8BDD\u4E0D\u4E00\u81F4\uFF08\u5F53\u524D ${actualText}\uFF09\u3002
+  \u6839\u56E0: AppContext \u662F\u9875\u9762\u7EA7\u5355\u4F8B\uFF0C\u540C\u9875\u6240\u6709\u6865\u63A5\u5B9E\u4F8B\u5FC5\u987B\u4F7F\u7528\u540C\u4E00\u767B\u5F55\u4EE3\u6B21\uFF1B
+        getContext \u5FEB\u7167\u7684 sessionKey\uFF08\u6216\u73B0\u6709 AppContext \u7684 sessionKey\uFF09\u4E0E\u53D7\u63A7\u503C\u4E0D\u540C\u3002
+  \u4FEE\u6CD5: \u2460 \u6362\u8D26\u53F7\u65F6\u5148\u8BA9\u53D7\u63A7 prop \u7F6E null \u5E76\u7B49\u5F85\u5378\u8F7D\uFF0C\u518D clearAppContext() \u6E05\u65E7\u8D26\u53F7\u3001
+        \u51C6\u5907\u65B0\u8D26\u53F7\u5B8C\u6574\u5FEB\u7167\u540E\u66F4\u65B0\u53D7\u63A7 prop\uFF1B
+        \u2461 \u65E0 getContext \u65F6\uFF0C\u5148\u7531\u5BBF\u4E3B\u6865 provideAppContext({...\u65B0\u4F1A\u8BDD, sessionKey}) \u518D\u6302\u8F7D\uFF1B
+        \u2462 \u540C\u9875\u4E0D\u8981\u540C\u65F6\u6302\u8F7D\u4E0D\u540C\u8D26\u53F7\u7684\u6865\u63A5\u5B9E\u4F8B\uFF08\u9875\u9762\u7EA7\u5355\u4F1A\u8BDD\u7EA6\u675F\uFF09\u3002`,
+    { spec, controlled, actual: String(actual), ...extra }
+  );
+}
+function invalidSessionKeyError(spec, value) {
+  return new FgError(
+    BridgeErrorCodes.BRIDGE_SESSION_MISMATCH,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u6536\u5230\u975E\u6CD5\u7684\u53D7\u63A7 sessionKey\uFF1A${typeof value === "string" ? '\u7A7A\u5B57\u7B26\u4E32 ""' : `${typeof value}\uFF08${String(value)}\uFF09`}\u3002
+  \u6839\u56E0: sessionKey \u53EA\u63A5\u53D7 undefined\uFF08\u4E0D\u542F\u7528\u53D7\u63A7\u4F1A\u8BDD\uFF09\u3001null\uFF08\u767B\u51FA\u6001\uFF09\u6216\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u767B\u5F55\u4EE3\u6B21 ID\uFF09\u3002
+  \u4FEE\u6CD5: \u767B\u51FA\u4F20 null \u800C\u4E0D\u662F\u7A7A\u5B57\u7B26\u4E32\uFF1B\u767B\u5F55\u4EE3\u6B21\u7528\u975E\u7A7A\u5B57\u7B26\u4E32\uFF1B\u4E0D\u8981\u4F20\u6570\u5B57/\u5E03\u5C14\u7B49\u5176\u4ED6\u7C7B\u578B\u3002`,
+    { spec, value: String(value) }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BridgeErrorCodes,
+  bridgeLifecycleError,
+  bridgeSessionMismatchError,
+  invalidBridgeContractError,
+  invalidSessionKeyError
+});

package/dist/bridge-errors.d.cts

@@ -0,0 +1,36 @@
+/** 统一错误码体系（对齐 webpack ScriptExternalLoadError 等运行时错误的可诊断性） */
+declare class FgError extends Error {
+    code: string;
+    details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>, options?: ErrorOptions);
+}
+
+/**
+ * 桥接层错误码表（MFU-015/016/017，任务书 D3）。
+ *
+ * 与 runtime.js 解耦：桥接专用分支不进内核 bundle（runtime 内核零改动为首选目标）；
+ * 码值登记于 src/diagnostics.ts 的 CODE_REGISTRY，由 scripts/check-manual-codes.mjs
+ * 做「源码定义 ⊆ 登记表 = README 错误码总表」三方一致性校验。
+ * 三段式口径与 runtime/context 一致：现象 → 根因 → 修法。
+ */
+
+declare const BridgeErrorCodes: {
+    /** 桥接契约非法（./bridge 默认导出缺 mount/unmount 或不是函数） */
+    readonly BRIDGE_INVALID_CONTRACT: "MFU-015";
+    /** 桥接准备或生命周期失败（details.phase = getContext | mount | unmount） */
+    readonly BRIDGE_LIFECYCLE_FAILED: "MFU-016";
+    /** 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾） */
+    readonly BRIDGE_SESSION_MISMATCH: "MFU-017";
+};
+/** 桥接生命周期阶段（MFU-016 details.phase 取值） */
+type BridgePhase = 'getContext' | 'mount' | 'unmount';
+/** MFU-015：远程 ./bridge 默认导出不是合法契约对象 */
+declare function invalidBridgeContractError(spec: string, mod: unknown): FgError;
+/** MFU-016：桥接准备（getContext）或生命周期（mount/unmount）失败；cause 保留原始错误 */
+declare function bridgeLifecycleError(phase: BridgePhase, spec: string, cause: unknown, extra?: Record<string, unknown>): FgError;
+/** MFU-017：受控 sessionKey 与当前 AppContext / 活跃桥接会话不一致 */
+declare function bridgeSessionMismatchError(spec: string, controlled: string, actual: unknown, extra?: Record<string, unknown>): FgError;
+/** MFU-017：受控 sessionKey 值本身非法（空字符串/数字等，非 undefined/null/非空字符串） */
+declare function invalidSessionKeyError(spec: string, value: unknown): FgError;
+
+export { BridgeErrorCodes, type BridgePhase, bridgeLifecycleError, bridgeSessionMismatchError, invalidBridgeContractError, invalidSessionKeyError };

package/dist/bridge-errors.d.ts

@@ -0,0 +1,36 @@
+/** 统一错误码体系（对齐 webpack ScriptExternalLoadError 等运行时错误的可诊断性） */
+declare class FgError extends Error {
+    code: string;
+    details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>, options?: ErrorOptions);
+}
+
+/**
+ * 桥接层错误码表（MFU-015/016/017，任务书 D3）。
+ *
+ * 与 runtime.js 解耦：桥接专用分支不进内核 bundle（runtime 内核零改动为首选目标）；
+ * 码值登记于 src/diagnostics.ts 的 CODE_REGISTRY，由 scripts/check-manual-codes.mjs
+ * 做「源码定义 ⊆ 登记表 = README 错误码总表」三方一致性校验。
+ * 三段式口径与 runtime/context 一致：现象 → 根因 → 修法。
+ */
+
+declare const BridgeErrorCodes: {
+    /** 桥接契约非法（./bridge 默认导出缺 mount/unmount 或不是函数） */
+    readonly BRIDGE_INVALID_CONTRACT: "MFU-015";
+    /** 桥接准备或生命周期失败（details.phase = getContext | mount | unmount） */
+    readonly BRIDGE_LIFECYCLE_FAILED: "MFU-016";
+    /** 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾） */
+    readonly BRIDGE_SESSION_MISMATCH: "MFU-017";
+};
+/** 桥接生命周期阶段（MFU-016 details.phase 取值） */
+type BridgePhase = 'getContext' | 'mount' | 'unmount';
+/** MFU-015：远程 ./bridge 默认导出不是合法契约对象 */
+declare function invalidBridgeContractError(spec: string, mod: unknown): FgError;
+/** MFU-016：桥接准备（getContext）或生命周期（mount/unmount）失败；cause 保留原始错误 */
+declare function bridgeLifecycleError(phase: BridgePhase, spec: string, cause: unknown, extra?: Record<string, unknown>): FgError;
+/** MFU-017：受控 sessionKey 与当前 AppContext / 活跃桥接会话不一致 */
+declare function bridgeSessionMismatchError(spec: string, controlled: string, actual: unknown, extra?: Record<string, unknown>): FgError;
+/** MFU-017：受控 sessionKey 值本身非法（空字符串/数字等，非 undefined/null/非空字符串） */
+declare function invalidSessionKeyError(spec: string, value: unknown): FgError;
+
+export { BridgeErrorCodes, type BridgePhase, bridgeLifecycleError, bridgeSessionMismatchError, invalidBridgeContractError, invalidSessionKeyError };

package/dist/bridge-errors.js

@@ -0,0 +1,15 @@
+import {
+  BridgeErrorCodes,
+  bridgeLifecycleError,
+  bridgeSessionMismatchError,
+  invalidBridgeContractError,
+  invalidSessionKeyError
+} from "./chunk-E55P4TIY.js";
+import "./chunk-OF2JCXTZ.js";
+export {
+  BridgeErrorCodes,
+  bridgeLifecycleError,
+  bridgeSessionMismatchError,
+  invalidBridgeContractError,
+  invalidSessionKeyError
+};

package/dist/bridge-host-react-C55RmGll.d.ts

@@ -0,0 +1,35 @@
+import { ReactNode } from 'react';
+import { A as AppContext } from './bridge-core-6uLJiMVa.js';
+
+/**
+ * React 宿主桥接工厂（/bridge、/bridge/react 导出 createReactBridgeApp；任务书 §3.4）。
+ *
+ * 定位：接收注入的 loadRemote（不静态引用运行时内核，dist 壳绑定），返回
+ * `ComponentType<{ appProps: P; sessionKey?: string | null }>`，负责：
+ * - DOM 所有权（§4.5）：只创建并保持稳定的空挂载 el（fragment 的固定子节点）；
+ *   pending/error 占位是它的兄弟节点，宿主重渲染不 patch 子应用 root 内部；
+ * - 会话代次（§4.3）：受控 sessionKey 驱动 挂载/换会话/登出；同会话重渲染不重挂；
+ * - StrictMode 安全（§4.5）：双 effect 走 cleanup(作废+卸载)→setup(新代次) 顺序，
+ *   顺序 unmount/mount 不产生双实例或残留；
+ * - unmount 抛错（BN09）：报告 MFU-016（phase: unmount）并封锁该容器的新挂载。
+ *
+ * appProps 是挂载时浅拷贝快照（顶层替换不追踪，重挂由 key 重建）；sessionKey
+ * 是桥接控制参数，不混入业务 props。
+ */
+
+/** 渲染函数形态的错误占位：(error, retry) => ReactNode */
+type BridgeErrorFallback = (error: unknown, retry: () => void) => ReactNode;
+interface ReactBridgeAppOptions {
+    /** 加载 pending 占位（默认 null） */
+    fallback?: ReactNode;
+    /** 加载/挂载失败占位；默认内置中文诊断 + 「重试加载 / 刷新页面重试」 */
+    error?: ReactNode | BridgeErrorFallback;
+    /** 透传现行 loadRemote 的重试选项（0-10 整数），不另叠自动重试 */
+    retries?: number;
+    /** 本次桥接加载等待上限 ms；不取消已发出的共享请求，迟到结果一律丢弃 */
+    timeout?: number;
+    /** 无副作用的同步 getter：首次、重试及换会话的实际加载前返回本次所需上下文快照 */
+    getContext?: () => Partial<AppContext> & Record<string, unknown>;
+}
+
+export type { BridgeErrorFallback as B, ReactBridgeAppOptions as R };