@fulgurjs/federation 3.0.1 → 4.1.0

package/dist/vue.cjs

@@ -20,10 +20,10 @@ 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);
-var import_vue = require("vue");
 
 // src/semver.ts
 var VERSION_RE = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-((?:[0-9A-Za-z-]+)(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -254,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;
@@ -282,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 {
@@ -341,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" }
       });
     }
   }
@@ -610,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) {
@@ -636,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(
@@ -829,7 +982,8 @@ function createRuntime() {
     loadRemote: loadRemote2,
     getContainer: getContainer2,
     preloadRemote: preloadRemote2,
-    parseSpec: parseSpec2
+    parseSpec: parseSpec2,
+    clearSessionState: clearSessionState2
   };
 }
 var g = globalThis;
@@ -849,9 +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.ts
+// 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",
@@ -863,9 +1161,7 @@ var ERROR_STYLE = {
 };
 var RemoteErrorPlaceholder = (0, import_vue.defineComponent)({
   name: "FulgurjsRemoteError",
-  props: {
-    error: { type: Object, default: void 0 }
-  },
+  props: { error: { type: Object, default: void 0 } },
   setup(props) {
     return () => {
       const err = props.error;
@@ -874,25 +1170,127 @@ var RemoteErrorPlaceholder = (0, import_vue.defineComponent)({
       return (0, import_vue.h)("div", { style: ERROR_STYLE }, [
         (0, import_vue.h)("p", { style: "margin:0 0 4px;font-weight:600" }, `\u8FDC\u7A0B\u7EC4\u4EF6\u52A0\u8F7D\u5931\u8D25\uFF08\u9519\u8BEF\u7801 ${code}\uFF09`),
         (0, import_vue.h)("p", { style: "margin:0 0 8px;word-break:break-all" }, message),
-        (0, import_vue.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"
-        )
+        (0, import_vue.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 remoteComponent(spec, opts = {}) {
-  return (0, import_vue.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
-  });
+function createRemoteComponent(loadRemote2) {
+  return function remoteComponent2(spec, opts = {}) {
+    return (0, import_vue.defineAsyncComponent)({
+      loader: () => loadRemote2(spec, { retries: opts.retries }).then((m) => m.default ?? m),
+      loadingComponent: opts.loadingComponent,
+      errorComponent: opts.errorComponent ?? RemoteErrorPlaceholder,
+      delay: opts.delay,
+      timeout: opts.timeout
+    });
+  };
+}
+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,35 +1,10 @@
-import { Component } from 'vue';
+import * as vue from 'vue';
+import { createHostPages as createHostPages$1, HostPages, RemoteComponentOptions } from './vue-adapter.cjs';
+export { HostPagesOptions, ResolvedHostPage } from './vue-adapter.cjs';
+import './pages.cjs';
 
-/**
- * Vue 生态层：remoteComponent() 远程组件直渲染。
- *
- * 定位：runtime.js 保持框架无关（不 import vue，gzip 红线守卫），
- * Vue 封装按需引入——独立文件、零 runtime 体积增量。
- *
- * 语义（用法与选项见 README §8）：
- * - 内部 = defineAsyncComponent({ loader: () => loadRemote(spec, opts).then(m => m.default ?? m) })；
- * - H3 零兜底：加载失败显式进错误态（fulgurjs:error 事件由 runtime 层照常发出），
- *   不传 errorComponent 时渲染内置默认错误占位（文案含错误码+根因+修法，显式非静默）；
- * - 模块去重沿用 loadRemote 内部 Promise 缓存（同 spec 不重复加载）；
- * - 返回标准 Vue 异步组件，props（如 form-params）在使用处透传，不改分发机制。
- */
+declare const remoteComponent: (spec: string, opts?: RemoteComponentOptions) => vue.Component;
+/** 宿主页面适配器（绑定本包运行时的 loadRemote；选项与返回值类型见 vue-adapter） */
+declare function createHostPages(options: Parameters<typeof createHostPages$1>[0]): HostPages;
 
-interface RemoteComponentOptions {
-    /** 加载期间展示的组件 */
-    loadingComponent?: Component;
-    /** 加载失败展示的组件（收到 error prop）；不传时用内置默认错误占位 */
-    errorComponent?: Component;
-    /** 单次调用级重试覆盖，透传 loadRemote（缺省用远程注册值，默认 2） */
-    retries?: number;
-    /** defineAsyncComponent delay（ms）：切换到 loadingComponent 前的等待，默认 200 */
-    delay?: number;
-    /** defineAsyncComponent timeout（ms）：超时进错误态；不设则由 runtime 容器超时兜底 */
-    timeout?: number;
-}
-/**
- * 创建远程组件：`remoteComponent('demo-host/FormRouterPage')`。
- * 返回标准 Vue 异步组件，使用处直接透传 props（如 form-params）。
- */
-declare function remoteComponent(spec: string, opts?: RemoteComponentOptions): Component;
-
-export { type RemoteComponentOptions, remoteComponent };
+export { HostPages, RemoteComponentOptions, createHostPages, remoteComponent };

package/dist/vue.d.ts

@@ -1,35 +1,10 @@
-import { Component } from 'vue';
+import * as vue from 'vue';
+import { createHostPages as createHostPages$1, HostPages, RemoteComponentOptions } from './vue-adapter.js';
+export { HostPagesOptions, ResolvedHostPage } from './vue-adapter.js';
+import './pages.js';
 
-/**
- * Vue 生态层：remoteComponent() 远程组件直渲染。
- *
- * 定位：runtime.js 保持框架无关（不 import vue，gzip 红线守卫），
- * Vue 封装按需引入——独立文件、零 runtime 体积增量。
- *
- * 语义（用法与选项见 README §8）：
- * - 内部 = defineAsyncComponent({ loader: () => loadRemote(spec, opts).then(m => m.default ?? m) })；
- * - H3 零兜底：加载失败显式进错误态（fulgurjs:error 事件由 runtime 层照常发出），
- *   不传 errorComponent 时渲染内置默认错误占位（文案含错误码+根因+修法，显式非静默）；
- * - 模块去重沿用 loadRemote 内部 Promise 缓存（同 spec 不重复加载）；
- * - 返回标准 Vue 异步组件，props（如 form-params）在使用处透传，不改分发机制。
- */
+declare const remoteComponent: (spec: string, opts?: RemoteComponentOptions) => vue.Component;
+/** 宿主页面适配器（绑定本包运行时的 loadRemote；选项与返回值类型见 vue-adapter） */
+declare function createHostPages(options: Parameters<typeof createHostPages$1>[0]): HostPages;
 
-interface RemoteComponentOptions {
-    /** 加载期间展示的组件 */
-    loadingComponent?: Component;
-    /** 加载失败展示的组件（收到 error prop）；不传时用内置默认错误占位 */
-    errorComponent?: Component;
-    /** 单次调用级重试覆盖，透传 loadRemote（缺省用远程注册值，默认 2） */
-    retries?: number;
-    /** defineAsyncComponent delay（ms）：切换到 loadingComponent 前的等待，默认 200 */
-    delay?: number;
-    /** defineAsyncComponent timeout（ms）：超时进错误态；不设则由 runtime 容器超时兜底 */
-    timeout?: number;
-}
-/**
- * 创建远程组件：`remoteComponent('demo-host/FormRouterPage')`。
- * 返回标准 Vue 异步组件，使用处直接透传 props（如 form-params）。
- */
-declare function remoteComponent(spec: string, opts?: RemoteComponentOptions): Component;
-
-export { type RemoteComponentOptions, remoteComponent };
+export { HostPages, RemoteComponentOptions, createHostPages, remoteComponent };