@fulgurjs/federation 5.2.4 → 5.3.0

package/dist/bridge-app-react.js

@@ -0,0 +1,115 @@
+import {
+  bridgeLifecycleError
+} from "./chunk-E55P4TIY.js";
+import "./chunk-OF2JCXTZ.js";
+
+// src/bridge-app-react.ts
+import { Component, createElement, useEffect } from "react";
+var entriesByEl = /* @__PURE__ */ new WeakMap();
+var FirstCommitGate = class extends Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error) {
+    this.props.onError(error);
+    if (this.props.phaseRef.current === "committed") throw error;
+  }
+  render() {
+    if (this.props.phaseRef.current === "committed") return this.props.children;
+    return this.state.error === null ? this.props.children : null;
+  }
+};
+function CommitProbe({ children, onCommit }) {
+  useEffect(() => {
+    onCommit();
+  }, []);
+  return children ?? null;
+}
+function defineBridgeApp(factory) {
+  return {
+    mount(el, props) {
+      if (entriesByEl.has(el)) {
+        throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
+          reason: "container-occupied"
+        });
+      }
+      const snapshot = { ...props ?? {} };
+      let element;
+      try {
+        element = factory(snapshot);
+      } catch (e) {
+        throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
+      }
+      if (element === null || typeof element !== "object") {
+        throw bridgeLifecycleError(
+          "mount",
+          "bridge",
+          `defineBridgeApp \u5DE5\u5382\u8FD4\u56DE\u503C\u4E0D\u662F ReactElement\uFF08\u5F53\u524D ${element === null ? "null" : typeof element}\uFF09\u3002`
+        );
+      }
+      const entry = { status: "pending" };
+      entriesByEl.set(el, entry);
+      const promise = (async () => {
+        const reactDomClient = await import("react-dom/client");
+        if (entry.status === "abort" || entriesByEl.get(el) !== entry) return;
+        const root = reactDomClient.createRoot(el);
+        entry.root = root;
+        entry.status = "live";
+        const phaseRef = { current: "pending" };
+        await new Promise((resolve, reject) => {
+          let settled = false;
+          const onError = (e) => {
+            if (settled) return;
+            settled = true;
+            reject(bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e)));
+          };
+          const onCommit = () => {
+            if (settled) return;
+            settled = true;
+            phaseRef.current = "committed";
+            resolve();
+          };
+          root.render(
+            createElement(
+              FirstCommitGate,
+              { onError, phaseRef },
+              createElement(CommitProbe, { onCommit, children: element })
+            )
+          );
+        });
+      })();
+      return promise.then(
+        void 0,
+        (e) => {
+          if (entry.root && entry.status === "live") {
+            try {
+              entry.root.unmount();
+            } catch {
+            }
+          }
+          if (entriesByEl.get(el) === entry) entriesByEl.delete(el);
+          throw e;
+        }
+      ).then(() => void 0);
+    },
+    unmount(el) {
+      const entry = entriesByEl.get(el);
+      if (!entry) return;
+      entriesByEl.delete(el);
+      if (entry.status === "pending" || !entry.root) {
+        entry.status = "abort";
+        return;
+      }
+      entry.status = "abort";
+      try {
+        entry.root.unmount();
+      } catch (e) {
+        throw bridgeLifecycleError("unmount", "bridge", e instanceof Error ? e : String(e));
+      }
+    }
+  };
+}
+export {
+  defineBridgeApp
+};

package/dist/bridge-app-vue.cjs

@@ -0,0 +1,111 @@
+"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-app-vue.ts
+var bridge_app_vue_exports = {};
+__export(bridge_app_vue_exports, {
+  defineBridgeApp: () => defineBridgeApp
+});
+module.exports = __toCommonJS(bridge_app_vue_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 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 }
+  );
+}
+
+// src/bridge-app-vue.ts
+var appsByEl = /* @__PURE__ */ new WeakMap();
+function defineBridgeApp(factory) {
+  return {
+    mount(el, props) {
+      if (appsByEl.has(el)) {
+        throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
+          reason: "container-occupied"
+        });
+      }
+      const snapshot = { ...props ?? {} };
+      let app;
+      try {
+        app = factory(snapshot);
+        if (!app || typeof app.mount !== "function" || typeof app.unmount !== "function") {
+          throw new Error(
+            `defineBridgeApp \u5DE5\u5382\u8FD4\u56DE\u503C\u4E0D\u662F VueApp\uFF08\u5F53\u524D ${app === null ? "null" : typeof app}\uFF09\uFF1B\u5DE5\u5382\u5FC5\u987B\u8FD4\u56DE createApp(...) \u521B\u5EFA\u7684\u5E94\u7528\u5B9E\u4F8B\u3002`
+          );
+        }
+        app.mount(el);
+      } catch (e) {
+        if (app) {
+          try {
+            app.unmount();
+          } catch {
+          }
+        }
+        throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
+      }
+      appsByEl.set(el, app);
+    },
+    unmount(el) {
+      const app = appsByEl.get(el);
+      if (!app) return;
+      appsByEl.delete(el);
+      try {
+        app.unmount();
+      } catch (e) {
+        throw bridgeLifecycleError("unmount", "bridge", e instanceof Error ? e : String(e));
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineBridgeApp
+});

package/dist/bridge-app-vue.d.cts

@@ -0,0 +1,34 @@
+import { App } from 'vue';
+import { BridgeApp } from './bridge-core.cjs';
+import './context.cjs';
+
+/**
+ * Vue 子应用桥接适配（/runtime 导出 defineBridgeApp；任务书 §3.3 D1/D2）。
+ *
+ * 工厂形态：接收 props 快照，返回已装配完整的 VueApp（router/pinia 等由子应用自行装配）；
+ * helper 负责 app.mount(el) / app.unmount() 与按容器 el 的实例跟踪。
+ *
+ * 契约语义（§3.2）：
+ * - 契约实例按容器 el 分键（WeakMap）：同一契约多处挂载互不干扰；
+ * - 同一容器未卸载再次 mount → MFU-016（phase: mount，容器已被占用）且不覆盖原实例；
+ * - Vue 的 app.mount 同步完成首次渲染，mount 成功即返回 void（首次根提交语义由 Vue 保证）；
+ * - mount 抛错时清理已创建的 app（best-effort unmount），不留半挂状态；
+ * - unmount 未知容器为 no-op；unmount 抛错包装为 MFU-016（phase: unmount）由宿主捕获。
+ *
+ * 本文件零 React：/runtime 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
+ */
+
+/** Vue 子应用工厂：接收挂载时 props 快照，返回装配完成的 VueApp */
+type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
+/**
+ * 定义 Vue 子应用的桥接契约（远程 ./bridge 模块默认导出）。
+ *
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { defineBridgeApp } from '@fulgurjs/federation/runtime'
+ * export default defineBridgeApp((props) => { const app = createApp(App, props); app.use(router); return app })
+ * ```
+ */
+declare function defineBridgeApp(factory: VueBridgeAppFactory): BridgeApp;
+
+export { BridgeApp, type VueBridgeAppFactory, defineBridgeApp };

package/dist/bridge-app-vue.d.ts

@@ -0,0 +1,34 @@
+import { App } from 'vue';
+import { BridgeApp } from './bridge-core.js';
+import './context.js';
+
+/**
+ * Vue 子应用桥接适配（/runtime 导出 defineBridgeApp；任务书 §3.3 D1/D2）。
+ *
+ * 工厂形态：接收 props 快照，返回已装配完整的 VueApp（router/pinia 等由子应用自行装配）；
+ * helper 负责 app.mount(el) / app.unmount() 与按容器 el 的实例跟踪。
+ *
+ * 契约语义（§3.2）：
+ * - 契约实例按容器 el 分键（WeakMap）：同一契约多处挂载互不干扰；
+ * - 同一容器未卸载再次 mount → MFU-016（phase: mount，容器已被占用）且不覆盖原实例；
+ * - Vue 的 app.mount 同步完成首次渲染，mount 成功即返回 void（首次根提交语义由 Vue 保证）；
+ * - mount 抛错时清理已创建的 app（best-effort unmount），不留半挂状态；
+ * - unmount 未知容器为 no-op；unmount 抛错包装为 MFU-016（phase: unmount）由宿主捕获。
+ *
+ * 本文件零 React：/runtime 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
+ */
+
+/** Vue 子应用工厂：接收挂载时 props 快照，返回装配完成的 VueApp */
+type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
+/**
+ * 定义 Vue 子应用的桥接契约（远程 ./bridge 模块默认导出）。
+ *
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { defineBridgeApp } from '@fulgurjs/federation/runtime'
+ * export default defineBridgeApp((props) => { const app = createApp(App, props); app.use(router); return app })
+ * ```
+ */
+declare function defineBridgeApp(factory: VueBridgeAppFactory): BridgeApp;
+
+export { BridgeApp, type VueBridgeAppFactory, defineBridgeApp };

package/dist/bridge-app-vue.js

@@ -0,0 +1,51 @@
+import {
+  bridgeLifecycleError
+} from "./chunk-E55P4TIY.js";
+import "./chunk-OF2JCXTZ.js";
+
+// src/bridge-app-vue.ts
+var appsByEl = /* @__PURE__ */ new WeakMap();
+function defineBridgeApp(factory) {
+  return {
+    mount(el, props) {
+      if (appsByEl.has(el)) {
+        throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
+          reason: "container-occupied"
+        });
+      }
+      const snapshot = { ...props ?? {} };
+      let app;
+      try {
+        app = factory(snapshot);
+        if (!app || typeof app.mount !== "function" || typeof app.unmount !== "function") {
+          throw new Error(
+            `defineBridgeApp \u5DE5\u5382\u8FD4\u56DE\u503C\u4E0D\u662F VueApp\uFF08\u5F53\u524D ${app === null ? "null" : typeof app}\uFF09\uFF1B\u5DE5\u5382\u5FC5\u987B\u8FD4\u56DE createApp(...) \u521B\u5EFA\u7684\u5E94\u7528\u5B9E\u4F8B\u3002`
+          );
+        }
+        app.mount(el);
+      } catch (e) {
+        if (app) {
+          try {
+            app.unmount();
+          } catch {
+          }
+        }
+        throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
+      }
+      appsByEl.set(el, app);
+    },
+    unmount(el) {
+      const app = appsByEl.get(el);
+      if (!app) return;
+      appsByEl.delete(el);
+      try {
+        app.unmount();
+      } catch (e) {
+        throw bridgeLifecycleError("unmount", "bridge", e instanceof Error ? e : String(e));
+      }
+    }
+  };
+}
+export {
+  defineBridgeApp
+};

package/dist/bridge-core-6uLJiMVa.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 跨应用上下文标准字段表（§4.3，0.8.2 精简后）。
+ *
+ * 读写约定：宿主桥先写标准字段；远程 boot 只增不改宿主键；
+ * 嵌套对象（如 events）是引用共享，子应用挂属性即时可见（同 realm 直引用）。
+ *
+ * 精简记录（0.8.2）：`token` 快照与 `formUrl`/`baseUrl` 从默认 provide 集合移除——
+ * token 快照与 getToken 函数引用重复（快照会过期），formUrl/baseUrl 自 0.7.0
+ * remoteComponent 直渲染后无消费点；项目如需可经扩展位自行提供。
+ */
+interface AppContext {
+    /** 宿主登录用户原始形态（只读约定） */
+    user: Record<string, any>;
+    /** 取最新 token（拉取式防过期；0.8.2 起 bridge 不再传一次性 token 快照，用本函数取值） */
+    getToken?: () => string | undefined;
+    /** 宿主 pinia 实例：子应用 useUserStore(ctx.store) 拿共享响应式状态 */
+    store?: unknown;
+    /** 宿主 Vue App 实例（同 realm 直引用）：全局组件/指令注册目标 */
+    hostApp?: unknown;
+    /** EP locale 等 UI 配置（原 W4 字段） */
+    locale?: unknown;
+    /** 事件/方法池：events.main.* 宿主提供、events.bpm.* / events.lowcode.* 子应用反向注册 */
+    events?: Record<string, any>;
+    /**
+     * 非敏感登录代次 ID：宿主每次成功登录/重新登录生成新值，token 刷新但会话未变时沿用。
+     * 远程 onSession 按它去重（同一代次只执行一次）。不是用户 ID、不是 token、不作为授权凭证。
+     * 远程声明了 onSession 时必填（缺省即 MFU-013）。
+     */
+    sessionKey?: string;
+    /** 项目扩展位（formUrl/baseUrl 等自定义键，按需自行提供） */
+    [key: string]: unknown;
+}
+
+/** 子应用桥接契约（远程 ./bridge 模块的默认导出；任务书 §3.2） */
+interface BridgeApp {
+    /** 首次根提交完成时才算挂载成功；同一容器未卸载前重复 mount 是契约违例 */
+    mount(el: HTMLElement, props?: Record<string, unknown>): void | Promise<void>;
+    /** 同步使当前挂载代次失效并清理已创建的 root；未知容器为 no-op */
+    unmount(el: HTMLElement): void;
+}
+
+export type { AppContext as A, BridgeApp as B };

package/dist/bridge-core.cjs

@@ -0,0 +1,224 @@
+"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-core.ts
+var bridge_core_exports = {};
+__export(bridge_core_exports, {
+  acquireBridgeSession: () => acquireBridgeSession,
+  assertBridgeContract: () => assertBridgeContract,
+  assertBridgeOptions: () => assertBridgeOptions,
+  assertControlledSessionKey: () => assertControlledSessionKey,
+  releaseBridgeSession: () => releaseBridgeSession,
+  resolveBridgeContext: () => resolveBridgeContext,
+  withBridgeTimeout: () => withBridgeTimeout
+});
+module.exports = __toCommonJS(bridge_core_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/context.ts
+var APP_CONTEXT_STORAGE_KEY = "__FULGURJS_APP_CONFIG__";
+function clearAppContext() {
+  const g = globalThis;
+  delete g[APP_CONTEXT_STORAGE_KEY];
+  try {
+    g.__FULGURJS_RUNTIME__?.clearSessionState?.();
+  } catch {
+  }
+}
+
+// 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) }
+  );
+}
+
+// src/bridge-core.ts
+function assertBridgeContract(spec, mod) {
+  const contract = mod?.default ?? mod;
+  if (contract === null || typeof contract !== "object" || typeof contract.mount !== "function" || typeof contract.unmount !== "function") {
+    throw invalidBridgeContractError(spec, mod);
+  }
+  return contract;
+}
+var activeBridgeSessions = /* @__PURE__ */ new Map();
+function acquireBridgeSession(spec, sessionKey) {
+  for (const [active] of activeBridgeSessions) {
+    if (active !== sessionKey && (activeBridgeSessions.get(active) ?? 0) > 0) {
+      throw bridgeSessionMismatchError(spec, sessionKey, active, { reason: "active-instance" });
+    }
+  }
+  activeBridgeSessions.set(sessionKey, (activeBridgeSessions.get(sessionKey) ?? 0) + 1);
+}
+function releaseBridgeSession(sessionKey) {
+  const n = activeBridgeSessions.get(sessionKey) ?? 0;
+  if (n <= 1) activeBridgeSessions.delete(sessionKey);
+  else activeBridgeSessions.set(sessionKey, n - 1);
+}
+function resolveBridgeContext(spec, controlled, getContext) {
+  if (getContext) {
+    let snapshot;
+    try {
+      snapshot = getContext();
+    } catch (e) {
+      throw bridgeLifecycleError("getContext", spec, e);
+    }
+    if (snapshot === null || typeof snapshot !== "object" || typeof snapshot.then === "function") {
+      throw bridgeLifecycleError(
+        "getContext",
+        spec,
+        `getContext \u8FD4\u56DE\u4E86${typeof snapshot.then === "function" ? " Promise/thenable" : "\u975E\u5BF9\u8C61\u503C\uFF08" + typeof snapshot + "\uFF09"}\uFF1B\u5B83\u5FC5\u987B\u662F\u540C\u6B65\u8FD4\u56DE\u5FEB\u7167\u5BF9\u8C61\u7684\u7EAF getter\u3002`
+      );
+    }
+    if (controlled !== void 0 && snapshot.sessionKey !== controlled) {
+      throw bridgeSessionMismatchError(spec, controlled, snapshot.sessionKey, { reason: "getter-snapshot" });
+    }
+    const current = currentSessionKey();
+    if (snapshot.sessionKey !== void 0 && snapshot.sessionKey !== current) {
+      clearAppContext();
+    }
+    return { provide: snapshot };
+  }
+  if (controlled !== void 0) {
+    const current = currentSessionKey();
+    if (current !== controlled) {
+      throw bridgeSessionMismatchError(spec, controlled, current, { reason: "app-context" });
+    }
+  }
+  return {};
+}
+function currentSessionKey() {
+  const sk = (globalThis.__FULGURJS_APP_CONFIG__ ?? {}).sessionKey;
+  return typeof sk === "string" && sk !== "" ? sk : void 0;
+}
+function assertControlledSessionKey(spec, value) {
+  if (value === void 0 || value === null) return;
+  if (typeof value === "string" && value !== "") return;
+  throw invalidSessionKeyError(spec, value);
+}
+function assertBridgeOptions(source, opts) {
+  if (opts.retries !== void 0 && (typeof opts.retries !== "number" || !Number.isInteger(opts.retries) || opts.retries < 0 || opts.retries > 10)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 retries \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.retries)}\uFF0C\u5E94\u4E3A 0 \u5230 10 \u7684\u6574\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+  if (opts.timeout !== void 0 && (typeof opts.timeout !== "number" || !Number.isFinite(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 timeout \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.timeout)}\uFF0C\u5E94\u4E3A\u5927\u4E8E 0 \u7684\u6709\u9650\u6BEB\u79D2\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+}
+function withBridgeTimeout(p, ms, spec) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(
+        `[fulgurjs] \u6865\u63A5\u5E94\u7528 "${spec}" \u52A0\u8F7D\u7B49\u5F85\u8D85\u8FC7 ${ms} \u6BEB\u79D2\uFF08\u9002\u914D\u5C42 timeout\uFF09\u3002\u8BE5\u8D85\u65F6\u53EA\u7ED3\u675F\u672C\u6B21\u7B49\u5F85\uFF0C\u4E0D\u53D6\u6D88\u5DF2\u53D1\u51FA\u7684\u5171\u4EAB\u8BF7\u6C42\uFF1B\u53EF\u70B9\u51FB\u300C\u91CD\u8BD5\u52A0\u8F7D\u300D\u5EFA\u7ACB\u65B0\u7684\u5C1D\u8BD5\u3002`
+      ));
+    }, ms);
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  acquireBridgeSession,
+  assertBridgeContract,
+  assertBridgeOptions,
+  assertControlledSessionKey,
+  releaseBridgeSession,
+  resolveBridgeContext,
+  withBridgeTimeout
+});

package/dist/bridge-core.d.cts

@@ -0,0 +1,51 @@
+import { AppContext } from './context.cjs';
+
+/** 子应用桥接契约（远程 ./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 };