@fulgurjs/federation 5.3.3 → 5.4.0

package/dist/bridge-host-vue.cjs

@@ -77,7 +77,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;
@@ -134,6 +142,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) {
@@ -238,7 +282,267 @@ 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" });
+  }
+};
+
 // src/bridge-host-vue.ts
+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",
@@ -316,7 +620,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 = (0, import_vue.ref)("idle");
@@ -326,6 +632,8 @@ function createVueBridgeAppWithLoader(loadRemote) {
         let contract;
         let containerBlocked = false;
         let acquiredSession;
+        let channel;
+        let genAbort;
         const releaseAcquired = () => {
           if (acquiredSession !== void 0) {
             releaseBridgeSession(acquiredSession);
@@ -337,6 +645,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;
@@ -378,7 +690,18 @@ function createVueBridgeAppWithLoader(loadRemote) {
             if (myGeneration !== generation) return;
             contract = assertBridgeContract(spec, mod);
             const appPropsSource = props.appProps ? (0, import_vue.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) {
@@ -403,6 +726,15 @@ function createVueBridgeAppWithLoader(loadRemote) {
         (0, import_vue.watch)(() => props.sessionKey, () => {
           start();
         });
+        (0, import_vue.watch)(() => routingKey(props.routing), (after, before) => {
+          if (after !== before) start();
+        });
+        (0, import_vue.onDeactivated)(() => {
+          channel?.setActive(false);
+        });
+        (0, import_vue.onActivated)(() => {
+          channel?.setActive(true);
+        });
         (0, import_vue.onBeforeUnmount)(() => {
           invalidate();
         });

package/dist/bridge-host-vue.js

@@ -1,3 +1,7 @@
+import {
+  RoutingChannel,
+  assertBridgeRoutingProtocol
+} from "./chunk-WOTR2FUQ.js";
 import {
   acquireBridgeSession,
   assertBridgeContract,
@@ -6,17 +10,22 @@ import {
   releaseBridgeSession,
   resolveBridgeContext,
   withBridgeTimeout
-} from "./chunk-LE2G23E7.js";
+} from "./chunk-PRUYHYX2.js";
 import {
   bridgeLifecycleError
-} from "./chunk-DH2QMM4Y.js";
+} from "./chunk-JQF7KYZF.js";
 import {
   provideAppContext
 } from "./chunk-TSYLDY6H.js";
 import "./chunk-OF2JCXTZ.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",
@@ -94,7 +103,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");
@@ -104,6 +115,8 @@ function createVueBridgeAppWithLoader(loadRemote) {
         let contract;
         let containerBlocked = false;
         let acquiredSession;
+        let channel;
+        let genAbort;
         const releaseAcquired = () => {
           if (acquiredSession !== void 0) {
             releaseBridgeSession(acquiredSession);
@@ -115,6 +128,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;
@@ -156,7 +173,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) {
@@ -181,6 +209,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();
         });

package/dist/bridge-react.d.ts

@@ -1,12 +1,14 @@
 import * as react from 'react';
-import { R as ReactBridgeAppOptions } from './bridge-host-react-C55RmGll.js';
-export { B as BridgeErrorFallback } from './bridge-host-react-C55RmGll.js';
-export { A as AppContext, B as BridgeApp } from './bridge-core-6uLJiMVa.js';
+import { B as BridgeHostRouting } from './bridge-core-BOWvVUxO.js';
+export { A as AppContext, a as BridgeApp } from './bridge-core-BOWvVUxO.js';
+import { R as ReactBridgeAppOptions } from './bridge-host-react-CMVd-ym0.js';
+export { B as BridgeErrorFallback } from './bridge-host-react-CMVd-ym0.js';
 
 /** React 宿主桥接工厂：返回 `ComponentType<{ appProps: P; sessionKey?: string | null }>` */
 declare const createReactBridgeApp: <P = Record<string, unknown>>(spec: string, options?: ReactBridgeAppOptions) => react.ComponentType<{
     appProps?: P;
     sessionKey?: string | null;
+    routing?: BridgeHostRouting;
 }>;
 
 export { ReactBridgeAppOptions, createReactBridgeApp };

package/dist/bridge-router-core-BxBx-reP.d.cts

@@ -0,0 +1,44 @@
+/** 统一逻辑位置：pathname 以 / 开头；search 空串或 ? 开头；hash 空串或 # 开头 */
+interface BridgeLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+type BridgeNavigationResult = {
+    status: 'committed';
+    location: BridgeLocation;
+} | {
+    status: 'cancelled';
+    location: BridgeLocation;
+};
+/** 宿主导航端口（宿主适配器把 Router 包装成本接口；逻辑路径不含部署 base） */
+interface BridgeHostNavigation {
+    getLocation(): BridgeLocation;
+    subscribe(listener: (location: BridgeLocation) => void): () => void;
+    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    go(delta: number): void;
+}
+/** 子应用路由通道（桥接宿主按挂载代次创建，随 mount 第三参数交给子应用） */
+interface BridgeChildRoute {
+    getLocation(): BridgeLocation;
+    subscribe(listener: (location: BridgeLocation) => void): () => void;
+    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    go(delta: number): void;
+}
+/** 挂载控制参数（mount 第三参数；不混入业务 props） */
+interface BridgeMountOptions {
+    signal?: AbortSignal;
+    routing?: BridgeChildRoute;
+}
+/** 子应用路由协议声明（defineBridgeApp(工厂, { routing: true }) 时写入） */
+interface BridgeRoutingProtocol {
+    protocol: 1;
+}
+/** 宿主组件 routing prop（独立控制通道，不进 appProps/Context） */
+interface BridgeHostRouting {
+    /** 宿主路由视角的静态绝对路径，如 "/approval"；同页各同步实例不得相同或重叠 */
+    basePath: string;
+    navigation: BridgeHostNavigation;
+}
+
+export type { BridgeChildRoute as B, BridgeMountOptions as a, BridgeRoutingProtocol as b, BridgeHostRouting as c };

package/dist/bridge-router-core-BxBx-reP.d.ts

@@ -0,0 +1,44 @@
+/** 统一逻辑位置：pathname 以 / 开头；search 空串或 ? 开头；hash 空串或 # 开头 */
+interface BridgeLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+type BridgeNavigationResult = {
+    status: 'committed';
+    location: BridgeLocation;
+} | {
+    status: 'cancelled';
+    location: BridgeLocation;
+};
+/** 宿主导航端口（宿主适配器把 Router 包装成本接口；逻辑路径不含部署 base） */
+interface BridgeHostNavigation {
+    getLocation(): BridgeLocation;
+    subscribe(listener: (location: BridgeLocation) => void): () => void;
+    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    go(delta: number): void;
+}
+/** 子应用路由通道（桥接宿主按挂载代次创建，随 mount 第三参数交给子应用） */
+interface BridgeChildRoute {
+    getLocation(): BridgeLocation;
+    subscribe(listener: (location: BridgeLocation) => void): () => void;
+    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    go(delta: number): void;
+}
+/** 挂载控制参数（mount 第三参数；不混入业务 props） */
+interface BridgeMountOptions {
+    signal?: AbortSignal;
+    routing?: BridgeChildRoute;
+}
+/** 子应用路由协议声明（defineBridgeApp(工厂, { routing: true }) 时写入） */
+interface BridgeRoutingProtocol {
+    protocol: 1;
+}
+/** 宿主组件 routing prop（独立控制通道，不进 appProps/Context） */
+interface BridgeHostRouting {
+    /** 宿主路由视角的静态绝对路径，如 "/approval"；同页各同步实例不得相同或重叠 */
+    basePath: string;
+    navigation: BridgeHostNavigation;
+}
+
+export type { BridgeChildRoute as B, BridgeMountOptions as a, BridgeRoutingProtocol as b, BridgeHostRouting as c };