@fulgurjs/federation 5.3.2 → 5.4.0

package/dist/{chunk-TOT3P7AK.js → chunk-BTJGYDHT.js}

@@ -252,6 +252,14 @@ function createRuntime() {
   const remotes = /* @__PURE__ */ new Map();
   const plugins = [];
   const reportedSingletonSkews = /* @__PURE__ */ new Set();
+  const resolvedShareSnapshots = /* @__PURE__ */ new Map();
+  const shareRequestKey = (name, opts) => JSON.stringify([
+    opts.shareScope || "default",
+    opts.shareKey || name,
+    opts.requiredVersion ?? null,
+    !!opts.singleton,
+    !!opts.strictVersion
+  ]);
   const loadedModules = /* @__PURE__ */ new Map();
   const remoteManifests = /* @__PURE__ */ new Map();
   const stylesheetLoads = /* @__PURE__ */ new WeakMap();
@@ -472,14 +480,16 @@ function createRuntime() {
   }
   function registerPlugins2(list) {
     plugins.push(...list);
+    resolvedShareSnapshots.clear();
     applyPlugins();
   }
-  async function loadShare2(name, opts = {}) {
+  function selectShareEntry(name, opts, readyOnly = false) {
     const scopeName = opts.shareScope || "default";
     const shareKey = opts.shareKey || name;
     const scope = getScope(scopeName);
     const byName = scope[shareKey] || {};
-    const versions = Object.keys(byName);
+    const versions = Object.keys(byName).filter((v) => !readyOnly || opts.singleton || byName[v].value !== void 0);
+    if (readyOnly && versions.length === 0) return void 0;
     const req = opts.requiredVersion;
     const satisfying = versions.filter(
       (v) => req === void 0 || req === false || satisfies(v, req)
@@ -512,49 +522,121 @@ function createRuntime() {
       pick = [...satisfying].sort(compareVersions).pop();
       if (!pick) {
         if (opts.strictVersion) {
-          const err2 = new FgError(
+          const err = new FgError(
             ErrorCodes.SHARE_STRICT_VERSION,
             `\u73B0\u8C61\uFF1A\u5171\u4EAB\u4F5C\u7528\u57DF "${scopeName}" \u4E2D\u627E\u4E0D\u5230\u7B26\u5408\u8981\u6C42\u7684 "${shareKey}"\u3002
 \u539F\u56E0\uFF1A\u8981\u6C42\u7248\u672C ${req}\uFF0C\u5F53\u524D\u53EF\u7528\u7248\u672C\u4E3A ${versions.join("\u3001") || "\u65E0"}\u3002
 \u4FEE\u6CD5\uFF1A\u7EDF\u4E00\u5BBF\u4E3B\u4E0E\u8FDC\u7A0B\u7684\u4F9D\u8D56\u7248\u672C\uFF0C\u6216\u4FEE\u6B63 shared.requiredVersion\u3002`
           );
-          emitError({ remote: shareKey, error: err2 });
-          throw err2;
+          emitError({ remote: shareKey, error: err });
+          throw err;
         }
-        if (opts.fallback) return opts.fallback();
-        const err = new FgError(
-          ErrorCodes.SHARE_NOT_AVAILABLE,
-          `\u73B0\u8C61\uFF1A\u65E0\u6CD5\u52A0\u8F7D\u5171\u4EAB\u4F9D\u8D56 "${shareKey}"\u3002
-\u539F\u56E0\uFF1A\u4F5C\u7528\u57DF "${scopeName}" \u4E2D\u6CA1\u6709\u7B26\u5408 ${req ?? "\u4EFB\u610F\u7248\u672C"} \u8981\u6C42\u7684\u7248\u672C\uFF0C\u4E14\u672A\u914D\u7F6E\u672C\u5730\u526F\u672C\u3002
-\u4FEE\u6CD5\uFF1A\u5728\u5BBF\u4E3B\u6216\u8FDC\u7A0B\u6CE8\u518C\u8BE5\u4F9D\u8D56\uFF0C\u6216\u4E3A shared \u914D\u7F6E\u53EF\u7528\u7684\u672C\u5730\u526F\u672C\u3002`,
-          { shareKey, requiredVersion: req }
-        );
-        emitError({ remote: shareKey, error: err });
-        throw err;
+        return void 0;
       }
     }
-    let entry = byName[pick];
+    return byName[pick];
+  }
+  function registerFallbackInstance(name, opts, instance) {
+    const localVersion = opts.localVersion;
+    if (!localVersion || instance === void 0) return;
+    const scopeName = opts.shareScope || "default";
+    const key = opts.shareKey || name;
+    const scope = getScope(scopeName);
+    const byName = Object.hasOwn(scope, key) ? scope[key] : void 0;
+    if (byName && Object.keys(byName).length > 0) {
+      try {
+        const pick = selectShareEntry(name, opts);
+        if (pick && pick.value === void 0 && pick.version === localVersion) {
+          pick.value = instance;
+          pick.loaded = true;
+        }
+      } catch {
+      }
+      return;
+    }
+    registerShare2(scopeName, key, localVersion, () => Promise.resolve(instance), {
+      from: "fulgurjs:local-fallback",
+      loaded: true
+    });
+    const fresh = scope[key]?.[localVersion];
+    if (fresh) fresh.value = instance;
+  }
+  async function loadShare2(name, opts = {}) {
+    const scopeName = opts.shareScope || "default";
+    const shareKey = opts.shareKey || name;
+    const byName = getScope(scopeName)[shareKey] || {};
+    let entry = selectShareEntry(name, opts);
+    if (!entry) {
+      if (opts.fallback) {
+        const instance2 = await opts.fallback();
+        registerFallbackInstance(name, opts, instance2);
+        return instance2;
+      }
+      const err = new FgError(
+        ErrorCodes.SHARE_NOT_AVAILABLE,
+        `\u73B0\u8C61\uFF1A\u65E0\u6CD5\u52A0\u8F7D\u5171\u4EAB\u4F9D\u8D56 "${shareKey}"\u3002
+\u539F\u56E0\uFF1A\u4F5C\u7528\u57DF "${scopeName}" \u4E2D\u6CA1\u6709\u7B26\u5408 ${opts.requiredVersion ?? "\u4EFB\u610F\u7248\u672C"} \u8981\u6C42\u7684\u7248\u672C\uFF0C\u4E14\u672A\u914D\u7F6E\u672C\u5730\u526F\u672C\u3002
+\u4FEE\u6CD5\uFF1A\u5728\u5BBF\u4E3B\u6216\u8FDC\u7A0B\u6CE8\u518C\u8BE5\u4F9D\u8D56\uFF0C\u6216\u4E3A shared \u914D\u7F6E\u53EF\u7528\u7684\u672C\u5730\u526F\u672C\u3002`,
+        { shareKey, requiredVersion: opts.requiredVersion }
+      );
+      emitError({ remote: shareKey, error: err });
+      throw err;
+    }
     if (hooks.resolveShare) {
       const picked = await hooks.resolveShare({
         shareKey,
         shareScope: scopeName,
-        requiredVersion: req,
+        requiredVersion: opts.requiredVersion,
         picked: entry,
         available: Object.values(byName)
       });
       if (picked) entry = picked;
     }
+    if (entry.value !== void 0) {
+      resolvedShareSnapshots.set(shareRequestKey(name, opts), entry);
+      return entry.value;
+    }
     entry.loaded = true;
-    const instance = await entry.get();
-    entry.value = instance;
-    return instance;
+    if (!entry.pendingGet) {
+      try {
+        entry.pendingGet = entry.get();
+      } catch (e) {
+        entry.pendingGet = Promise.reject(e);
+      }
+    }
+    const pending = entry.pendingGet;
+    let instance;
+    try {
+      instance = await pending;
+    } catch (e) {
+      if (entry.value !== void 0) {
+        resolvedShareSnapshots.set(shareRequestKey(name, opts), entry);
+        return entry.value;
+      }
+      entry.loaded = false;
+      throw e;
+    } finally {
+      if (entry.pendingGet === pending) entry.pendingGet = void 0;
+    }
+    if (entry.value === void 0) entry.value = instance;
+    resolvedShareSnapshots.set(shareRequestKey(name, opts), entry);
+    return entry.value;
   }
   function getLoadedShare2(name, opts = {}) {
-    const shareKey = opts.shareKey || name;
-    const byName = getScope(opts.shareScope || "default")[shareKey] || {};
-    const ready = Object.keys(byName).filter((v) => byName[v].value !== void 0);
-    if (ready.length === 0) return void 0;
-    return byName[ready.sort(compareVersions).pop()].value;
+    if (hooks.resolveShare) return resolvedShareSnapshots.get(shareRequestKey(name, opts))?.value;
+    return selectShareEntry(name, opts, true)?.value;
+  }
+  function pinLoadedShare2(name, opts, localVersion, instance) {
+    if (instance === void 0) return;
+    let entry;
+    try {
+      entry = selectShareEntry(name, opts);
+    } catch {
+      return;
+    }
+    if (!entry || entry.value !== void 0 || entry.version !== localVersion) return;
+    entry.value = instance;
+    entry.loaded = true;
   }
   function sanitizeUrl(u) {
     try {
@@ -986,6 +1068,7 @@ ${hints.join("\n")}`,
     registerPlugins: registerPlugins2,
     loadShare: loadShare2,
     getLoadedShare: getLoadedShare2,
+    pinLoadedShare: pinLoadedShare2,
     loadRemote: loadRemote2,
     getContainer: getContainer2,
     preloadRemote: preloadRemote2,
@@ -1007,6 +1090,7 @@ var registerRemote = runtime.registerRemote;
 var registerPlugins = runtime.registerPlugins;
 var loadShare = runtime.loadShare;
 var getLoadedShare = runtime.getLoadedShare;
+var pinLoadedShare = runtime.pinLoadedShare;
 var loadRemote = runtime.loadRemote;
 var getContainer = runtime.getContainer;
 var preloadRemote = runtime.preloadRemote;
@@ -1054,7 +1138,15 @@ var BridgeErrorCodes = {
   /** 桥接准备或生命周期失败（details.phase = getContext | mount | unmount） */
   BRIDGE_LIFECYCLE_FAILED: "MFU-016",
   /** 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾） */
-  BRIDGE_SESSION_MISMATCH: "MFU-017"
+  BRIDGE_SESSION_MISMATCH: "MFU-017",
+  /** 路由同步配置/前缀冲突（basePath 非法、同页前缀冲突或重叠） */
+  ROUTING_CONFIG_INVALID: "MFU-030",
+  /** 路由协议缺失/通道失效（子应用未声明 routing 协议，或已销毁通道被再次使用） */
+  ROUTING_PROTOCOL_MISSING: "MFU-031",
+  /** 非法导航（目标越界前缀、非法 go 参数、失效实例的请求） */
+  ROUTING_NAVIGATION_INVALID: "MFU-032",
+  /** 路由准备/同步失败（重定向循环、子应用路由准备失败且已阻止错误页面显示） */
+  ROUTING_SYNC_FAILED: "MFU-033"
 };
 function invalidBridgeContractError(spec, mod) {
   const actual = mod === null ? "null" : typeof mod;
@@ -1111,6 +1203,42 @@ function invalidSessionKeyError(spec, value) {
     { spec, value: String(value) }
   );
 }
+function routingConfigError(spec, reason) {
+  return new FgError(
+    BridgeErrorCodes.ROUTING_CONFIG_INVALID,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 URL \u540C\u6B65\u914D\u7F6E\u65E0\u6CD5\u542F\u7528\u3002
+\u539F\u56E0\uFF1A${reason}
+\u4FEE\u6CD5\uFF1A\u4FEE\u6B63 routing.basePath \u4E3A\u5BBF\u4E3B\u8DEF\u7531\u89C6\u89D2\u7684\u9759\u6001\u7EDD\u5BF9\u8DEF\u5F84\uFF08\u5982 "/approval"\uFF09\uFF0C\u5E76\u4FDD\u8BC1\u540C\u9875\u5404\u540C\u6B65\u5B9E\u4F8B\u524D\u7F00\u4E92\u4E0D\u91CD\u53E0\uFF1B\u5BBF\u4E3B\u8DEF\u7531\u9700\u58F0\u660E\u5BF9\u5E94\u7684\u540E\u7F00\u5339\u914D\uFF08Vue "/approval/:pathMatch(.*)*"\u3001React "/approval/*"\uFF09\u3002`,
+    { spec }
+  );
+}
+function routingProtocolError(spec, reason) {
+  return new FgError(
+    BridgeErrorCodes.ROUTING_PROTOCOL_MISSING,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 URL \u540C\u6B65\u901A\u9053\u4E0D\u53EF\u7528\u3002
+\u539F\u56E0\uFF1A${reason}
+\u4FEE\u6CD5\uFF1A\u5B50\u5E94\u7528\u4EE5 defineBridgeApp(\u5DE5\u5382, { routing: true }) \u58F0\u660E\u8DEF\u7531\u534F\u8BAE\u5E76\u5728\u5DE5\u5382\u7B2C\u4E8C\u53C2\u6570\u63A5\u6536 { signal, routing } \u63A5\u7EBF\u53D7\u63A7\u8DEF\u7531\uFF1B\u901A\u9053\u968F\u6302\u8F7D\u751F\u547D\u5468\u671F\u521B\u5EFA\uFF0C\u9500\u6BC1\u540E\u4E0D\u5F97\u590D\u7528\uFF08\u91CD\u6302\u4F1A\u5F97\u5230\u65B0\u901A\u9053\uFF09\u3002`,
+    { spec }
+  );
+}
+function routingNavigationError(spec, reason) {
+  return new FgError(
+    BridgeErrorCodes.ROUTING_NAVIGATION_INVALID,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684\u4E00\u6B21\u5BFC\u822A\u8BF7\u6C42\u88AB\u62D2\u7EDD\u3002
+\u539F\u56E0\uFF1A${reason}
+\u4FEE\u6CD5\uFF1A\u5B50\u5E94\u7528\u5BFC\u822A\u76EE\u6807\u5FC5\u987B\u4F4D\u4E8E\u81EA\u8EAB basePath \u524D\u7F00\u5185\uFF08\u8DE8\u524D\u7F00\u8BF7\u7528\u5BBF\u4E3B\u83DC\u5355/\u5BBF\u4E3B\u80FD\u529B\uFF09\uFF1Bgo \u53C2\u6570\u4E3A\u6709\u9650\u6574\u6570\u4E14 |delta| \u2264 50\u3002`,
+    { spec }
+  );
+}
+function routingSyncError(spec, reason, chain) {
+  return new FgError(
+    BridgeErrorCodes.ROUTING_SYNC_FAILED,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 URL \u540C\u6B65\u5728\u91CD\u5B9A\u5411\u94FE\u4E0A\u8D85\u51FA\u4E0A\u9650\uFF08${chain.length} \u6B21\uFF09\u3002
+\u539F\u56E0\uFF1A${reason}
+\u4FEE\u6CD5\uFF1A\u68C0\u67E5\u5B50\u5E94\u7528\u8DEF\u7531\u7684\u91CD\u5B9A\u5411\u89C4\u5219\u662F\u5426\u4E92\u76F8\u6210\u73AF\uFF1B\u540C\u6B65\u91CD\u5B9A\u5411\u4F7F\u7528 replace \u4E14\u4E0D\u5F97\u5BF9\u540C\u4E00\u4F4D\u7F6E\u91CD\u590D\u53D1\u8D77\u3002\u76EE\u6807\u94FE\uFF1A${chain.join(" \u2192 ")}\u3002`,
+    { spec, chain: [...chain] }
+  );
+}
 
 // src/bridge-core.ts
 function assertBridgeContract(spec, mod) {
@@ -1215,6 +1343,261 @@ function withBridgeTimeout(p, ms, spec) {
   });
 }
 
+// src/bridge-router-core.ts
+var MAX_REDIRECT_PER_REQUEST = 5;
+var MAX_GO_DELTA = 50;
+function normalizeBasePath(basePath, spec) {
+  const bad = (reason) => routingConfigError(spec, reason);
+  if (typeof basePath !== "string" || basePath === "") throw bad("basePath \u4E0D\u80FD\u4E3A\u7A7A\u3002");
+  if (basePath === "/") throw bad('basePath \u4E0D\u80FD\u662F\u6839 "/"\u2014\u2014\u6839\u8DEF\u5F84\u5C5E\u4E8E\u5BBF\u4E3B\u81EA\u8EAB\u9875\u9762\uFF0C\u8BF7\u4E3A\u540C\u6B65\u5B9E\u4F8B\u5206\u914D\u72EC\u7ACB\u524D\u7F00\u3002');
+  if (!basePath.startsWith("/")) throw bad(`basePath \u5FC5\u987B\u4EE5 "/" \u5F00\u5934\uFF1A\u5F53\u524D\u4E3A "${basePath}"\u3002`);
+  if (/[?#]/.test(basePath) || basePath.includes("://")) throw bad(`basePath \u4E0D\u80FD\u5305\u542B query/hash/\u534F\u8BAE\uFF1A\u5F53\u524D\u4E3A "${basePath}"\u3002`);
+  if (basePath.includes("*") || basePath.includes(":")) throw bad(`basePath \u4E0D\u63A5\u53D7\u901A\u914D\u7B26\u6216\u53C2\u6570\u6A21\u677F\uFF1A\u5F53\u524D\u4E3A "${basePath}"\u3002\u8BF7\u4F7F\u7528\u9759\u6001\u7EDD\u5BF9\u8DEF\u5F84\u3002`);
+  return basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+}
+function matchesBasePath(hostPathname, basePath) {
+  return hostPathname === basePath || hostPathname.startsWith(basePath + "/");
+}
+function overlapsBasePath(a, b) {
+  return a === b || a.startsWith(b + "/") || b.startsWith(a + "/");
+}
+function toChildLocation(host, basePath) {
+  const rest = host.pathname === basePath ? "/" : host.pathname.slice(basePath.length);
+  return { pathname: rest || "/", search: host.search, hash: host.hash };
+}
+function toHostLocation(child, basePath, spec) {
+  const childPath = child.pathname === "/" ? "" : child.pathname;
+  if (childPath !== "" && !childPath.startsWith("/")) {
+    throw routingNavigationError(spec, `\u5BFC\u822A\u76EE\u6807 pathname \u5FC5\u987B\u4EE5 "/" \u5F00\u5934\uFF1A\u5F53\u524D\u4E3A "${child.pathname}"\u3002`);
+  }
+  return { pathname: basePath + childPath, search: child.search, hash: child.hash };
+}
+function sameLocation(a, b) {
+  return a.pathname === b.pathname && a.search === b.search && a.hash === b.hash;
+}
+function assertChildTargetInScope(target, basePath, spec) {
+  if (target.pathname.includes("\0") || target.pathname.split("/").includes("..")) {
+    throw routingNavigationError(spec, `\u5BFC\u822A\u76EE\u6807\u8BD5\u56FE\u9003\u9038\u81EA\u8EAB\u524D\u7F00\uFF1Apathname "${target.pathname}"\u3002\u8DE8\u524D\u7F00\u5BFC\u822A\u8BF7\u901A\u8FC7\u5BBF\u4E3B\u83DC\u5355\u7B49\u5BBF\u4E3B\u80FD\u529B\u5B8C\u6210\u3002`);
+  }
+  const host = toHostLocation(target, basePath, spec);
+  if (!matchesBasePath(host.pathname, basePath)) {
+    throw routingNavigationError(spec, `\u5BFC\u822A\u76EE\u6807 ${host.pathname} \u4E0D\u5728\u524D\u7F00 ${basePath} \u4E0B\u3002`);
+  }
+}
+var activeRoutingPrefixes = /* @__PURE__ */ new Map();
+function acquireRoutingPrefix(basePath, spec) {
+  for (const [active] of activeRoutingPrefixes) {
+    if ((activeRoutingPrefixes.get(active) ?? 0) > 0 && overlapsBasePath(active, basePath)) {
+      throw routingConfigError(spec, `\u540C\u9875\u5DF2\u6709\u5360\u7528\u524D\u7F00 "${active}" \u7684\u540C\u6B65\u5B9E\u4F8B\uFF0C\u65B0\u5B9E\u4F8B "${spec}" \u7684 basePath "${basePath}" \u4E0E\u5176\u91CD\u53E0\u3002`);
+    }
+  }
+  activeRoutingPrefixes.set(basePath, (activeRoutingPrefixes.get(basePath) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    activeRoutingPrefixes.set(basePath, Math.max(0, (activeRoutingPrefixes.get(basePath) ?? 1) - 1));
+  };
+}
+function assertBridgeRoutingProtocol(spec, contract) {
+  const r = contract?.routing;
+  if (!r || r.protocol !== 1) {
+    throw routingProtocolError(
+      spec,
+      `\u8FDC\u7A0B\u5951\u7EA6\u672A\u58F0\u660E\u8DEF\u7531\u534F\u8BAE\uFF08\u671F\u671B routing: { protocol: 1 }\uFF0C\u5B9E\u9645 ${r === void 0 ? "\u7F3A\u5931" : `protocol=${String(r?.protocol)}`}\uFF09\u3002\u5F00\u542F URL \u540C\u6B65\u4E0D\u80FD\u9759\u9ED8\u9000\u56DE memory \u6A21\u5F0F\u3002`
+    );
+  }
+}
+var RoutingChannel = class {
+  id;
+  basePath;
+  spec;
+  host;
+  listeners = /* @__PURE__ */ new Set();
+  current;
+  lastConfirmed;
+  seq = 0;
+  inflight = null;
+  disposed = false;
+  active = true;
+  releasePrefix;
+  unsubHost;
+  /** 连续内部 replace 计数（有界重定向检测） */
+  redirectChain = [];
+  redirectTimer;
+  /** 诊断观测钩子（测试断言/诊断用） */
+  onEvent;
+  constructor(id, basePath, host, spec) {
+    this.id = id;
+    this.spec = spec;
+    this.basePath = normalizeBasePath(basePath, spec);
+    this.host = host;
+    this.current = toChildLocation(host.getLocation(), this.basePath);
+    this.lastConfirmed = { ...this.current };
+    this.releasePrefix = acquireRoutingPrefix(this.basePath, spec);
+    this.unsubHost = host.subscribe((loc) => this.handleHostLocation(loc));
+  }
+  emit(loc) {
+    this.current = { ...loc };
+    for (const l of [...this.listeners]) {
+      try {
+        l(this.current);
+      } catch (e) {
+        console.error("[fulgurjs] \u5B50\u5E94\u7528\u8DEF\u7531\u8BA2\u9605\u8005\u5F02\u5E38\uFF08\u5DF2\u9694\u79BB\uFF0C\u4E0D\u5F71\u54CD\u5BBF\u4E3B\uFF09\uFF1A", e);
+      }
+    }
+  }
+  handleHostLocation(hostLoc) {
+    if (this.disposed) return;
+    if (!matchesBasePath(hostLoc.pathname, this.basePath)) {
+      this.onEvent?.({ type: "prefix-miss", pathname: hostLoc.pathname });
+      return;
+    }
+    if (!this.active) {
+      this.onEvent?.({ type: "paused-host-loc" });
+      return;
+    }
+    const child = toChildLocation(hostLoc, this.basePath);
+    if (this.inflight && sameLocation(child, this.inflight.target)) {
+      const { seq, resolve } = this.inflight;
+      this.inflight = null;
+      this.lastConfirmed = child;
+      this.emit(child);
+      this.onEvent?.({ type: "request-confirmed", seq });
+      resolve({ status: "committed", location: { ...child } });
+      return;
+    }
+    if (this.inflight) {
+      const { seq, resolve } = this.inflight;
+      this.inflight = null;
+      this.lastConfirmed = child;
+      this.emit(child);
+      this.onEvent?.({ type: "request-superseded", seq });
+      resolve({ status: "cancelled", location: { ...child } });
+      return;
+    }
+    this.lastConfirmed = child;
+    this.emit(child);
+    this.onEvent?.({ type: "host-broadcast" });
+  }
+  getLocation() {
+    return { ...this.current };
+  }
+  subscribe(listener) {
+    if (this.disposed) {
+      throw routingProtocolError(this.spec, `\u901A\u9053 ${this.id} \u5DF2\u9500\u6BC1\uFF0C\u4E0D\u80FD\u518D\u8BA2\u9605\uFF08\u65E7\u5B9E\u4F8B\u7684\u8FDF\u5230\u8BA2\u9605\u5FC5\u987B\u5931\u6548\uFF1B\u91CD\u6302\u4F1A\u5F97\u5230\u65B0\u901A\u9053\uFF09\u3002`);
+    }
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  async navigate(target, action) {
+    if (this.disposed || !this.active) {
+      this.onEvent?.({ type: this.disposed ? "rejected-disposed" : "rejected-inactive" });
+      return { status: "cancelled", location: { ...this.lastConfirmed } };
+    }
+    assertChildTargetInScope(target, this.basePath, this.spec);
+    if (sameLocation(target, this.lastConfirmed)) {
+      this.onEvent?.({ type: "noop" });
+      return { status: "committed", location: { ...this.lastConfirmed } };
+    }
+    if (action === "replace") {
+      this.redirectChain.push(target.pathname + target.search + target.hash);
+    } else {
+      this.redirectChain = [];
+    }
+    if (this.redirectTimer) clearTimeout(this.redirectTimer);
+    this.redirectTimer = setTimeout(() => {
+      this.redirectChain = [];
+    }, 1e3);
+    if (this.redirectChain.length > MAX_REDIRECT_PER_REQUEST) {
+      const chain = [...this.redirectChain];
+      this.redirectChain = [];
+      throw routingSyncError(this.spec, "\u540C\u4E00\u901A\u9053\u7684\u8FDE\u7EED replace \u91CD\u5B9A\u5411\u8D85\u8FC7\u4E0A\u9650\uFF08\u7591\u4F3C\u5B50\u5E94\u7528\u8DEF\u7531\u4E92\u76F8\u6210\u73AF\uFF09\u3002", chain);
+    }
+    if (this.inflight) {
+      const prev = this.inflight;
+      await new Promise((resolve) => {
+        const timer = setInterval(() => {
+          if (this.inflight !== prev) {
+            clearInterval(timer);
+            resolve();
+          }
+        }, 0);
+      });
+      if (this.disposed || !this.active) {
+        return { status: "cancelled", location: { ...this.lastConfirmed } };
+      }
+      if (sameLocation(target, this.lastConfirmed)) {
+        return { status: "committed", location: { ...this.lastConfirmed } };
+      }
+    }
+    const seq = ++this.seq;
+    this.onEvent?.({ type: "request-start", seq, target: { ...target }, action });
+    return new Promise((resolve) => {
+      this.inflight = { seq, target: { ...target }, resolve };
+      this.host.navigate(toHostLocation(target, this.basePath, this.spec), action).then((result) => {
+        if (!this.inflight || this.inflight.seq !== seq) return;
+        if (this.disposed || !this.active) {
+          this.inflight = null;
+          resolve({ status: "cancelled", location: { ...this.lastConfirmed } });
+          return;
+        }
+        this.inflight = null;
+        if (result.status === "committed") {
+          const child = toChildLocation(result.location, this.basePath);
+          this.lastConfirmed = child;
+          this.emit(child);
+        } else {
+          this.emit({ ...this.lastConfirmed });
+        }
+        this.onEvent?.({ type: "host-verdict", seq, status: result.status });
+        resolve(
+          result.status === "committed" ? { status: "committed", location: { ...this.lastConfirmed } } : { status: "cancelled", location: { ...this.lastConfirmed } }
+        );
+      }).catch(() => {
+        if (this.inflight?.seq === seq) {
+          this.inflight = null;
+          this.onEvent?.({ type: "host-error", seq });
+          this.emit({ ...this.lastConfirmed });
+          resolve({ status: "cancelled", location: { ...this.lastConfirmed } });
+        }
+      });
+    });
+  }
+  /** 委托宿主历史（有限整数）；不创建第二条独立历史 */
+  go(delta) {
+    if (this.disposed || !this.active) return;
+    if (typeof delta !== "number" || !Number.isInteger(delta) || Math.abs(delta) > MAX_GO_DELTA) {
+      throw routingNavigationError(this.spec, `go \u53C2\u6570\u5FC5\u987B\u662F\u6709\u9650\u6574\u6570\uFF08|delta| \u2264 ${MAX_GO_DELTA}\uFF09\uFF1A\u5F53\u524D\u4E3A ${String(delta)}\u3002`);
+    }
+    this.host.go(delta);
+  }
+  /** KeepAlive deactivate：暂停广播与写入；通道与订阅保留（activate 后 resync） */
+  setActive(active) {
+    if (this.disposed) return;
+    this.active = active;
+    this.onEvent?.({ type: active ? "resumed" : "paused" });
+    if (active) this.handleHostLocation(this.host.getLocation());
+  }
+  /** 挂载生命周期结束：清理订阅/登记/在飞请求；此后一切写入失效 */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.redirectTimer) clearTimeout(this.redirectTimer);
+    this.unsubHost();
+    this.releasePrefix();
+    if (this.inflight) {
+      const { resolve } = this.inflight;
+      this.inflight = null;
+      resolve({ status: "cancelled", location: { ...this.lastConfirmed } });
+    }
+    this.listeners.clear();
+    this.onEvent?.({ type: "disposed" });
+  }
+};
+
 export {
   loadRemote,
   provideAppContext,
@@ -1225,5 +1608,7 @@ export {
   resolveBridgeContext,
   assertControlledSessionKey,
   assertBridgeOptions,
-  withBridgeTimeout
+  withBridgeTimeout,
+  assertBridgeRoutingProtocol,
+  RoutingChannel
 };

package/dist/{chunk-MMXKQN2H.js → chunk-GF6KOH67.js}

@@ -1,17 +1,24 @@
 import {
+  RoutingChannel,
   acquireBridgeSession,
   assertBridgeContract,
   assertBridgeOptions,
+  assertBridgeRoutingProtocol,
   assertControlledSessionKey,
   bridgeLifecycleError,
   provideAppContext,
   releaseBridgeSession,
   resolveBridgeContext,
   withBridgeTimeout
-} from "./chunk-TOT3P7AK.js";
+} from "./chunk-BTJGYDHT.js";
 
 // src/bridge-host-vue.ts
-import { defineComponent, h, onBeforeUnmount, onMounted, ref, shallowRef, toRaw, watch } from "vue";
+import { defineComponent, h, onActivated, onBeforeUnmount, onDeactivated, onMounted, ref, shallowRef, toRaw, watch } from "vue";
+var assertBridgeRoutingProtocolSpec = (spec, contract) => assertBridgeRoutingProtocol(spec, contract);
+function routingKey(routing) {
+  if (!routing) return void 0;
+  return routing.basePath + "|" + String(routing.navigation && typeof routing.navigation.navigate === "function");
+}
 var ERROR_STYLE = {
   padding: "16px",
   border: "1px solid #fde2e2",
@@ -89,7 +96,9 @@ function createVueBridgeAppWithLoader(loadRemote) {
       props: {
         appProps: { type: Object, required: false, default: void 0 },
         // 桥接控制参数：undefined（不启用受控会话）/ null（登出态）/ 非空字符串（登录代次）
-        sessionKey: { type: null, required: false, default: void 0 }
+        sessionKey: { type: null, required: false, default: void 0 },
+        // URL 同步控制通道（独立于 appProps/Context；省略 = 原 memory 模式）
+        routing: { type: Object, required: false, default: void 0 }
       },
       setup(props) {
         const status = ref("idle");
@@ -99,6 +108,8 @@ function createVueBridgeAppWithLoader(loadRemote) {
         let contract;
         let containerBlocked = false;
         let acquiredSession;
+        let channel;
+        let genAbort;
         const releaseAcquired = () => {
           if (acquiredSession !== void 0) {
             releaseBridgeSession(acquiredSession);
@@ -110,6 +121,10 @@ function createVueBridgeAppWithLoader(loadRemote) {
           generation++;
           const el = container.value;
           releaseAcquired();
+          genAbort?.abort();
+          genAbort = void 0;
+          channel?.dispose();
+          channel = void 0;
           if (contract && el) {
             const c = contract;
             contract = void 0;
@@ -151,7 +166,18 @@ function createVueBridgeAppWithLoader(loadRemote) {
             if (myGeneration !== generation) return;
             contract = assertBridgeContract(spec, mod);
             const appPropsSource = props.appProps ? toRaw(props.appProps) : void 0;
-            await contract.mount(el, { ...appPropsSource ?? {} });
+            genAbort = new AbortController();
+            let mountOptions = { signal: genAbort.signal };
+            if (props.routing) {
+              assertBridgeRoutingProtocolSpec(spec, contract);
+              const navigation = props.routing.navigation;
+              const latestLoc = navigation.getLocation();
+              if (myGeneration !== generation) return;
+              channel = new RoutingChannel(`bridge-vue:${spec}:${myGeneration}`, props.routing.basePath, navigation, spec);
+              mountOptions = { signal: genAbort.signal, routing: channel };
+              void latestLoc;
+            }
+            await contract.mount(el, { ...appPropsSource ?? {} }, mountOptions);
             if (myGeneration !== generation) return;
             status.value = "ready";
           } catch (e) {
@@ -176,6 +202,15 @@ function createVueBridgeAppWithLoader(loadRemote) {
         watch(() => props.sessionKey, () => {
           start();
         });
+        watch(() => routingKey(props.routing), (after, before) => {
+          if (after !== before) start();
+        });
+        onDeactivated(() => {
+          channel?.setActive(false);
+        });
+        onActivated(() => {
+          channel?.setActive(true);
+        });
         onBeforeUnmount(() => {
           invalidate();
         });