@fulgurjs/federation 5.3.3 → 5.4.0

package/dist/bridge-router-react.d.ts

@@ -0,0 +1,96 @@
+import { ReactElement } from 'react';
+import { RouteObject } from 'react-router-dom';
+
+/** 统一逻辑位置：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;
+}
+
+/**
+ * React Router 路由适配（/bridge/router/react 按需入口；URL 同步任务书 §3.1/§3.3）。
+ *
+ * 实际支持模式（原型实证，任务书 §1 结论 2）：
+ * - 宿主：data router（createBrowserRouter / createHashRouter + RouterProvider）。
+ *   router.navigate 被 blocker 拦截时静默返回 void（dist 源码核实）——取消用
+ *   「与 useBlocker 同一取消策略预判」：canNavigate(target) 返回 false 即 cancelled，
+ *   URL/历史零副作用；菜单/POP 等其他来源仍由树内 useBlocker 真实拦截。
+ * - 子应用：createMemoryRouter（RR 6.11+）受控路由——Link/useNavigate 全兼容，
+ *   通道广播与本地导航双向桥接，取消时乐观回滚。
+ * - declarative 模式（BrowserRouter）无 blocker/提交语义，不支持 URL 同步（文档声明）。
+ */
+
+/** 宿主取消策略（与树内 useBlocker 共用同一谓词，单一事实源） */
+type ReactBridgeCancelPolicy = (next: BridgeLocation) => boolean;
+/** data router 的最小结构面（避免耦合 RR 内部类型版本） */
+interface ReactDataRouterLike {
+    state: {
+        location: {
+            pathname: string;
+            search: string;
+            hash: string;
+        };
+    };
+    subscribe(cb: () => void): () => void;
+    navigate(to: string | number, opts?: {
+        replace?: boolean;
+    }): void | Promise<void>;
+}
+/**
+ * 宿主侧：把 RR data router 包装为宿主导航端口。
+ *
+ * ```tsx
+ * const router = createBrowserRouter(routes, { basename })
+ * const navigation = createReactBridgeNavigation(router, {
+ *   basename, // = createBrowserRouter 的 basename（含它；RR location.pathname 不剥 basename）
+ *   canNavigate: (next) => !next.pathname.startsWith('/approval/secret'), // 与 useBlocker 同一谓词
+ * })
+ * ```
+ */
+declare function createReactBridgeNavigation(router: ReactDataRouterLike, options?: {
+    canNavigate?: ReactBridgeCancelPolicy;
+    basename?: string;
+}): BridgeHostNavigation;
+interface ReactBridgeRouterConnection {
+    /** RouterProvider 元素：子应用在自己的 root 内渲染 */
+    element: ReactElement;
+    /** 清理本接线（通道订阅与本地监听；通道本身由宿主生命周期销毁） */
+    dispose(): void;
+}
+/**
+ * 子应用侧：把子应用自己的 routes 接到通道，返回 RouterProvider 元素。
+ *
+ * ```tsx
+ * export default defineBridgeApp((props, ctx) => {
+ *   const conn = createReactBridgeRouter(ctx.routing, routes)
+ *   const root = createRoot(el)
+ *   root.render(conn.element)
+ *   return { mount: () => {}, unmount: () => { conn.dispose(); root.unmount() } }
+ * }, { routing: true })
+ * ```
+ */
+declare function createReactBridgeRouter(routing: BridgeChildRoute, routes: RouteObject[]): ReactBridgeRouterConnection;
+
+export { type ReactBridgeCancelPolicy, type ReactBridgeRouterConnection, type ReactDataRouterLike, createReactBridgeNavigation, createReactBridgeRouter };

package/dist/bridge-router-react.js

@@ -0,0 +1,70 @@
+// src/bridge-router-react.tsx
+import { createElement } from "react";
+import { RouterProvider, createMemoryRouter } from "react-router-dom";
+function createReactBridgeNavigation(router, options = {}) {
+  const routerBase = options.basename && options.basename !== "/" ? options.basename.replace(/\/$/, "") : "";
+  const toLogic = () => {
+    const l = router.state.location;
+    const pathname = routerBase && l.pathname.startsWith(routerBase) ? l.pathname.slice(routerBase.length) || "/" : l.pathname;
+    return { pathname, search: l.search, hash: l.hash };
+  };
+  return {
+    getLocation: toLogic,
+    subscribe(listener) {
+      return router.subscribe(() => listener(toLogic()));
+    },
+    async navigate(target, action) {
+      if (options.canNavigate && !options.canNavigate(target)) {
+        return { status: "cancelled", location: toLogic() };
+      }
+      await router.navigate((routerBase && routerBase !== "/" ? routerBase : "") + target.pathname + target.search + target.hash, { replace: action === "replace" });
+      return { status: "committed", location: toLogic() };
+    },
+    go(delta) {
+      void router.navigate(delta);
+    }
+  };
+}
+function createReactBridgeRouter(routing, routes) {
+  const init = routing.getLocation();
+  const router = createMemoryRouter(routes, {
+    initialEntries: [init.pathname + init.search + init.hash]
+  });
+  let syncing = false;
+  let disposed = false;
+  const unsub = routing.subscribe((loc) => {
+    if (disposed) return;
+    const next = loc.pathname + loc.search + loc.hash;
+    const cur = router.state.location;
+    if (next !== cur.pathname + cur.search + cur.hash) void router.navigate(next, { replace: true });
+  });
+  const unwatch = router.subscribe(() => {
+    if (disposed || syncing) return;
+    const cur = router.state.location;
+    const chan = routing.getLocation();
+    if (cur.pathname + cur.search + cur.hash === chan.pathname + chan.search + chan.hash) return;
+    syncing = true;
+    void routing.navigate({ pathname: cur.pathname, search: cur.search, hash: cur.hash }, "push").then((result) => {
+      syncing = false;
+      if (result.status === "cancelled" && !disposed) {
+        const c = result.location;
+        const next = c.pathname + c.search + c.hash;
+        const cur2 = router.state.location;
+        if (next !== cur2.pathname + cur2.search + cur2.hash) void router.navigate(next, { replace: true });
+      }
+    });
+  });
+  return {
+    element: createElement(RouterProvider, { router }),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unwatch();
+      unsub();
+    }
+  };
+}
+export {
+  createReactBridgeNavigation,
+  createReactBridgeRouter
+};

package/dist/bridge-router-vue.d.ts

@@ -0,0 +1,75 @@
+import { Router } from 'vue-router';
+
+/** 统一逻辑位置：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;
+}
+
+/**
+ * Vue Router 4 路由适配（/bridge/router/vue 按需入口；URL 同步任务书 §3.1/§3.3）。
+ *
+ * 宿主侧：createVueBridgeNavigation(router) 把 Vue Router 实例包装为宿主导航端口——
+ * push/replace 落定 NavigationFailure | undefined，failure 即真实取消（守卫拒绝），
+ * 不以「函数返回」冒充提交成功。
+ *
+ * 子应用侧：connectVueBridgeRouter(routing, router) 把子应用自己的 memory router
+ * 接到通道上——RouterLink/router.push 等真实入口经 afterEach 桥为通道请求（宿主仲裁，
+ * 取消时回滚最后确认位置）；通道广播 replace 应用到本地 router。
+ * 初始位置已由通道就绪；`ready` 落定前 afterEach 不发起请求（原型实证：install 的
+ * 初始导航竞态，见任务书 §1 原型结论 1）。
+ *
+ * 本入口按需导入 vue-router（peerDependenciesMeta.optional）；默认 /bridge、/runtime、
+ * /react 不加载本模块。
+ */
+
+/** Vue Router base（createWebHistory/createWebHashHistory 的 base 参数）；逻辑路径 = 实际路径去 base */
+interface VueBridgeNavigationOptions {
+    routerBase?: string;
+}
+/** 宿主侧：把 Vue Router 实例包装为宿主导航端口（宿主 Router 是唯一历史写入方） */
+declare function createVueBridgeNavigation(router: Router, options?: VueBridgeNavigationOptions): BridgeHostNavigation;
+interface VueBridgeRouterConnection {
+    /** 初始位置就绪（含初始 push 与首次广播应用）；ready 前后的清理都必须可用 */
+    ready: Promise<void>;
+    /** 清理本接线（通道订阅与本地监听；通道本身由宿主生命周期销毁） */
+    dispose(): void;
+}
+/**
+ * 子应用侧：把子应用自己的 memory router 接到通道。
+ *
+ * ```ts
+ * export default defineBridgeApp((props, ctx) => {
+ *   const router = createRouter({ history: createMemoryHistory(), routes })
+ *   const conn = connectVueBridgeRouter(ctx.routing, router)
+ *   const app = createApp(App, props)
+ *   app.use(router)
+ *   return app
+ * }, { routing: true })
+ * ```
+ */
+declare function connectVueBridgeRouter(routing: BridgeChildRoute, router: Router): VueBridgeRouterConnection;
+
+export { type VueBridgeNavigationOptions, type VueBridgeRouterConnection, connectVueBridgeRouter, createVueBridgeNavigation };

package/dist/bridge-router-vue.js

@@ -0,0 +1,73 @@
+// src/bridge-router-vue.ts
+function createVueBridgeNavigation(router, options = {}) {
+  const routerBase = options.routerBase && options.routerBase !== "/" ? options.routerBase.replace(/\/$/, "") : "";
+  const toLogic = () => {
+    const raw = new URL(router.currentRoute.value.fullPath || "/", "http://f.invalid");
+    const pathname = routerBase && raw.pathname.startsWith(routerBase) ? raw.pathname.slice(routerBase.length) || "/" : raw.pathname;
+    return { pathname, search: raw.search, hash: raw.hash };
+  };
+  return {
+    getLocation: toLogic,
+    subscribe(listener) {
+      return router.afterEach(() => listener(toLogic()));
+    },
+    async navigate(target, action) {
+      const to = target.pathname + target.search + target.hash;
+      try {
+        const failure = action === "replace" ? await router.replace(to) : await router.push(to);
+        if (failure) return { status: "cancelled", location: toLogic() };
+        return { status: "committed", location: toLogic() };
+      } catch {
+        return { status: "cancelled", location: toLogic() };
+      }
+    },
+    go(delta) {
+      router.go(delta);
+    }
+  };
+}
+function connectVueBridgeRouter(routing, router) {
+  let syncing = false;
+  let disposed = false;
+  let started = false;
+  const unsub = routing.subscribe((loc) => {
+    if (disposed) return;
+    const next = loc.pathname + loc.search + loc.hash;
+    if (router.currentRoute.value.fullPath !== next) void router.replace(next);
+  });
+  const stopWatch = router.afterEach((to) => {
+    if (disposed || syncing || !started) return;
+    const chan = routing.getLocation();
+    const toFull = to.fullPath;
+    if (toFull === chan.pathname + chan.search + chan.hash) return;
+    const raw = new URL(toFull, "http://f.invalid");
+    syncing = true;
+    void routing.navigate({ pathname: raw.pathname, search: raw.search, hash: raw.hash }, "push").then((result) => {
+      syncing = false;
+      if (result.status === "cancelled" && !disposed) {
+        const c = result.location;
+        const cur = c.pathname + c.search + c.hash;
+        if (router.currentRoute.value.fullPath !== cur) void router.replace(cur);
+      }
+    });
+  });
+  const init = routing.getLocation();
+  const ready = router.push(init.pathname + init.search + init.hash).then(() => {
+    started = true;
+  }).catch(() => {
+    started = true;
+  });
+  return {
+    ready,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopWatch();
+      unsub();
+    }
+  };
+}
+export {
+  connectVueBridgeRouter,
+  createVueBridgeNavigation
+};

package/dist/bridge-vue.d.ts

@@ -1,6 +1,6 @@
 import * as vue from 'vue';
-import { V as VueBridgeAppOptions } from './bridge-host-vue-BAxDKqGH.js';
-export { A as AppContext, B as BridgeApp } from './bridge-core-6uLJiMVa.js';
+import { V as VueBridgeAppOptions } from './bridge-host-vue-BuCGlLdS.js';
+export { A as AppContext, a as BridgeApp } from './bridge-core-BOWvVUxO.js';
 
 /** Vue 宿主桥接工厂：返回 `{ appProps: P; sessionKey?: string | null }` 形态的包装组件 */
 declare const createVueBridgeApp: <P = Record<string, unknown>>(spec: string, options?: VueBridgeAppOptions) => vue.Component;

package/dist/bridge.d.ts

@@ -1,9 +1,10 @@
 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';
+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';
 import * as vue from 'vue';
-import { V as VueBridgeAppOptions } from './bridge-host-vue-BAxDKqGH.js';
-export { A as AppContext, B as BridgeApp } from './bridge-core-6uLJiMVa.js';
+import { V as VueBridgeAppOptions } from './bridge-host-vue-BuCGlLdS.js';
 
 /** Vue 宿主桥接工厂：返回 `{ appProps: P; sessionKey?: string | null }` 形态的包装组件 */
 declare const createVueBridgeApp: <P = Record<string, unknown>>(spec: string, options?: VueBridgeAppOptions) => vue.Component;
@@ -11,6 +12,7 @@ declare const createVueBridgeApp: <P = Record<string, unknown>>(spec: string, op
 declare const createReactBridgeApp: <P = Record<string, unknown>>(spec: string, options?: ReactBridgeAppOptions) => react.ComponentType<{
     appProps?: P;
     sessionKey?: string | null;
+    routing?: BridgeHostRouting;
 }>;
 
 export { ReactBridgeAppOptions, VueBridgeAppOptions, createReactBridgeApp, createVueBridgeApp };

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

@@ -1138,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;
@@ -1195,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) {
@@ -1299,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,
@@ -1309,5 +1608,7 @@ export {
   resolveBridgeContext,
   assertControlledSessionKey,
   assertBridgeOptions,
-  withBridgeTimeout
+  withBridgeTimeout,
+  assertBridgeRoutingProtocol,
+  RoutingChannel
 };