@fulgurjs/federation 4.0.0 → 4.1.0

package/dist/vue-adapter.js

@@ -1,6 +1,9 @@
 import {
+  createHostPages,
   createRemoteComponent
-} from "./chunk-AYS56IRF.js";
+} from "./chunk-NUZKZUTD.js";
+import "./chunk-TSXZ7TWA.js";
 export {
+  createHostPages,
   createRemoteComponent
 };

package/dist/vue.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/vue.ts
 var vue_exports = {};
 __export(vue_exports, {
+  createHostPages: () => createHostPages2,
   remoteComponent: () => remoteComponent
 });
 module.exports = __toCommonJS(vue_exports);
@@ -253,10 +254,20 @@ var ErrorCodes = {
   /** 加载到的模块没有任何导出（常见：exposes 指向了不导出内容的文件） */
   EMPTY_EXPORTS: "MFU-009",
   /** singleton 共享协商版本与消费方 requiredVersion 不一致（使用作用域版本，仅告警） */
-  SINGLETON_SKEW: "MFU-010"
+  SINGLETON_SKEW: "MFU-010",
+  /** setup 生命周期入口导出形态非法（默认导出不是函数，或具名 onSession 不是函数） */
+  SETUP_INVALID_EXPORT: "MFU-011",
+  /** setup/onSession 执行抛错（该次 loadRemote 拒绝；仅清失败阶段缓存，允许重试） */
+  SETUP_RUN_FAILED: "MFU-012",
+  /** 远程声明了 onSession 但宿主 AppContext 未提供 sessionKey（登录代次） */
+  SETUP_SESSION_KEY_MISSING: "MFU-013",
+  /** setup/onSession 执行的同步段内递归 loadRemote 同一远程 */
+  SETUP_RECURSION: "MFU-014"
 };
 
 // src/runtime/index.ts
+var SETUP_META_KEY = "__fulgurjsSetup";
+var APP_CONTEXT_GLOBAL_KEY = "__FULGURJS_APP_CONFIG__";
 var DEFAULT_TIMEOUT = 15e3;
 var DEFAULT_RETRIES = 2;
 var BREAKER_THRESHOLD = 5;
@@ -281,6 +292,140 @@ function createRuntime() {
       }
     }
   };
+  const lifecycleStates = /* @__PURE__ */ new Map();
+  let lifecycleSyncRemote;
+  const lifecycleOf = (name) => {
+    let st = lifecycleStates.get(name);
+    if (!st) lifecycleStates.set(name, st = {});
+    return st;
+  };
+  const currentAppContext = () => globalThis[APP_CONTEXT_GLOBAL_KEY] ?? {};
+  async function invokeLifecycleFn(remoteName, fn, ctx, phase) {
+    const wrap = (err) => {
+      if (err instanceof FgError) return err;
+      return new FgError(
+        ErrorCodes.SETUP_RUN_FAILED,
+        `${phase} of "${remoteName}" threw: ${String(err?.message ?? err)}
+  \u4FEE\u6CD5: \u4FEE\u590D\u8BE5 ${phase} \u7684\u521D\u59CB\u5316\u903B\u8F91\u540E\u91CD\u65B0\u52A0\u8F7D\uFF08\u5931\u8D25\u7684\u521D\u59CB\u5316\u7F13\u5B58\u5DF2\u6E05\u9664\uFF0C\u53EF\u76F4\u63A5\u91CD\u8BD5\uFF09`,
+        { remote: remoteName, phase }
+      );
+    };
+    lifecycleSyncRemote = remoteName;
+    let result;
+    try {
+      result = fn(ctx);
+    } catch (err) {
+      throw wrap(err);
+    } finally {
+      lifecycleSyncRemote = void 0;
+    }
+    try {
+      await result;
+    } catch (err) {
+      throw wrap(err);
+    }
+  }
+  async function runSetupPhase(remote, container, setupKey, st) {
+    remote.debug.setup = "pending";
+    try {
+      if (remote.manifestUrl) {
+        try {
+          await preloadRemote2(`${remote.name}/${setupKey}`);
+        } catch {
+        }
+      }
+      const mod = await container.get(setupKey);
+      const setupFn = mod?.default;
+      if (typeof setupFn !== "function") {
+        throw new FgError(
+          ErrorCodes.SETUP_INVALID_EXPORT,
+          `setup module "${setupKey}" of "${remote.name}": default export is ${mod == null ? String(mod) : typeof setupFn}, expected a function
+  expected: export default async function setup(context: RemoteSetupContext) { ... }
+  \u4FEE\u6CD5: \u5728 federation({ setup }) \u6307\u5411\u7684\u6587\u4EF6\u8865\u9ED8\u8BA4\u5BFC\u51FA\u51FD\u6570\uFF08\u5177\u540D onSession \u53EF\u9009\uFF1B\u5176\u4ED6\u5BFC\u51FA\u4E0D\u4F5C\u4E3A\u751F\u547D\u5468\u671F\u5165\u53E3\uFF09`,
+          { remote: remote.name, module: setupKey }
+        );
+      }
+      if (mod.onSession !== void 0 && typeof mod.onSession !== "function") {
+        throw new FgError(
+          ErrorCodes.SETUP_INVALID_EXPORT,
+          `setup module "${setupKey}" of "${remote.name}": export "onSession" is ${typeof mod.onSession}, expected a function
+  \u4FEE\u6CD5: \u5C06 onSession \u4FEE\u6B63\u4E3A\u51FD\u6570\u5BFC\u51FA\uFF0C\u6216\u5220\u9664\u8BE5\u5177\u540D\u5BFC\u51FA\uFF08\u5176\u4ED6\u5BFC\u51FA\u540D\u4E0D\u4F5C\u4E3A\u751F\u547D\u5468\u671F\u5165\u53E3\uFF09`,
+          { remote: remote.name, module: setupKey }
+        );
+      }
+      st.setupExports = mod;
+      await invokeLifecycleFn(
+        remote.name,
+        setupFn,
+        { appContext: currentAppContext(), signal: (st.controller ??= new AbortController()).signal },
+        "setup"
+      );
+      remote.debug.setup = "ready";
+    } catch (err) {
+      remote.debug.setup = "failed";
+      st.setupExports = void 0;
+      throw err;
+    }
+  }
+  async function ensureSessionPhase(remote, st, onSession) {
+    const appContext = currentAppContext();
+    const sessionKey = appContext?.sessionKey;
+    if (typeof sessionKey !== "string" || sessionKey === "") {
+      throw new FgError(
+        ErrorCodes.SETUP_SESSION_KEY_MISSING,
+        `remote "${remote.name}" declares onSession but AppContext.sessionKey is ${sessionKey === void 0 ? "missing" : JSON.stringify(sessionKey)}
+  expected: \u5BBF\u4E3B\u767B\u5F55\u540E provideAppContext({ ..., sessionKey: '<\u975E\u654F\u611F\u767B\u5F55\u4EE3\u6B21 ID>' })
+  \u4FEE\u6CD5: \u5BBF\u4E3B\u767B\u5F55\u6D41\u7A0B\u6BCF\u6B21\u6210\u529F\u767B\u5F55/\u91CD\u767B\u751F\u6210\u65B0\u4EE3\u6B21 ID\uFF08\u7981\u6B62\u7528 token \u5145\u5F53\uFF09\uFF0C\u5E76\u5728 loadRemote \u524D\u63D0\u4F9B`,
+        { remote: remote.name }
+      );
+    }
+    if (st.sessionPromise && st.sessionKey === sessionKey) return st.sessionPromise;
+    st.controller?.abort();
+    const controller = new AbortController();
+    st.controller = controller;
+    st.sessionKey = sessionKey;
+    const prev = st.sessionPromise ? st.sessionPromise.catch(() => {
+    }) : Promise.resolve();
+    const run = (async () => {
+      await prev;
+      if (controller.signal.aborted) return;
+      await invokeLifecycleFn(remote.name, onSession, { appContext, sessionKey, signal: controller.signal }, "onSession");
+    })();
+    st.sessionPromise = run;
+    run.catch(() => {
+      if (st.sessionKey === sessionKey) {
+        st.sessionKey = void 0;
+        st.sessionPromise = void 0;
+      }
+    });
+    return run;
+  }
+  async function ensureLifecycle(remote, container) {
+    const setupKey = container?.[SETUP_META_KEY];
+    if (typeof setupKey !== "string" || setupKey === "") return;
+    const st = lifecycleOf(remote.name);
+    if (!st.setupPromise) {
+      st.setupPromise = runSetupPhase(remote, container, setupKey, st).catch((err) => {
+        st.setupPromise = void 0;
+        throw err;
+      });
+    }
+    await st.setupPromise;
+    const onSession = st.setupExports?.onSession;
+    if (typeof onSession === "function") {
+      await ensureSessionPhase(remote, st, onSession);
+    }
+  }
+  function clearSessionState2() {
+    for (const st of lifecycleStates.values()) {
+      try {
+        st.controller?.abort();
+      } catch {
+      }
+      st.sessionKey = void 0;
+      st.sessionPromise = void 0;
+    }
+  }
   const getScope = (name) => shareScopeMap2[name] ??= /* @__PURE__ */ Object.create(null);
   function emitError(info) {
     try {
@@ -340,7 +485,7 @@ function createRuntime() {
         state: prev?.state ?? "idle",
         breakerState: prev?.breakerState ?? { fails: 0, openUntil: 0 },
         entryInflight: prev?.entryInflight ?? /* @__PURE__ */ new Map(),
-        debug: prev?.debug ?? { entry: r.entry, status: "idle" }
+        debug: prev?.debug ?? { entry: r.entry, status: "idle", setup: "none" }
       });
     }
   }
@@ -609,6 +754,14 @@ function createRuntime() {
   }
   async function loadRemote2(spec, opts) {
     const { remote: name, module: module2 } = parseSpec2(spec);
+    if (module2 && lifecycleSyncRemote === name) {
+      throw new FgError(
+        ErrorCodes.SETUP_RECURSION,
+        `loadRemote("${spec}") re-entered from setup/onSession of "${name}" \u2014 the initialization promise would await itself (deadlock)
+  \u4FEE\u6CD5: setup/onSession \u5185\u4E0D loadRemote \u540C\u4E00\u8FDC\u7A0B\u7684\u6A21\u5757\uFF1B\u9700\u8981\u7684\u4E1A\u52A1\u6A21\u5757\u6539\u4E3A\u5728\u9875\u9762\u7EC4\u4EF6\u5185\u52A0\u8F7D\uFF0C\u6216\u7ECF context \u901A\u9053\u89E3\u8026`,
+        { remote: name }
+      );
+    }
     try {
       hooks.beforeLoadRemote?.({ remote: name, module: module2 });
     } catch (hookErr) {
@@ -635,6 +788,7 @@ function createRuntime() {
       throw err;
     }
     if (!module2) return container;
+    await ensureLifecycle(remote, container);
     const cacheKey = `${name}@${remote.shareScope || "default"}#${module2}`;
     if (!loadedModules.has(cacheKey)) {
       loadedModules.set(
@@ -828,7 +982,8 @@ function createRuntime() {
     loadRemote: loadRemote2,
     getContainer: getContainer2,
     preloadRemote: preloadRemote2,
-    parseSpec: parseSpec2
+    parseSpec: parseSpec2,
+    clearSessionState: clearSessionState2
   };
 }
 var g = globalThis;
@@ -848,10 +1003,153 @@ var loadRemote = runtime.loadRemote;
 var getContainer = runtime.getContainer;
 var preloadRemote = runtime.preloadRemote;
 var parseSpec = runtime.parseSpec;
+var clearSessionState = runtime.clearSessionState;
 var shareScopeMap = runtime.shareScopeMap;
 
 // src/vue-adapter.ts
 var import_vue = require("vue");
+
+// src/pages.ts
+var normSpec = (s) => s.replace(/^[./]+/, "").replace(/\/+$/, "");
+var hasParam = (route) => /(^|\/):[\w]+/.test(route);
+var segs = (route) => route.split("/").filter(Boolean);
+function defaultDeriveSpec(route) {
+  return segs(route).slice(1).filter((seg) => !seg.startsWith(":")).join("/");
+}
+function shadows(earlier, later) {
+  const a = segs(earlier);
+  const b = segs(later);
+  if (a.length !== b.length) return null;
+  if (earlier === later) return "full";
+  let hasParam2 = false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i].startsWith(":")) {
+      hasParam2 = true;
+      continue;
+    }
+    return null;
+  }
+  return hasParam2 ? "param" : null;
+}
+function remoteOfRoute(route, remotes) {
+  if (!remotes) return null;
+  for (const [prefix, name] of Object.entries(remotes)) {
+    if (route === prefix.replace(/\/+$/, "") || route.startsWith(prefix)) return name;
+  }
+  return null;
+}
+function validatePages(pages, options = {}) {
+  const deriveSpec = options.deriveSpec ?? defaultDeriveSpec;
+  const violations = [];
+  const effective = pages.map((p) => normSpec(p.spec ?? deriveSpec(p.route)));
+  pages.forEach((p, i) => {
+    if (p.spec || !hasParam(p.route)) return;
+    pages.forEach((q, j) => {
+      if (i === j) return;
+      if (effective[j] !== effective[i]) return;
+      violations.push({
+        rule: "R1",
+        level: "error",
+        message: `[R1] \u8DEF\u7531 "${p.route}" \u5265\u53C2\u63A8\u5BFC spec "${effective[i]}" \u4E0E\u8DEF\u7531 "${q.route}"${q.spec ? "\uFF08\u663E\u5F0F spec\uFF09" : ""}\u6536\u655B\u76F8\u540C\u3002
+   \u6839\u56E0\uFF1A\u53C2\u6570\u6BB5\u5265\u79BB\u540E expose \u952E\u4E0E\u5176\u5B83\u6761\u76EE\u76F8\u540C\uFF0C\u8BE5\u8DEF\u7531\u4F1A\u9759\u9ED8\u52A0\u8F7D\u9519\u8BEF\u7EC4\u4EF6
+   \uFF08\u771F\u5B9E\u4E8B\u6545\uFF1A\u5E26\u53C2\u52A8\u4F5C\u9875\u8BEF\u8D70\u5217\u8868/\u66F4\u65B0\u8BED\u4E49\uFF0C\u6570\u636E\u98CE\u9669\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u4E3A\u8BE5\u6761\u76EE\u663E\u5F0F\u58F0\u660E spec: '...'\uFF08\u6307\u5411\u5E26\u53C2\u9875\u9762\u81EA\u5DF1\u7684 expose\uFF09\uFF0C\u6216\u8C03\u6574\u8DEF\u7531\u62C6\u5206\u3002`
+      });
+    });
+  });
+  const seenSpec = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const key = effective[i];
+    if (seenSpec.has(key)) {
+      const first = pages[seenSpec.get(key)];
+      const bothExplicit = !!p.spec && !!first.spec;
+      violations.push({
+        rule: "R2",
+        level: "warn",
+        message: `[R2] \u8DEF\u7531 "${p.route}" \u4E0E "${first.route}" \u6709\u6548 spec \u76F8\u540C\uFF08"${key}"\uFF09\u3002${bothExplicit ? "\u4E24\u6761\u5747\u4E3A\u663E\u5F0F spec" : "\u5176\u4E2D\u542B\u63A8\u5BFC spec"}\u2014\u2014\u82E5\u4E3A\u523B\u610F\u7684\u83DC\u5355\u522B\u540D\u53EF\u5FFD\u7565\u672C\u8B66\u544A\uFF0C\u5426\u5219\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenSpec.set(key, i);
+    }
+  });
+  if (options.schema && options.remotes) {
+    pages.forEach((p, i) => {
+      const remote = remoteOfRoute(p.route, options.remotes);
+      if (!remote) return;
+      const entry = options.schema[remote];
+      if (!entry || entry.exists === false) return;
+      const exposes = new Set((entry.exposes ?? []).map(normSpec));
+      if (!exposes.has(effective[i])) {
+        violations.push({
+          rule: "R3",
+          level: "error",
+          message: `[R3] \u8DEF\u7531 "${p.route}" \u7684 spec "${effective[i]}" \u4E0D\u5728\u8FDC\u7A0B "${remote}" \u7684 exposes \u6E05\u5355\u4E2D\u3002
+   \u6839\u56E0\uFF1Aspec \u62FC\u5199\u4E0E\u8FDC\u7A0B exposes \u952E\u4E0D\u4E00\u81F4\uFF08\u8FD0\u884C\u65F6\u5C06 MFU-006 \u52A0\u8F7D\u5931\u8D25\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u6838\u5BF9\u8FDC\u7A0B vite.config exposes \u952E\u540D\uFF0C\u6216\u4FEE\u6B63\u672C\u8868 spec\u3002
+   \u8FDC\u7A0B\u5B9E\u9645 exposes\uFF08\u524D 10\uFF09\uFF1A${[...exposes].slice(0, 10).join("\u3001") || "\uFF08\u7A7A\uFF09"}`
+        });
+      }
+    });
+  }
+  pages.forEach((p, i) => {
+    pages.forEach((q, j) => {
+      if (j <= i) return;
+      const kind = shadows(p.route, q.route);
+      if (!kind) return;
+      violations.push({
+        rule: "R4",
+        level: "error",
+        message: kind === "full" ? `[R4] \u8DEF\u7531\u5B8C\u5168\u91CD\u590D\uFF1A"${p.route}"\uFF08\u7B2C ${i + 1} \u6761\uFF09\u4E0E "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u3002` : `[R4] \u8DEF\u7531 "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u4F1A\u88AB\u66F4\u9760\u524D\u7684 "${p.route}" \u906E\u853D\uFF08\u5339\u914D\u5148\u5230\u5148\u5F97\uFF0C\u540E\u8005\u6210\u6B7B\u8DEF\u7531\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u8C03\u6574\u6570\u7EC4\u987A\u5E8F\uFF08\u66F4\u5177\u4F53\u7684\u9759\u6001\u8DEF\u7531\u653E\u524D\u9762\uFF09\u6216\u5408\u5E76\u6761\u76EE\u3002`
+      });
+    });
+  });
+  const seenName = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const name = typeof p.name === "string" ? p.name : "";
+    if (!name) return;
+    if (seenName.has(name)) {
+      violations.push({
+        rule: "R5",
+        level: "warn",
+        message: `[R5] name "${name}" \u91CD\u590D\uFF08"${pages[seenName.get(name)].route}" \u4E0E "${p.route}"\uFF09\u2014\u2014vue-router \u547D\u540D\u8DF3\u8F6C push({name}) \u5C06\u547D\u4E2D\u524D\u8005\uFF0C\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenName.set(name, i);
+    }
+  });
+  return violations;
+}
+function formatViolations(violations) {
+  const errors = violations.filter((v) => v.level === "error");
+  const warns = violations.filter((v) => v.level === "warn");
+  let out = "";
+  if (errors.length) {
+    out += `[fulgurjs] \u8DEF\u7531\u8868\u6821\u9A8C\u5931\u8D25\uFF08${errors.length} \u9879\uFF0CERROR\uFF09\uFF1A
+` + errors.map((v) => v.message).join("\n") + "\n";
+  }
+  if (warns.length) {
+    out += `[fulgurjs] \u8DEF\u7531\u8868\u6821\u9A8C\u8B66\u544A\uFF08${warns.length} \u9879\uFF0CWARN\uFF09\uFF1A
+` + warns.map((v) => v.message).join("\n");
+  }
+  return out.trim();
+}
+function definePages(pages, options = {}) {
+  const violations = validatePages(pages, options);
+  const errors = violations.filter((v) => v.level === "error");
+  const warns = violations.filter((v) => v.level === "warn");
+  const text = formatViolations(violations);
+  if (text) {
+    if (errors.length && options.strict !== false) {
+      throw new Error(text);
+    }
+    console[errors.length ? "error" : "warn"](text);
+  }
+  return pages;
+}
+
+// src/vue-adapter.ts
 var ERROR_STYLE = {
   padding: "16px",
   border: "1px solid #fde2e2",
@@ -888,10 +1186,111 @@ function createRemoteComponent(loadRemote2) {
     });
   };
 }
+var cleanCompName = (spec) => "Fulgurjs_" + spec.replace(/[^A-Za-z0-9_-]/g, "_");
+function defaultDeriveSpec2(route) {
+  return route.split("/").filter(Boolean).slice(1).filter((seg) => !seg.startsWith(":")).join("/");
+}
+function createHostPages(options, load) {
+  const { pages, remotePrefixes, deriveSpec, schema, strict, base, beforeLoad, loadingComponent, errorComponent, delay } = options;
+  definePages(pages, { deriveSpec, remotes: remotePrefixes, schema, strict });
+  const prefixes = Object.entries(remotePrefixes).map(([p, name]) => [p.endsWith("/") ? p : `${p}/`, name]).sort((a, b) => b[0].length - a[0].length);
+  const remoteOf = (route) => {
+    for (const [prefix, name] of prefixes) {
+      if (route.startsWith(prefix) || `${route}/` === prefix) return name;
+    }
+    throw new Error(
+      `[fulgurjs] page route "${route}" matches none of remotePrefixes { ${Object.entries(remotePrefixes).map(([k, v]) => `'${k}': '${v}'`).join(", ")} }
+  \u6839\u56E0: \u9875\u9762\u8868\u6761\u76EE\u7684\u8DEF\u7531\u4E0D\u5728\u4EFB\u4F55\u5DF2\u58F0\u660E\u7684\u8FDC\u7A0B\u524D\u7F00\u4E0B\u3002
+  \u4FEE\u6CD5: \u5728 remotePrefixes \u8865\u5145\u8BE5\u8DEF\u7531\u524D\u7F00 \u2192 \u8FDC\u7A0B\u540D\u7684\u6620\u5C04\uFF0C\u6216\u4FEE\u6B63\u9875\u9762\u8868 route\u3002`
+    );
+  };
+  for (const page of pages) remoteOf(page.route);
+  const specOf = (page) => {
+    const s = page.spec ?? (deriveSpec ? deriveSpec(page.route) : defaultDeriveSpec2(page.route));
+    return `${remoteOf(page.route)}/${String(s).replace(/^[./]+/, "")}`;
+  };
+  const baseNorm = base && base !== "/" ? base.endsWith("/") ? base : `${base}/` : "";
+  const matchSegments = (pattern, path) => {
+    const patSegs = pattern.split("/").filter(Boolean);
+    const pathSegs = path.split("/").filter(Boolean);
+    if (patSegs.length !== pathSegs.length) return null;
+    const params = {};
+    for (let i = 0; i < patSegs.length; i++) {
+      const seg = patSegs[i];
+      if (seg.startsWith(":")) {
+        try {
+          params[seg.slice(1)] = decodeURIComponent(pathSegs[i]);
+        } catch {
+          return null;
+        }
+      } else if (seg !== pathSegs[i]) {
+        return null;
+      }
+    }
+    return params;
+  };
+  let cacheSession;
+  const compCache = /* @__PURE__ */ new Map();
+  const resolve = (rawPath) => {
+    let clean = String(rawPath ?? "");
+    if (baseNorm) {
+      if (clean === baseNorm.replace(/\/$/, "")) clean = "/";
+      else if (clean.startsWith(baseNorm)) clean = `/${clean.slice(baseNorm.length)}`;
+    }
+    clean = (clean.replace(/\/+$/, "") || "/").split("?")[0].split("#")[0];
+    for (const page of pages) {
+      const params = matchSegments(page.route, clean);
+      if (params) return { page, remote: remoteOf(page.route), spec: specOf(page), params };
+    }
+    return null;
+  };
+  const component = (spec) => {
+    const sk = (globalThis.__FULGURJS_APP_CONFIG__ ?? {}).sessionKey;
+    const sessionKey = typeof sk === "string" ? sk : void 0;
+    if (sessionKey !== cacheSession) {
+      compCache.clear();
+      cacheSession = sessionKey;
+    }
+    let comp = compCache.get(spec);
+    if (!comp) {
+      const name = cleanCompName(spec);
+      const asyncComp = (0, import_vue.defineAsyncComponent)({
+        loader: async () => {
+          await beforeLoad?.();
+          const mod = await load(spec);
+          const inner = mod?.default ?? mod;
+          if (!inner) {
+            throw new Error(
+              `[fulgurjs] remote module "${spec}" did not export a component (got ${inner === null ? "null" : typeof inner})\u3002
+  \u4FEE\u6CD5: \u6838\u5BF9\u8FDC\u7A0B exposes \u952E\u540D\u4E0E\u9875\u9762\u8868 spec \u662F\u5426\u4E00\u81F4\uFF08MFU-006 \u8BED\u4E49\uFF09`
+            );
+          }
+          return inner;
+        },
+        loadingComponent,
+        errorComponent: errorComponent ?? RemoteErrorPlaceholder,
+        delay
+      });
+      comp = (0, import_vue.defineComponent)({
+        name,
+        inheritAttrs: false,
+        setup: (_props, ctx) => () => (0, import_vue.h)(asyncComp, ctx.attrs, ctx.slots)
+      });
+      compCache.set(spec, comp);
+    }
+    return comp;
+  };
+  const keepAliveNames = pages.filter((p) => p.keepAlive).map((p) => cleanCompName(specOf(p)));
+  return { pages, resolve, component, keepAliveNames };
+}
 
 // src/vue.ts
 var remoteComponent = createRemoteComponent(loadRemote);
+function createHostPages2(options) {
+  return createHostPages(options, loadRemote);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createHostPages,
   remoteComponent
 });

package/dist/vue.d.cts

@@ -1,6 +1,10 @@
 import * as vue from 'vue';
-import { RemoteComponentOptions } from './vue-adapter.cjs';
+import { createHostPages as createHostPages$1, HostPages, RemoteComponentOptions } from './vue-adapter.cjs';
+export { HostPagesOptions, ResolvedHostPage } from './vue-adapter.cjs';
+import './pages.cjs';
 
 declare const remoteComponent: (spec: string, opts?: RemoteComponentOptions) => vue.Component;
+/** 宿主页面适配器（绑定本包运行时的 loadRemote；选项与返回值类型见 vue-adapter） */
+declare function createHostPages(options: Parameters<typeof createHostPages$1>[0]): HostPages;
 
-export { RemoteComponentOptions, remoteComponent };
+export { HostPages, RemoteComponentOptions, createHostPages, remoteComponent };

package/dist/vue.d.ts

@@ -1,6 +1,10 @@
 import * as vue from 'vue';
-import { RemoteComponentOptions } from './vue-adapter.js';
+import { createHostPages as createHostPages$1, HostPages, RemoteComponentOptions } from './vue-adapter.js';
+export { HostPagesOptions, ResolvedHostPage } from './vue-adapter.js';
+import './pages.js';
 
 declare const remoteComponent: (spec: string, opts?: RemoteComponentOptions) => vue.Component;
+/** 宿主页面适配器（绑定本包运行时的 loadRemote；选项与返回值类型见 vue-adapter） */
+declare function createHostPages(options: Parameters<typeof createHostPages$1>[0]): HostPages;
 
-export { RemoteComponentOptions, remoteComponent };
+export { HostPages, RemoteComponentOptions, createHostPages, remoteComponent };

package/dist/vue.js

@@ -1,3 +1,4 @@
 import { loadRemote } from "./runtime.js";
-import { createRemoteComponent } from "./vue-adapter.js";
+import { createRemoteComponent, createHostPages as createHostPagesWithLoader } from "./vue-adapter.js";
 export const remoteComponent = createRemoteComponent(loadRemote);
+export const createHostPages = (options) => createHostPagesWithLoader(options, loadRemote);

package/docs//350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -8,11 +8,11 @@
 |---------|--------------------|
 | 主应用 registerMicroApps | 宿主 `federation({ remotes })` |
 | 子应用 entry（HTML） | remote entry（dev: `@fulgurjs-entry.js` 中间件 / prod: `fulgurjs-remoteEntry.js`） |
-| 子应用生命周期 mount/unmount | 页面级 exposes（组件即入口，无生命周期样板） |
+| 子应用生命周期 mount/unmount | 页面级 exposes（组件即入口，无生命周期样板）；启动期初始化 = 远程 `federation({ setup })`（setup/onSession，见三C 节） |
 | 主子应用 window 隔离/沙箱 | 无沙箱：同 realm 直渲染（`window.xxx` 全局桥自然可用） |
 | props 传递（qiankun 传参） | 组件 props（路由通道 = params+query 合并；弹窗通道 = 显式 v-bind） |
 | 公共依赖 externals/主应用共享 | `shared`（singleton 协商，"已加载优先"） |
-| `qiankun` 运行时 + single-spa | `@fulgurjs/federation/runtime`（运行时内核 15KB 级，无 single-spa） |
+| `qiankun` 运行时 + single-spa | `@fulgurjs/federation/runtime`（运行时内核 20KB 级，无 single-spa） |
 
 应用代码统一从 `@fulgurjs/federation/runtime` 导入。Vite 配置继续从 `@fulgurjs/federation` 导入插件。升级自 3.x 时，将 `virtual:fulgurjs-api` 替换为物理子路径；`remoteSchema` 仍按具名导入，开发态由插件填充，构建态为空清单。
 
@@ -21,7 +21,8 @@
 1. **子应用装插件 + exposes**：把原菜单路由表逐页映射为 `exposes`（`./pages/bpm/task/todo` 对应路由 `bpm/task/todo`）。
 2. **shared 声明**：vue/pinia/vue-router 设 singleton；**不要**把业务库（element-plus/avue/dayjs 等）放 shared——插件会在预构建与构建期自动处理其内部对 shared 键的引用（UMD/CJS-only 依赖支持）。
 3. **宿主装插件 + remotes**：菜单 URL 通道由 `resolveFulgurjsPageFromPath` 按路由表解析 spec（见 `admin/src/qiankun/fulgurjsPages.ts`）。
-4. **全局环境迁移**：子应用依赖宿主的全局（用户/字典 store、i18n、全局组件）→ 写 `federatedBoot.ts` expose，宿主加载页面前 `bootRemoteOnce` 执行；失败必须显式报错（H3）。
+4. **全局环境迁移**：子应用依赖宿主的全局（用户/字典 store、i18n、全局组件、全局样式）→ 在子应用 `federation({ setup })` 声明初始化入口文件：默认导出 `setup(context)` 应用级执行一次（全局组件/样式/locale），可选具名导出 `onSession(context)` 按宿主 sessionKey 去重同步用户/权限/字典（换账号自动重跑）；宿主正常 `loadRemote` 页面即可，**无需手写「loadRemote 启动器并调用」**；失败必须显式报错（H3，MFU-011~014）。
+   > 旧写法（`exposes` 启动器 + 宿主 `bootRemoteOnce` 手动调用）**继续可用**，属兼容形态，新迁移项目请用 `setup`。
 5. **路由参数**：页面组件用 `defineProps` 声明参数（id/taskId 等）；宿主路由通道把 params+query 作为 props 传入。
 6. **跨应用弹窗**：原 iframe 嵌子应用页 → `fulgurjsPageComponent(spec)` 直渲染 + props（见 FormDetailsModal）；真外链（数据驱动 URL、AMIS 站点）保留 iframe。
 7. **公共依赖坑**：
@@ -82,15 +83,17 @@ realm 检测等特殊场景，常规集成无需使用。
 原 qiankun `props` / `globalState` / `window.*` 裸口子，统一收编为 context 一等公民通道（对标乾坤 props，带类型与错误契约）：
 
 ```ts
-// 宿主桥（admin/src/fulgurjs/host/bridge.ts）——登录完成后一次性提供
-import { provideAppContext } from '@fulgurjs/federation/runtime'
+// 宿主桥（admin/src/fulgurjs/host/bridge.ts）——登录态同步（可多次调用，幂等 merge）
+import { provideAppContext, clearAppContext } from '@fulgurjs/federation/runtime'
 provideAppContext({
   user, getToken, store, hostApp, locale,   // 只传有真实消费的键（token 一律 getToken() 拉取）
+  sessionKey: 's-101-…',              // 非敏感登录代次 ID：每次成功登录/重登生成新值（禁用 token 充当）
   events: { main: mainEvents },       // 方法池：宿主提供 main.*，子应用反向注册 bpm.* / lowcode.*
   // 项目扩展位：自定义键按需自行提供（如 baseUrl）
 })
+// 退出登录：clearAppContext()（清 context + 作废远程会话信号/onSession 去重）
 
-// 远程启动引导（xxx/src/fulgurjs/exposes/federatedBoot.ts）——显式校验消费
+// 远程初始化（xxx/src/fulgurjs/setup.ts，经 vite federation({ setup }) 声明）——显式校验消费
 import { requireAppContext } from '@fulgurjs/federation/runtime'
 const { store, user, hostApp } = requireAppContext('store', 'user', 'hostApp')
 // 缺键 → [fulgurjs:CC-001]（三段式，指向宿主桥）；独立直开远程页 → [fulgurjs:CC-002]
@@ -102,8 +105,8 @@ const dict = getAppContext().events?.main?.getDictItems?.('sex')
 
 要点：
 
-- **时序契约**：bridge（provide）→ federatedBoot（require）→ 页面 loadRemote；违反即在 boot 显式失败（CC-001），无静默；
-- **数据语义**：传输层快照 + 函数引用，非响应式（与乾坤 props 同语义）。"实时"三通道 = ①函数引用拉取（`getToken()` / `events.main.*` 每次执行宿主最新闭包）②宿主 pinia 共享响应式（`useUserStore(ctx.store)`）③登录变更 = 刷新重跑；
+- **时序契约**：bridge（provide）→ 远程 setup/onSession（require）→ 页面模块返回；违反即在初始化处显式失败（CC-001 / MFU-013），无静默；
+- **数据语义**：传输层快照 + 函数引用，非响应式（与乾坤 props 同语义）。"实时"两通道 = ①函数引用拉取（`getToken()` / `events.main.*` 每次执行宿主最新闭包）②宿主 pinia 共享响应式（`useUserStore(ctx.store)`）；**同页换账号不依赖页面刷新**——宿主重新 provide 最新 context + 新 sessionKey，远程 onSession 检测到新代次自动重跑；
 - **嵌套对象（events）是引用共享**：子应用挂属性即时可见（同 realm 直引用）；
 - **方法引用两条通道**：高频热路径（token/字典/文件 URL、反向注册）走 context 函数引用；低频/重逻辑跨应用调用走 exposes 方法模块——远程 `src/fulgurjs/exposes/api.ts` 导出纯函数（不挂 Vue 组件），对面 `await loadRemote('remote/api')`；
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
   "license": "MIT",

package/dist/chunk-AYS56IRF.js

@@ -1,42 +0,0 @@
-// src/vue-adapter.ts
-import { defineAsyncComponent, defineComponent, h } from "vue";
-var ERROR_STYLE = {
-  padding: "16px",
-  border: "1px solid #fde2e2",
-  borderRadius: "4px",
-  background: "#fef0f0",
-  color: "#c45656",
-  fontSize: "13px",
-  lineHeight: "1.6"
-};
-var RemoteErrorPlaceholder = defineComponent({
-  name: "FulgurjsRemoteError",
-  props: { error: { type: Object, default: void 0 } },
-  setup(props) {
-    return () => {
-      const err = props.error;
-      const code = err?.code ?? "UNKNOWN";
-      const message = err?.message ?? String(props.error ?? "unknown error");
-      return h("div", { style: ERROR_STYLE }, [
-        h("p", { style: "margin:0 0 4px;font-weight:600" }, `\u8FDC\u7A0B\u7EC4\u4EF6\u52A0\u8F7D\u5931\u8D25\uFF08\u9519\u8BEF\u7801 ${code}\uFF09`),
-        h("p", { style: "margin:0 0 8px;word-break:break-all" }, message),
-        h("p", { style: "margin:0" }, "\u4FEE\u6CD5\uFF1A\u2460 \u6838\u5BF9 spec \u7684\u300C\u8FDC\u7A0B\u540D/expose \u540D\u300D\u4E0E\u8FDC\u7A0B\u5E94\u7528 exposes \u662F\u5426\u4E00\u81F4\uFF08MFU-006/008\uFF09\uFF1B\u2461 \u6838\u5BF9 remotes \u5730\u5740\u7AEF\u53E3\u4E0E\u8FDC\u7A0B\u670D\u52A1\u53EF\u8FBE\u6027\u3001remoteEntry \u662F\u5426\u53EF\u8BBF\u95EE\uFF08MFU-001\uFF09\uFF1B\u2462 \u67E5\u770B window \u7684 fulgurjs:error \u4E8B\u4EF6\u4E0E console \u540C\u6E90\u9519\u8BEF\u5B9A\u4F4D\u6839\u56E0\u3002")
-      ]);
-    };
-  }
-});
-function createRemoteComponent(loadRemote) {
-  return function remoteComponent(spec, opts = {}) {
-    return defineAsyncComponent({
-      loader: () => loadRemote(spec, { retries: opts.retries }).then((m) => m.default ?? m),
-      loadingComponent: opts.loadingComponent,
-      errorComponent: opts.errorComponent ?? RemoteErrorPlaceholder,
-      delay: opts.delay,
-      timeout: opts.timeout
-    });
-  };
-}
-
-export {
-  createRemoteComponent
-};