@fulgurjs/federation 4.0.0 → 4.1.0

package/dist/config.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var config_exports = {};
 __export(config_exports, {
   defineRepoConfig: () => defineRepoConfig,
+  federationOptionsForApp: () => federationOptionsForApp,
   loadRepoConfig: () => loadRepoConfig
 });
 module.exports = __toCommonJS(config_exports);
@@ -44,9 +45,19 @@ async function loadRepoConfig(configPath) {
   const fs = await import("fs");
   const os = await import("os");
   const path = await import("path");
-  const selfDir = path.dirname(fileURLToPath(import_meta.url));
-  const selfConfigJs = path.join(selfDir, "config.js");
-  const SELF_SPEC = fs.existsSync(selfConfigJs) ? pathToFileURL(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
+  const selfDir = await (async () => {
+    try {
+      return path.dirname(fileURLToPath(import_meta.url));
+    } catch {
+    }
+    try {
+      return __dirname;
+    } catch {
+    }
+    return "";
+  })();
+  const selfConfigJs = selfDir ? path.join(selfDir, "config.js") : "";
+  const SELF_SPEC = selfConfigJs && fs.existsSync(selfConfigJs) ? pathToFileURL(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
   const rewriteSelfImports = (source) => source.replace(/(['"])@fulgurjs\/federation\/config\1/g, (_m, q) => `${q}${SELF_SPEC}${q}`);
   const importConfigs = async (cacheKey) => {
     return await import(`${cacheKey}?t=${Date.now()}`);
@@ -101,14 +112,62 @@ async function loadRepoConfig(configPath) {
       throw new Error(
         `[fulgurjs:init] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
 \u6839\u56E0\uFF1A\u5E94\u7528\u5FC5\u987B\u81F3\u5C11\u58F0\u660E\u4E00\u4E2A\u89D2\u8272
-\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { pages, remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF08pages \u53EF\u9009\uFF09\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
       );
     }
   }
   return cfg;
 }
+function federationOptionsForApp(config, appPathOrName) {
+  const app = config.apps.find(
+    (a) => a.path === appPathOrName || a.name === appPathOrName
+  );
+  if (!app) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${appPathOrName}" \u4E0D\u5728\u4ED3\u5E93\u914D\u7F6E\u4E2D
+  \u53EF\u7528\u5E94\u7528: ${config.apps.map((a) => `${a.path}(${a.name})`).join("\u3001")}
+  \u4FEE\u6CD5: \u4FEE\u6B63\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D\uFF08fulgurjs.config.ts apps \u6570\u7EC4\u5185\u4E8C\u9009\u4E00\u5339\u914D\uFF09`
+    );
+  }
+  if (!app.host && !app.remote) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
+  \u4FEE\u6CD5: \u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+    );
+  }
+  const remotes = {};
+  const remoteSource = /* @__PURE__ */ new Map();
+  const mergeRemotes = (from, role) => {
+    for (const [key, addr] of Object.entries(from ?? {})) {
+      const prev = remotes[key];
+      if (prev && (prev.dev !== addr.dev || prev.prod !== addr.prod)) {
+        throw new Error(
+          `[fulgurjs] \u5E94\u7528 "${app.path}" \u7684\u8FDC\u7A0B "${key}" \u5728 ${role} \u4E0E ${remoteSource.get(key)} \u4E24\u5904\u5730\u5740\u4E0D\u4E00\u81F4
+  ${remoteSource.get(key)}: dev=${prev.dev} prod=${prev.prod}
+  ${role}: dev=${addr.dev} prod=${addr.prod}
+  \u4FEE\u6CD5: \u4FEE\u6B63 fulgurjs.config.ts \u4F7F\u4E24\u5904\u4E00\u81F4\uFF08\u540C\u4E00\u8FDC\u7A0B\u5728\u4E00\u4E2A\u5E94\u7528\u5185\u53EA\u80FD\u6709\u4E00\u4E2A\u5730\u5740\uFF09`
+        );
+      }
+      remotes[key] = addr;
+      remoteSource.set(key, role);
+    }
+  };
+  mergeRemotes(app.host?.remotes, "host.remotes");
+  mergeRemotes(app.remote?.remotes, "remote.remotes");
+  const hasExposes = !!app.remote && Object.keys(app.remote.exposes).length > 0;
+  const hasRemotes = Object.keys(remotes).length > 0;
+  return {
+    name: app.name,
+    ...hasRemotes ? { remotes } : {},
+    ...hasExposes ? { exposes: app.remote.exposes } : {},
+    ...app.remote?.setup ? { setup: app.remote.setup } : {},
+    ...app.shared ? { shared: app.shared } : {},
+    devSharedSelf: app.devSharedSelf ?? (hasExposes || !!app.remote?.setup)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   defineRepoConfig,
+  federationOptionsForApp,
   loadRepoConfig
 });

package/dist/config.d.cts

@@ -1,3 +1,5 @@
+import { F as FederationOptions } from './options-CRGpSmVj.cjs';
+
 /**
  * W1 fulgurjs.config.ts：单配置文件驱动的 schema + 加载器（项目无关，决策见排期文档 §4：
  * 主包内置 bin + 单配置文件驱动，可入库可复跑）。
@@ -12,14 +14,22 @@ interface PageEntry {
     spec?: string;
     /** 页签标题 */
     title?: string;
+    /** 页面保活开关（按页显式开启；默认关闭） */
+    keepAlive?: boolean;
 }
 interface RemoteAddress {
     dev: string;
     prod: string;
 }
 interface HostConfig {
-    /** 页面路由表 */
-    pages: PageEntry[];
+    /**
+     * 页面路由表（可选）：应用代码的页面表是运行时页面真源（供宿主路由与
+     * createHostPages 共用），仓库配置中的副本仅供 init/explain 摘要与核对。
+     * 不再强制——缺省时 CLI 摘要按实际提供数量报告。
+     */
+    pages?: PageEntry[];
+    /** 页面 spec 推导规则（与宿主 createHostPages 的 deriveSpec 保持一致；缺省 = 去首段 + 剥 :参 段） */
+    deriveSpec?: (route: string) => string;
     /** 路由前缀 → 远程名 */
     remotePrefixes: Record<string, string>;
     /** 消费的远程地址（键 = import 前缀；裸 URL，对象形式不支持 name@ 前缀） */
@@ -28,7 +38,9 @@ interface HostConfig {
 interface RemoteConfig {
     /** exposes：./键 → 源文件（独立页） */
     exposes: Record<string, string>;
-    /** 反向消费的远程（双向联邦时；dev 下自身源码参与协商需 devSharedSelf: true） */
+    /** 远程初始化入口（默认导出 setup(context)，可选具名导出 onSession(context)） */
+    setup?: string;
+    /** 反向消费的远程（双向联邦时） */
     remotes?: Record<string, RemoteAddress>;
 }
 interface AppConfig {
@@ -51,6 +63,8 @@ interface AppConfig {
         singleton?: boolean;
         requiredVersion?: string;
     }>;
+    /** 显式覆盖 dev 下自身源码参与 shared 协商改写；缺省按角色推断（见 federationOptionsForApp） */
+    devSharedSelf?: boolean;
 }
 interface DeployConfig {
     /** NGINX 站点根（样板输出用，可选） */
@@ -75,5 +89,18 @@ declare function defineRepoConfig(config: UserConfig): UserConfig;
  *   老版本 Node 回退 esbuild 转译（先试配置工程，再试 CLI 自带依赖树）。
  */
 declare function loadRepoConfig(configPath: string): Promise<RepoConfig>;
+/**
+ * 仓库配置 → 某应用的 federation() Vite 插件选项（§3.4 单配置驱动）。
+ *
+ * 转换范围：name、宿主/反向 remotes（两处同键冲突即报错，带两边值）、exposes、
+ * 可选 setup、shared、devSharedSelf。build.target/base/端口/代理/插件顺序等仍归各应用
+ * vite.config.ts 管理——本函数只生成 federation({...}) 的入参。
+ *
+ * devSharedSelf 来源（优先级）：app.devSharedSelf 显式值 > 角色推断。
+ * 推断规则：提供 exposes（含仅 setup）的应用为 true（其源码被宿主消费，需协商到宿主
+ * 实例）；纯宿主（只消费）为 false。双向联邦漏配该项曾是已知错误配置（§12.4），
+ * 推断后不再依赖背诵。
+ */
+declare function federationOptionsForApp(config: RepoConfig, appPathOrName: string): FederationOptions;
 
-export { type AppConfig, type DeployConfig, type HostConfig, type PageEntry, type RemoteAddress, type RemoteConfig, type RepoConfig, type UserConfig, defineRepoConfig, loadRepoConfig };
+export { type AppConfig, type DeployConfig, type HostConfig, type PageEntry, type RemoteAddress, type RemoteConfig, type RepoConfig, type UserConfig, defineRepoConfig, federationOptionsForApp, loadRepoConfig };

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import { F as FederationOptions } from './options-CRGpSmVj.js';
+
 /**
  * W1 fulgurjs.config.ts：单配置文件驱动的 schema + 加载器（项目无关，决策见排期文档 §4：
  * 主包内置 bin + 单配置文件驱动，可入库可复跑）。
@@ -12,14 +14,22 @@ interface PageEntry {
     spec?: string;
     /** 页签标题 */
     title?: string;
+    /** 页面保活开关（按页显式开启；默认关闭） */
+    keepAlive?: boolean;
 }
 interface RemoteAddress {
     dev: string;
     prod: string;
 }
 interface HostConfig {
-    /** 页面路由表 */
-    pages: PageEntry[];
+    /**
+     * 页面路由表（可选）：应用代码的页面表是运行时页面真源（供宿主路由与
+     * createHostPages 共用），仓库配置中的副本仅供 init/explain 摘要与核对。
+     * 不再强制——缺省时 CLI 摘要按实际提供数量报告。
+     */
+    pages?: PageEntry[];
+    /** 页面 spec 推导规则（与宿主 createHostPages 的 deriveSpec 保持一致；缺省 = 去首段 + 剥 :参 段） */
+    deriveSpec?: (route: string) => string;
     /** 路由前缀 → 远程名 */
     remotePrefixes: Record<string, string>;
     /** 消费的远程地址（键 = import 前缀；裸 URL，对象形式不支持 name@ 前缀） */
@@ -28,7 +38,9 @@ interface HostConfig {
 interface RemoteConfig {
     /** exposes：./键 → 源文件（独立页） */
     exposes: Record<string, string>;
-    /** 反向消费的远程（双向联邦时；dev 下自身源码参与协商需 devSharedSelf: true） */
+    /** 远程初始化入口（默认导出 setup(context)，可选具名导出 onSession(context)） */
+    setup?: string;
+    /** 反向消费的远程（双向联邦时） */
     remotes?: Record<string, RemoteAddress>;
 }
 interface AppConfig {
@@ -51,6 +63,8 @@ interface AppConfig {
         singleton?: boolean;
         requiredVersion?: string;
     }>;
+    /** 显式覆盖 dev 下自身源码参与 shared 协商改写；缺省按角色推断（见 federationOptionsForApp） */
+    devSharedSelf?: boolean;
 }
 interface DeployConfig {
     /** NGINX 站点根（样板输出用，可选） */
@@ -75,5 +89,18 @@ declare function defineRepoConfig(config: UserConfig): UserConfig;
  *   老版本 Node 回退 esbuild 转译（先试配置工程，再试 CLI 自带依赖树）。
  */
 declare function loadRepoConfig(configPath: string): Promise<RepoConfig>;
+/**
+ * 仓库配置 → 某应用的 federation() Vite 插件选项（§3.4 单配置驱动）。
+ *
+ * 转换范围：name、宿主/反向 remotes（两处同键冲突即报错，带两边值）、exposes、
+ * 可选 setup、shared、devSharedSelf。build.target/base/端口/代理/插件顺序等仍归各应用
+ * vite.config.ts 管理——本函数只生成 federation({...}) 的入参。
+ *
+ * devSharedSelf 来源（优先级）：app.devSharedSelf 显式值 > 角色推断。
+ * 推断规则：提供 exposes（含仅 setup）的应用为 true（其源码被宿主消费，需协商到宿主
+ * 实例）；纯宿主（只消费）为 false。双向联邦漏配该项曾是已知错误配置（§12.4），
+ * 推断后不再依赖背诵。
+ */
+declare function federationOptionsForApp(config: RepoConfig, appPathOrName: string): FederationOptions;
 
-export { type AppConfig, type DeployConfig, type HostConfig, type PageEntry, type RemoteAddress, type RemoteConfig, type RepoConfig, type UserConfig, defineRepoConfig, loadRepoConfig };
+export { type AppConfig, type DeployConfig, type HostConfig, type PageEntry, type RemoteAddress, type RemoteConfig, type RepoConfig, type UserConfig, defineRepoConfig, federationOptionsForApp, loadRepoConfig };

package/dist/config.js

@@ -8,9 +8,19 @@ async function loadRepoConfig(configPath) {
   const fs = await import("fs");
   const os = await import("os");
   const path = await import("path");
-  const selfDir = path.dirname(fileURLToPath(import.meta.url));
-  const selfConfigJs = path.join(selfDir, "config.js");
-  const SELF_SPEC = fs.existsSync(selfConfigJs) ? pathToFileURL(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
+  const selfDir = await (async () => {
+    try {
+      return path.dirname(fileURLToPath(import.meta.url));
+    } catch {
+    }
+    try {
+      return __dirname;
+    } catch {
+    }
+    return "";
+  })();
+  const selfConfigJs = selfDir ? path.join(selfDir, "config.js") : "";
+  const SELF_SPEC = selfConfigJs && fs.existsSync(selfConfigJs) ? pathToFileURL(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
   const rewriteSelfImports = (source) => source.replace(/(['"])@fulgurjs\/federation\/config\1/g, (_m, q) => `${q}${SELF_SPEC}${q}`);
   const importConfigs = async (cacheKey) => {
     return await import(`${cacheKey}?t=${Date.now()}`);
@@ -65,13 +75,61 @@ async function loadRepoConfig(configPath) {
       throw new Error(
         `[fulgurjs:init] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
 \u6839\u56E0\uFF1A\u5E94\u7528\u5FC5\u987B\u81F3\u5C11\u58F0\u660E\u4E00\u4E2A\u89D2\u8272
-\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { pages, remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF08pages \u53EF\u9009\uFF09\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
       );
     }
   }
   return cfg;
 }
+function federationOptionsForApp(config, appPathOrName) {
+  const app = config.apps.find(
+    (a) => a.path === appPathOrName || a.name === appPathOrName
+  );
+  if (!app) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${appPathOrName}" \u4E0D\u5728\u4ED3\u5E93\u914D\u7F6E\u4E2D
+  \u53EF\u7528\u5E94\u7528: ${config.apps.map((a) => `${a.path}(${a.name})`).join("\u3001")}
+  \u4FEE\u6CD5: \u4FEE\u6B63\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D\uFF08fulgurjs.config.ts apps \u6570\u7EC4\u5185\u4E8C\u9009\u4E00\u5339\u914D\uFF09`
+    );
+  }
+  if (!app.host && !app.remote) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
+  \u4FEE\u6CD5: \u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+    );
+  }
+  const remotes = {};
+  const remoteSource = /* @__PURE__ */ new Map();
+  const mergeRemotes = (from, role) => {
+    for (const [key, addr] of Object.entries(from ?? {})) {
+      const prev = remotes[key];
+      if (prev && (prev.dev !== addr.dev || prev.prod !== addr.prod)) {
+        throw new Error(
+          `[fulgurjs] \u5E94\u7528 "${app.path}" \u7684\u8FDC\u7A0B "${key}" \u5728 ${role} \u4E0E ${remoteSource.get(key)} \u4E24\u5904\u5730\u5740\u4E0D\u4E00\u81F4
+  ${remoteSource.get(key)}: dev=${prev.dev} prod=${prev.prod}
+  ${role}: dev=${addr.dev} prod=${addr.prod}
+  \u4FEE\u6CD5: \u4FEE\u6B63 fulgurjs.config.ts \u4F7F\u4E24\u5904\u4E00\u81F4\uFF08\u540C\u4E00\u8FDC\u7A0B\u5728\u4E00\u4E2A\u5E94\u7528\u5185\u53EA\u80FD\u6709\u4E00\u4E2A\u5730\u5740\uFF09`
+        );
+      }
+      remotes[key] = addr;
+      remoteSource.set(key, role);
+    }
+  };
+  mergeRemotes(app.host?.remotes, "host.remotes");
+  mergeRemotes(app.remote?.remotes, "remote.remotes");
+  const hasExposes = !!app.remote && Object.keys(app.remote.exposes).length > 0;
+  const hasRemotes = Object.keys(remotes).length > 0;
+  return {
+    name: app.name,
+    ...hasRemotes ? { remotes } : {},
+    ...hasExposes ? { exposes: app.remote.exposes } : {},
+    ...app.remote?.setup ? { setup: app.remote.setup } : {},
+    ...app.shared ? { shared: app.shared } : {},
+    devSharedSelf: app.devSharedSelf ?? (hasExposes || !!app.remote?.setup)
+  };
+}
 export {
   defineRepoConfig,
+  federationOptionsForApp,
   loadRepoConfig
 };

package/dist/context.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var context_exports = {};
 __export(context_exports, {
   ContextErrorCodes: () => ContextErrorCodes,
+  clearAppContext: () => clearAppContext,
   getAppContext: () => getAppContext,
   provideAppContext: () => provideAppContext,
   requireAppContext: () => requireAppContext
@@ -52,7 +53,7 @@ function requireRuntime() {
   if (!rt || typeof rt.loadRemote !== "function") {
     throw new FgError(
       ContextErrorCodes.CONTEXT_NO_RUNTIME,
-      "fulgurjs runtime singleton not found on this page (globalThis.__FULGURJS_RUNTIME__ is undefined).\n  \u6839\u56E0: \u5F53\u524D\u9875\u9762\u6CA1\u6709\u7ECF\u5BBF\u4E3B\u7684\u8054\u90A6\u8FD0\u884C\u65F6\u52A0\u8F7D\uFF08\u72EC\u7ACB\u76F4\u5F00\u8FDC\u7A0B\u9875\uFF0C\u6216\u5BBF\u4E3B\u6865\u665A\u4E8E\u672C\u8C03\u7528\u6267\u884C\uFF09\u3002\n  \u4FEE\u6CD5: \u2460 \u4ECE\u5BBF\u4E3B\u5E94\u7528\u7684\u8054\u90A6\u8DEF\u7531\u6253\u5F00\u672C\u9875\u9762\uFF08\u5BBF\u4E3B bridge \u4F1A\u5148\u52A0\u8F7D\u8FD0\u884C\u65F6\u5E76\u63D0\u4F9B context\uFF09\uFF1B\n        \u2461 \u82E5\u4F60\u662F\u5BBF\u4E3B\u6865\u4F5C\u8005\uFF1A\u628A provideAppContext \u653E\u5728 bridge \u521D\u59CB\u5316\u5C3E\u90E8\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 federatedBoot \u2192 loadRemote\uFF09\u3002",
+      "fulgurjs runtime singleton not found on this page (globalThis.__FULGURJS_RUNTIME__ is undefined).\n  \u6839\u56E0: \u5F53\u524D\u9875\u9762\u6CA1\u6709\u7ECF\u5BBF\u4E3B\u7684\u8054\u90A6\u8FD0\u884C\u65F6\u52A0\u8F7D\uFF08\u72EC\u7ACB\u76F4\u5F00\u8FDC\u7A0B\u9875\uFF0C\u6216\u5BBF\u4E3B\u6865\u665A\u4E8E\u672C\u8C03\u7528\u6267\u884C\uFF09\u3002\n  \u4FEE\u6CD5: \u2460 \u4ECE\u5BBF\u4E3B\u5E94\u7528\u7684\u8054\u90A6\u8DEF\u7531\u6253\u5F00\u672C\u9875\u9762\uFF08\u5BBF\u4E3B\u6865\u4F1A\u5148\u52A0\u8F7D\u8FD0\u884C\u65F6\u5E76\u63D0\u4F9B context\uFF09\uFF1B\n        \u2461 \u82E5\u4F60\u662F\u5BBF\u4E3B\u6865\u4F5C\u8005\uFF1A\u628A provideAppContext \u653E\u5728\u6865\u521D\u59CB\u5316\u5C3E\u90E8\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 \u8FDC\u7A0B setup \u2192 \u9875\u9762\u6A21\u5757\uFF09\u3002",
       { runtime: false }
     );
   }
@@ -63,6 +64,14 @@ function provideAppContext(config) {
   const g = globalThis;
   g[APP_CONTEXT_STORAGE_KEY] = { ...g[APP_CONTEXT_STORAGE_KEY] ?? {}, ...config };
 }
+function clearAppContext() {
+  const g = globalThis;
+  delete g[APP_CONTEXT_STORAGE_KEY];
+  try {
+    g.__FULGURJS_RUNTIME__?.clearSessionState?.();
+  } catch {
+  }
+}
 function getAppContext() {
   requireRuntime();
   return globalThis[APP_CONTEXT_STORAGE_KEY] ?? {};
@@ -78,7 +87,7 @@ function requireAppContext(...keys) {
   got: ${got.length ? got.map((k) => `"${k}"`).join(", ") : "(empty \u2014 \u5BBF\u4E3B\u6865\u4ECE\u672A\u8C03\u7528 provideAppContext?)"}
   expected: \u5BBF\u4E3B\u6865\u5FC5\u987B\u5728\u4EFB\u4F55\u8FDC\u7A0B\u9875\u9762\u52A0\u8F7D\u524D\u63D0\u4F9B ${missing.map((k) => `"${k}"`).join(" / ")}
   example: host/src/fulgurjs/host/bridge.ts \u2192 provideAppContext({ ${keys.join(", ")}, ... })
-  \u4FEE\u6CD5: \u68C0\u67E5\u5BBF\u4E3B\u5E94\u7528 fulgurjs bridge \u662F\u5426\u5347\u7EA7\u5230 0.8.0 context \u5F62\u6001\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 federatedBoot \u2192 loadRemote\uFF09`,
+  \u4FEE\u6CD5: \u68C0\u67E5\u5BBF\u4E3B\u5E94\u7528\u7684 fulgurjs \u6865\u662F\u5426\u5728 loadRemote \u9875\u9762\u524D\u5B8C\u6210 context provide\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 \u8FDC\u7A0B setup \u2192 \u9875\u9762\u6A21\u5757\uFF09`,
     { missing, got }
   );
   throw err;
@@ -86,6 +95,7 @@ function requireAppContext(...keys) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ContextErrorCodes,
+  clearAppContext,
   getAppContext,
   provideAppContext,
   requireAppContext

package/dist/context.d.cts

@@ -30,27 +30,43 @@ interface AppContext {
     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;
 }
 /**
  * 宿主写入跨应用上下文（merge 语义，幂等可多次调用，后写覆盖同键）。
  *
- * 宿主桥（host/src/fulgurjs/host/bridge.ts）在登录完成后调用一次：
- * provideAppContext({ user, token, getToken, store, hostApp, locale, events: { main: mainEvents }, ... })
+ * 宿主桥（host/src/fulgurjs/host/bridge.ts）在登录完成后调用：
+ * provideAppContext({ user, getToken, store, hostApp, locale, sessionKey, events: { main: mainEvents }, ... })
+ * 登录态变化（换账号/token 刷新）时再次调用即以最新值覆盖同键——不要用布尔闩锁把桥封成只跑一次。
  */
 declare function provideAppContext(config: Partial<AppContext> & Record<string, unknown>): void;
+/**
+ * 宿主退出登录时清理：删除整个 context 对象（旧 user/getToken 引用一并失效），并通知
+ * 运行时单例作废全部远程的会话信号与 onSession 去重状态（下次登录必须重新执行 onSession）。
+ *
+ * 边界（契约）：只清 AppContext 与会话初始化状态；不重置远程模块缓存、共享模块图与
+ * 应用级 setup 注册（同一页面内组件与共享实例继续复用）。页面无运行时单例时静默幂等
+ * （退出动作不依赖联邦形态，不得因缺运行时而打断登出流程）。
+ */
+declare function clearAppContext(): void;
 /**
  * 读上下文快照（传输层快照：顶层 merge 结果 + 嵌套对象引用共享）。
  * 页面无运行时单例（独立直开远程页）→ CC-002 显式抛错，不静默回空。
  */
 declare function getAppContext(): AppContext;
 /**
- * 显式校验读取（远程 boot 消费入口）：任一键缺失 → CC-001 三段式。
+ * 显式校验读取（远程 setup/boot 消费入口）：任一键缺失 → CC-001 三段式。
  *
  * 用法：const { store, user, hostApp } = requireAppContext('store', 'user', 'hostApp')
- * 时序契约：宿主 bridge 先 provide，远程 federatedBoot 后 require——违反即在 boot 处显式失败。
+ * 时序契约：宿主桥先 provide，远程 setup/onSession 后 require——违反即在初始化处显式失败。
  */
 declare function requireAppContext(...keys: string[]): AppContext;
 
-export { type AppContext, ContextErrorCodes, getAppContext, provideAppContext, requireAppContext };
+export { type AppContext, ContextErrorCodes, clearAppContext, getAppContext, provideAppContext, requireAppContext };

package/dist/context.d.ts

@@ -30,27 +30,43 @@ interface AppContext {
     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;
 }
 /**
  * 宿主写入跨应用上下文（merge 语义，幂等可多次调用，后写覆盖同键）。
  *
- * 宿主桥（host/src/fulgurjs/host/bridge.ts）在登录完成后调用一次：
- * provideAppContext({ user, token, getToken, store, hostApp, locale, events: { main: mainEvents }, ... })
+ * 宿主桥（host/src/fulgurjs/host/bridge.ts）在登录完成后调用：
+ * provideAppContext({ user, getToken, store, hostApp, locale, sessionKey, events: { main: mainEvents }, ... })
+ * 登录态变化（换账号/token 刷新）时再次调用即以最新值覆盖同键——不要用布尔闩锁把桥封成只跑一次。
  */
 declare function provideAppContext(config: Partial<AppContext> & Record<string, unknown>): void;
+/**
+ * 宿主退出登录时清理：删除整个 context 对象（旧 user/getToken 引用一并失效），并通知
+ * 运行时单例作废全部远程的会话信号与 onSession 去重状态（下次登录必须重新执行 onSession）。
+ *
+ * 边界（契约）：只清 AppContext 与会话初始化状态；不重置远程模块缓存、共享模块图与
+ * 应用级 setup 注册（同一页面内组件与共享实例继续复用）。页面无运行时单例时静默幂等
+ * （退出动作不依赖联邦形态，不得因缺运行时而打断登出流程）。
+ */
+declare function clearAppContext(): void;
 /**
  * 读上下文快照（传输层快照：顶层 merge 结果 + 嵌套对象引用共享）。
  * 页面无运行时单例（独立直开远程页）→ CC-002 显式抛错，不静默回空。
  */
 declare function getAppContext(): AppContext;
 /**
- * 显式校验读取（远程 boot 消费入口）：任一键缺失 → CC-001 三段式。
+ * 显式校验读取（远程 setup/boot 消费入口）：任一键缺失 → CC-001 三段式。
  *
  * 用法：const { store, user, hostApp } = requireAppContext('store', 'user', 'hostApp')
- * 时序契约：宿主 bridge 先 provide，远程 federatedBoot 后 require——违反即在 boot 处显式失败。
+ * 时序契约：宿主桥先 provide，远程 setup/onSession 后 require——违反即在初始化处显式失败。
  */
 declare function requireAppContext(...keys: string[]): AppContext;
 
-export { type AppContext, ContextErrorCodes, getAppContext, provideAppContext, requireAppContext };
+export { type AppContext, ContextErrorCodes, clearAppContext, getAppContext, provideAppContext, requireAppContext };

package/dist/context.js

@@ -1,6 +1,6 @@
 import {
   FgError
-} from "./chunk-3VBYOVH4.js";
+} from "./chunk-WBCXLR2N.js";
 
 // src/context.ts
 var ContextErrorCodes = {
@@ -15,7 +15,7 @@ function requireRuntime() {
   if (!rt || typeof rt.loadRemote !== "function") {
     throw new FgError(
       ContextErrorCodes.CONTEXT_NO_RUNTIME,
-      "fulgurjs runtime singleton not found on this page (globalThis.__FULGURJS_RUNTIME__ is undefined).\n  \u6839\u56E0: \u5F53\u524D\u9875\u9762\u6CA1\u6709\u7ECF\u5BBF\u4E3B\u7684\u8054\u90A6\u8FD0\u884C\u65F6\u52A0\u8F7D\uFF08\u72EC\u7ACB\u76F4\u5F00\u8FDC\u7A0B\u9875\uFF0C\u6216\u5BBF\u4E3B\u6865\u665A\u4E8E\u672C\u8C03\u7528\u6267\u884C\uFF09\u3002\n  \u4FEE\u6CD5: \u2460 \u4ECE\u5BBF\u4E3B\u5E94\u7528\u7684\u8054\u90A6\u8DEF\u7531\u6253\u5F00\u672C\u9875\u9762\uFF08\u5BBF\u4E3B bridge \u4F1A\u5148\u52A0\u8F7D\u8FD0\u884C\u65F6\u5E76\u63D0\u4F9B context\uFF09\uFF1B\n        \u2461 \u82E5\u4F60\u662F\u5BBF\u4E3B\u6865\u4F5C\u8005\uFF1A\u628A provideAppContext \u653E\u5728 bridge \u521D\u59CB\u5316\u5C3E\u90E8\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 federatedBoot \u2192 loadRemote\uFF09\u3002",
+      "fulgurjs runtime singleton not found on this page (globalThis.__FULGURJS_RUNTIME__ is undefined).\n  \u6839\u56E0: \u5F53\u524D\u9875\u9762\u6CA1\u6709\u7ECF\u5BBF\u4E3B\u7684\u8054\u90A6\u8FD0\u884C\u65F6\u52A0\u8F7D\uFF08\u72EC\u7ACB\u76F4\u5F00\u8FDC\u7A0B\u9875\uFF0C\u6216\u5BBF\u4E3B\u6865\u665A\u4E8E\u672C\u8C03\u7528\u6267\u884C\uFF09\u3002\n  \u4FEE\u6CD5: \u2460 \u4ECE\u5BBF\u4E3B\u5E94\u7528\u7684\u8054\u90A6\u8DEF\u7531\u6253\u5F00\u672C\u9875\u9762\uFF08\u5BBF\u4E3B\u6865\u4F1A\u5148\u52A0\u8F7D\u8FD0\u884C\u65F6\u5E76\u63D0\u4F9B context\uFF09\uFF1B\n        \u2461 \u82E5\u4F60\u662F\u5BBF\u4E3B\u6865\u4F5C\u8005\uFF1A\u628A provideAppContext \u653E\u5728\u6865\u521D\u59CB\u5316\u5C3E\u90E8\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 \u8FDC\u7A0B setup \u2192 \u9875\u9762\u6A21\u5757\uFF09\u3002",
       { runtime: false }
     );
   }
@@ -26,6 +26,14 @@ function provideAppContext(config) {
   const g = globalThis;
   g[APP_CONTEXT_STORAGE_KEY] = { ...g[APP_CONTEXT_STORAGE_KEY] ?? {}, ...config };
 }
+function clearAppContext() {
+  const g = globalThis;
+  delete g[APP_CONTEXT_STORAGE_KEY];
+  try {
+    g.__FULGURJS_RUNTIME__?.clearSessionState?.();
+  } catch {
+  }
+}
 function getAppContext() {
   requireRuntime();
   return globalThis[APP_CONTEXT_STORAGE_KEY] ?? {};
@@ -41,13 +49,14 @@ function requireAppContext(...keys) {
   got: ${got.length ? got.map((k) => `"${k}"`).join(", ") : "(empty \u2014 \u5BBF\u4E3B\u6865\u4ECE\u672A\u8C03\u7528 provideAppContext?)"}
   expected: \u5BBF\u4E3B\u6865\u5FC5\u987B\u5728\u4EFB\u4F55\u8FDC\u7A0B\u9875\u9762\u52A0\u8F7D\u524D\u63D0\u4F9B ${missing.map((k) => `"${k}"`).join(" / ")}
   example: host/src/fulgurjs/host/bridge.ts \u2192 provideAppContext({ ${keys.join(", ")}, ... })
-  \u4FEE\u6CD5: \u68C0\u67E5\u5BBF\u4E3B\u5E94\u7528 fulgurjs bridge \u662F\u5426\u5347\u7EA7\u5230 0.8.0 context \u5F62\u6001\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 federatedBoot \u2192 loadRemote\uFF09`,
+  \u4FEE\u6CD5: \u68C0\u67E5\u5BBF\u4E3B\u5E94\u7528\u7684 fulgurjs \u6865\u662F\u5426\u5728 loadRemote \u9875\u9762\u524D\u5B8C\u6210 context provide\uFF08\u65F6\u5E8F\u5951\u7EA6 bridge \u2192 \u8FDC\u7A0B setup \u2192 \u9875\u9762\u6A21\u5757\uFF09`,
     { missing, got }
   );
   throw err;
 }
 export {
   ContextErrorCodes,
+  clearAppContext,
   getAppContext,
   provideAppContext,
   requireAppContext