@fulgurjs/federation 5.4.0 → 5.4.1

package/dist/bridge-host-vue.cjs

@@ -169,13 +169,14 @@ function routingNavigationError(spec, reason) {
     { spec }
   );
 }
-function routingSyncError(spec, reason, chain) {
+function routingSyncError(spec, reason, chain, cause) {
   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
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 URL \u540C\u6B65\u5931\u8D25\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] }
+\u4FEE\u6CD5\uFF1A\u68C0\u67E5\u8DEF\u7531\u5B88\u536B\u3001\u52A0\u8F7D\u5668\u4E0E\u5BFC\u822A\u5F02\u5E38\uFF1B\u91CD\u5B9A\u5411\u94FE\u4E0D\u5E94\u6210\u73AF\u3002\u76EE\u6807\u94FE\uFF1A${chain.join(" \u2192 ")}\u3002`,
+    { spec, chain: [...chain] },
+    { cause }
   );
 }
 
@@ -288,10 +289,11 @@ 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 (/^\/+$/u.test(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`);
+  if (/\\|\/\/|%(?:2e|2f|5c)/i.test(basePath) || basePath.split("/").some((part) => part === "." || part === "..")) throw bad("basePath \u4E0D\u80FD\u5305\u542B\u7A7A\u8DEF\u5F84\u6BB5\u3001\u8F6C\u4E49\u5206\u9694\u7B26\u6216\u76F8\u5BF9\u8DEF\u5F84\u6BB5\u3002");
   return basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
 }
 function matchesBasePath(hostPathname, basePath) {
@@ -315,7 +317,8 @@ 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("..")) {
+  if (!target || typeof target.pathname !== "string" || typeof target.search !== "string" || typeof target.hash !== "string" || target.search !== "" && !target.search.startsWith("?") || target.hash !== "" && !target.hash.startsWith("#")) throw routingNavigationError(spec, "\u5BFC\u822A\u76EE\u6807\u5FC5\u987B\u63D0\u4F9B pathname\u3001search\u3001hash \u4E09\u6BB5\uFF0Csearch/hash \u5E94\u4E3A\u7A7A\u6216\u4EE5 ?/# \u5F00\u5934\u3002");
+  if (/[\x00-\x20\\?#]|%(?:2e|2f|5c)/i.test(target.pathname) || target.pathname.includes("//") || target.pathname.split("/").some((part) => part === "." || part === "..")) {
     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);
@@ -357,6 +360,8 @@ var RoutingChannel = class {
   lastConfirmed;
   seq = 0;
   inflight = null;
+  queue;
+  generation = 0;
   disposed = false;
   active = true;
   releasePrefix;
@@ -371,7 +376,8 @@ var RoutingChannel = class {
     this.spec = spec;
     this.basePath = normalizeBasePath(basePath, spec);
     this.host = host;
-    this.current = toChildLocation(host.getLocation(), this.basePath);
+    const initial = host.getLocation();
+    this.current = matchesBasePath(initial.pathname, this.basePath) ? toChildLocation(initial, this.basePath) : { pathname: "/", search: "", hash: "" };
     this.lastConfirmed = { ...this.current };
     this.releasePrefix = acquireRoutingPrefix(this.basePath, spec);
     this.unsubHost = host.subscribe((loc) => this.handleHostLocation(loc));
@@ -389,6 +395,7 @@ var RoutingChannel = class {
   handleHostLocation(hostLoc) {
     if (this.disposed) return;
     if (!matchesBasePath(hostLoc.pathname, this.basePath)) {
+      this.cancelPending();
       this.onEvent?.({ type: "prefix-miss", pathname: hostLoc.pathname });
       return;
     }
@@ -398,23 +405,21 @@ var RoutingChannel = class {
     }
     const child = toChildLocation(hostLoc, this.basePath);
     if (this.inflight && sameLocation(child, this.inflight.target)) {
-      const { seq, resolve } = this.inflight;
-      this.inflight = null;
+      const { seq } = this.inflight;
       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;
+      const seq = this.inflight.seq;
       this.lastConfirmed = child;
+      this.cancelPending();
       this.emit(child);
       this.onEvent?.({ type: "request-superseded", seq });
-      resolve({ status: "cancelled", location: { ...child } });
       return;
     }
+    if (!sameLocation(child, this.lastConfirmed)) this.generation++;
     this.lastConfirmed = child;
     this.emit(child);
     this.onEvent?.({ type: "host-broadcast" });
@@ -431,8 +436,31 @@ var RoutingChannel = class {
       this.listeners.delete(listener);
     };
   }
-  async navigate(target, action) {
-    if (this.disposed || !this.active) {
+  cancelPending() {
+    this.generation++;
+    const pending = this.inflight;
+    this.inflight = null;
+    if (pending) {
+      pending.abort.abort();
+      pending.resolve({ status: "cancelled", location: { ...this.lastConfirmed } });
+    }
+  }
+  navigate(target, action) {
+    const generation = this.generation;
+    const snapshot = { ...target };
+    const run = () => generation !== this.generation ? Promise.resolve({ status: "cancelled", location: { ...this.lastConfirmed } }) : this.performNavigation(snapshot, action);
+    const task = this.queue ? this.queue.then(run) : run();
+    const tail = task.then(() => {
+    }, () => {
+    });
+    this.queue = tail;
+    void tail.then(() => {
+      if (this.queue === tail) this.queue = void 0;
+    });
+    return task;
+  }
+  async performNavigation(target, action) {
+    if (this.disposed || !this.active || !matchesBasePath(this.host.getLocation().pathname, this.basePath)) {
       this.onEvent?.({ type: this.disposed ? "rejected-disposed" : "rejected-inactive" });
       return { status: "cancelled", location: { ...this.lastConfirmed } };
     }
@@ -455,28 +483,12 @@ var RoutingChannel = class {
       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) => {
+    return new Promise((resolve, reject) => {
+      const abort = new AbortController();
+      this.inflight = { seq, target: { ...target }, resolve, abort };
+      Promise.resolve().then(() => abort.signal.aborted ? { status: "cancelled", location: this.host.getLocation() } : this.host.navigate(toHostLocation(target, this.basePath, this.spec), action, { signal: abort.signal })).then((result) => {
         if (!this.inflight || this.inflight.seq !== seq) return;
         if (this.disposed || !this.active) {
           this.inflight = null;
@@ -484,7 +496,7 @@ var RoutingChannel = class {
           return;
         }
         this.inflight = null;
-        if (result.status === "committed") {
+        if (result.status === "committed" && matchesBasePath(result.location.pathname, this.basePath)) {
           const child = toChildLocation(result.location, this.basePath);
           this.lastConfirmed = child;
           this.emit(child);
@@ -493,21 +505,21 @@ var RoutingChannel = class {
         }
         this.onEvent?.({ type: "host-verdict", seq, status: result.status });
         resolve(
-          result.status === "committed" ? { status: "committed", location: { ...this.lastConfirmed } } : { status: "cancelled", location: { ...this.lastConfirmed } }
+          result.status === "committed" && matchesBasePath(result.location.pathname, this.basePath) ? { status: "committed", location: { ...this.lastConfirmed } } : { status: "cancelled", location: { ...this.lastConfirmed } }
         );
-      }).catch(() => {
+      }).catch((cause) => {
         if (this.inflight?.seq === seq) {
           this.inflight = null;
           this.onEvent?.({ type: "host-error", seq });
           this.emit({ ...this.lastConfirmed });
-          resolve({ status: "cancelled", location: { ...this.lastConfirmed } });
+          reject(routingSyncError(this.spec, `\u5BBF\u4E3B\u5BFC\u822A\u6267\u884C\u5931\u8D25\uFF1A${cause instanceof Error ? cause.message : String(cause)}`, [], cause));
         }
       });
     });
   }
   /** 委托宿主历史（有限整数）；不创建第二条独立历史 */
   go(delta) {
-    if (this.disposed || !this.active) return;
+    if (this.disposed || !this.active || !matchesBasePath(this.host.getLocation().pathname, this.basePath)) 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`);
     }
@@ -516,6 +528,7 @@ var RoutingChannel = class {
   /** KeepAlive deactivate：暂停广播与写入；通道与订阅保留（activate 后 resync） */
   setActive(active) {
     if (this.disposed) return;
+    if (!active) this.cancelPending();
     this.active = active;
     this.onEvent?.({ type: active ? "resumed" : "paused" });
     if (active) this.handleHostLocation(this.host.getLocation());
@@ -527,11 +540,7 @@ var RoutingChannel = class {
     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.cancelPending();
     this.listeners.clear();
     this.onEvent?.({ type: "disposed" });
   }

package/dist/bridge-host-vue.js

@@ -1,7 +1,7 @@
 import {
   RoutingChannel,
   assertBridgeRoutingProtocol
-} from "./chunk-WOTR2FUQ.js";
+} from "./chunk-7CQOVLSI.js";
 import {
   acquireBridgeSession,
   assertBridgeContract,
@@ -10,10 +10,10 @@ import {
   releaseBridgeSession,
   resolveBridgeContext,
   withBridgeTimeout
-} from "./chunk-PRUYHYX2.js";
+} from "./chunk-RXXBTPAY.js";
 import {
   bridgeLifecycleError
-} from "./chunk-JQF7KYZF.js";
+} from "./chunk-HZGQOW35.js";
 import {
   provideAppContext
 } from "./chunk-TSYLDY6H.js";

package/dist/bridge-react.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
-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 { B as BridgeHostRouting } from './bridge-core-ejlY9ddN.js';
+export { A as AppContext, a as BridgeApp } from './bridge-core-ejlY9ddN.js';
+import { R as ReactBridgeAppOptions } from './bridge-host-react-Bua1TCVh.js';
+export { B as BridgeErrorFallback } from './bridge-host-react-Bua1TCVh.js';
 
 /** React 宿主桥接工厂：返回 `ComponentType<{ appProps: P; sessionKey?: string | null }>` */
 declare const createReactBridgeApp: <P = Record<string, unknown>>(spec: string, options?: ReactBridgeAppOptions) => react.ComponentType<{

package/dist/{bridge-router-core-BxBx-reP.d.ts → bridge-router-core-BRZQYDPm.d.cts}

@@ -15,7 +15,9 @@ type BridgeNavigationResult = {
 interface BridgeHostNavigation {
     getLocation(): BridgeLocation;
     subscribe(listener: (location: BridgeLocation) => void): () => void;
-    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    navigate(target: BridgeLocation, action: 'push' | 'replace', options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeNavigationResult>;
     go(delta: number): void;
 }
 /** 子应用路由通道（桥接宿主按挂载代次创建，随 mount 第三参数交给子应用） */

package/dist/{bridge-router-core-BxBx-reP.d.cts → bridge-router-core-BRZQYDPm.d.ts}

@@ -15,7 +15,9 @@ type BridgeNavigationResult = {
 interface BridgeHostNavigation {
     getLocation(): BridgeLocation;
     subscribe(listener: (location: BridgeLocation) => void): () => void;
-    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    navigate(target: BridgeLocation, action: 'push' | 'replace', options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeNavigationResult>;
     go(delta: number): void;
 }
 /** 子应用路由通道（桥接宿主按挂载代次创建，随 mount 第三参数交给子应用） */

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

@@ -18,7 +18,9 @@ type BridgeNavigationResult = {
 interface BridgeHostNavigation {
     getLocation(): BridgeLocation;
     subscribe(listener: (location: BridgeLocation) => void): () => void;
-    navigate(target: BridgeLocation, action: 'push' | 'replace'): Promise<BridgeNavigationResult>;
+    navigate(target: BridgeLocation, action: 'push' | 'replace', options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeNavigationResult>;
     go(delta: number): void;
 }
 /** 子应用路由通道（桥接宿主按挂载代次创建，随 mount 第三参数交给子应用） */
@@ -29,68 +31,43 @@ interface BridgeChildRoute {
     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 同步（文档声明）。
- */
+/** React Router data router 的宿主端口与子应用 memory router 接线（按需入口）。 */
 
-/** 宿主取消策略（与树内 useBlocker 共用同一谓词，单一事实源） */
 type ReactBridgeCancelPolicy = (next: BridgeLocation) => boolean;
-/** data router 的最小结构面（避免耦合 RR 内部类型版本） */
 interface ReactDataRouterLike {
     state: {
         location: {
             pathname: string;
             search: string;
             hash: string;
+            key?: string;
+        };
+        navigation?: {
+            state: string;
+            location?: BridgeLocation;
         };
+        blockers?: ReadonlyMap<string, {
+            state: string;
+            reset?: () => void;
+        }>;
     };
     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 同一谓词
- * })
- * ```
- */
+/** canNavigate 是可选预判；最终结果同时核对真实 blocker 与已提交位置。 */
 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;
+/** 返回 RouterProvider 元素，直接作为 defineBridgeApp 工厂的 ReactElement 返回值。 */
+declare function createReactBridgeRouter(routing: BridgeChildRoute, routes: RouteObject[], options?: {
+    signal?: AbortSignal;
+}): ReactBridgeRouterConnection;
 
 export { type ReactBridgeCancelPolicy, type ReactBridgeRouterConnection, type ReactDataRouterLike, createReactBridgeNavigation, createReactBridgeRouter };

package/dist/bridge-router-react.js

@@ -1,68 +1,245 @@
 // src/bridge-router-react.tsx
 import { createElement } from "react";
 import { RouterProvider, createMemoryRouter } from "react-router-dom";
+
+// src/runtime/errors.ts
+var FgError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details, options) {
+    super(`[fulgurjs:${code}] ${message}`, options);
+    this.name = "FgError";
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/bridge-errors.ts
+var BridgeErrorCodes = {
+  /** 桥接契约非法（./bridge 默认导出缺 mount/unmount 或不是函数） */
+  BRIDGE_INVALID_CONTRACT: "MFU-015",
+  /** 桥接准备或生命周期失败（details.phase = getContext | mount | unmount） */
+  BRIDGE_LIFECYCLE_FAILED: "MFU-016",
+  /** 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾） */
+  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 routingSyncError(spec, reason, chain, cause) {
+  return new FgError(
+    BridgeErrorCodes.ROUTING_SYNC_FAILED,
+    `\u73B0\u8C61\uFF1A\u6865\u63A5\u5E94\u7528 "${spec}" \u7684 URL \u540C\u6B65\u5931\u8D25\u3002
+\u539F\u56E0\uFF1A${reason}
+\u4FEE\u6CD5\uFF1A\u68C0\u67E5\u8DEF\u7531\u5B88\u536B\u3001\u52A0\u8F7D\u5668\u4E0E\u5BFC\u822A\u5F02\u5E38\uFF1B\u91CD\u5B9A\u5411\u94FE\u4E0D\u5E94\u6210\u73AF\u3002\u76EE\u6807\u94FE\uFF1A${chain.join(" \u2192 ")}\u3002`,
+    { spec, chain: [...chain] },
+    { cause }
+  );
+}
+
+// src/bridge-router-core.ts
+function sameLocation(a, b) {
+  return a.pathname === b.pathname && a.search === b.search && a.hash === b.hash;
+}
+
+// src/bridge-router-sync.ts
+function connectChildNavigation(routing, apply, onError) {
+  let disposed = false;
+  let generation = 0;
+  let tail = Promise.resolve();
+  let confirmed = routing.getLocation();
+  let pending;
+  const restore = () => apply(routing.getLocation());
+  const unsub = routing.subscribe((location) => {
+    if (disposed) return;
+    const changed = !sameLocation(location, confirmed);
+    confirmed = location;
+    if (pending && sameLocation(location, pending)) return;
+    if (changed) generation++;
+    tail = tail.then(() => disposed ? void 0 : restore()).catch(onError);
+  });
+  return {
+    enqueue(prepare, action) {
+      const version = generation;
+      const cancelled = () => ({ status: "cancelled", location: routing.getLocation() });
+      const task = tail.then(async () => {
+        if (disposed || version !== generation) return cancelled();
+        try {
+          const target = await prepare();
+          if (disposed) return cancelled();
+          if (version !== generation) {
+            await restore();
+            return cancelled();
+          }
+          if (!target) return cancelled();
+          pending = target;
+          const result = await routing.navigate(target, action);
+          if (!disposed) await restore();
+          return result;
+        } catch (cause) {
+          if (!disposed) {
+            try {
+              await restore();
+            } catch (restoreError) {
+              onError(restoreError);
+            }
+          }
+          throw routingSyncError("child-router", `\u5B50\u5E94\u7528\u8DEF\u7531\u51C6\u5907\u6216\u540C\u6B65\u5931\u8D25\uFF1A${cause instanceof Error ? cause.message : String(cause)}`, [], cause);
+        } finally {
+          pending = void 0;
+        }
+      });
+      tail = task.then(() => {
+      }, () => {
+      });
+      return task;
+    },
+    dispose() {
+      disposed = true;
+      generation++;
+      unsub();
+    }
+  };
+}
+
+// src/bridge-router-react.tsx
 function createReactBridgeNavigation(router, options = {}) {
-  const routerBase = options.basename && options.basename !== "/" ? options.basename.replace(/\/$/, "") : "";
+  const base = 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;
+    const pathname = base && (l.pathname === base || l.pathname.startsWith(base + "/")) ? l.pathname.slice(base.length) || "/" : l.pathname;
     return { pathname, search: l.search, hash: l.hash };
   };
   return {
     getLocation: toLogic,
     subscribe(listener) {
-      return router.subscribe(() => listener(toLogic()));
+      let previous = toLogic();
+      return router.subscribe(() => {
+        const next = toLogic();
+        if (!sameLocation(previous, next)) {
+          previous = next;
+          listener(next);
+        }
+      });
     },
-    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() };
+    async navigate(target, action, context) {
+      if (context?.signal?.aborted || options.canNavigate && !options.canNavigate(target)) return { status: "cancelled", location: toLogic() };
+      const initial = router.state.location;
+      return new Promise((resolve, reject) => {
+        let finished = false;
+        let returned = false;
+        let blocked = false;
+        let unwatch = () => {
+        };
+        const finish = (status) => {
+          if (finished) return;
+          finished = true;
+          unwatch();
+          context?.signal?.removeEventListener("abort", abort);
+          resolve({ status, location: toLogic() });
+        };
+        const abort = () => {
+          finish("cancelled");
+          for (const blocker of router.state.blockers?.values() ?? []) if (blocker.state === "blocked") blocker.reset?.();
+          const loading = router.state.navigation;
+          if (loading && loading.state !== "idle" && loading.location?.pathname === base + target.pathname) {
+            const current = toLogic();
+            void Promise.resolve().then(() => {
+              const latest = router.state.navigation;
+              if (!latest || latest.state === "idle" || latest.location?.pathname !== base + target.pathname) return;
+              return router.navigate(current.pathname + current.search + current.hash, { replace: true });
+            }).catch((error) => console.error("[fulgurjs] \u53D6\u6D88\u5BBF\u4E3B\u5F85\u63D0\u4EA4\u5BFC\u822A\u5931\u8D25\uFF1A", error));
+          }
+        };
+        const check = () => {
+          if (finished) return;
+          if (context?.signal?.aborted) {
+            abort();
+            return;
+          }
+          const blockers = [...router.state.blockers?.values() ?? []];
+          if (blockers.some((b) => b.state === "blocked" || b.state === "proceeding")) {
+            blocked = true;
+            return;
+          }
+          if (router.state.navigation && router.state.navigation.state !== "idle") return;
+          const actual = router.state.location;
+          const committed = actual.key !== initial.key || !sameLocation(actual, initial);
+          if (committed) finish("committed");
+          else if (returned || blocked) finish("cancelled");
+        };
+        unwatch = router.subscribe(check);
+        context?.signal?.addEventListener("abort", abort, { once: true });
+        Promise.resolve().then(() => {
+          if (finished || context?.signal?.aborted) return;
+          return router.navigate(target.pathname + target.search + target.hash, { replace: action === "replace" });
+        }).then(() => {
+          returned = true;
+          check();
+        }, (error) => {
+          if (finished) return;
+          finished = true;
+          unwatch();
+          context?.signal?.removeEventListener("abort", abort);
+          reject(error);
+        });
+      });
     },
     go(delta) {
-      void router.navigate(delta);
+      void Promise.resolve().then(() => router.navigate(delta)).catch((error) => console.error("[fulgurjs] \u5BBF\u4E3B\u5386\u53F2\u5BFC\u822A\u5931\u8D25\uFF1A", error));
     }
   };
 }
-function createReactBridgeRouter(routing, routes) {
+function createReactBridgeRouter(routing, routes, options = {}) {
   const init = routing.getLocation();
-  const router = createMemoryRouter(routes, {
-    initialEntries: [init.pathname + init.search + init.hash]
-  });
-  let syncing = false;
+  const router = createMemoryRouter(routes, { initialEntries: [init.pathname + init.search + init.hash] });
+  const navigate = router.navigate.bind(router);
   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 sync = connectChildNavigation(routing, async (loc) => {
     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 });
-      }
+    if (!sameLocation(cur, loc)) await navigate(loc.pathname + loc.search + loc.hash, { replace: true });
+  }, (error) => console.error("[fulgurjs] \u5B50\u5E94\u7528 React \u8DEF\u7531\u540C\u6B65\u5931\u8D25\uFF1A", error));
+  router.navigate = ((to, options2) => {
+    if (typeof to === "number") {
+      if (!disposed) routing.go(to);
+      return Promise.resolve();
+    }
+    const task = sync.enqueue(async () => {
+      await navigate(to, options2);
+      const l = router.state.location;
+      return { pathname: l.pathname, search: l.search, hash: l.hash };
+    }, options2?.replace ? "replace" : "push").then(() => {
     });
+    void task.catch((error) => console.error("[fulgurjs] \u5B50\u5E94\u7528 React \u8DEF\u7531\u540C\u6B65\u5931\u8D25\uFF1A", error));
+    return task;
   });
-  return {
+  let unwatch = () => {
+  };
+  if (!router.state.initialized) unwatch = router.subscribe(() => {
+    if (!router.state.initialized) return;
+    unwatch();
+    const actual = router.state.location;
+    if (!sameLocation(actual, init)) void sync.enqueue(async () => actual, "replace").catch((error) => console.error("[fulgurjs] \u521D\u59CB React \u8DEF\u7531\u540C\u6B65\u5931\u8D25\uFF1A", error));
+  });
+  const connection = {
     element: createElement(RouterProvider, { router }),
     dispose() {
       if (disposed) return;
+      options.signal?.removeEventListener("abort", connection.dispose);
       disposed = true;
       unwatch();
-      unsub();
+      sync.dispose();
+      router.dispose();
     }
   };
+  options.signal?.addEventListener("abort", connection.dispose, { once: true });
+  if (options.signal?.aborted) connection.dispose();
+  return connection;
 }
 export {
   createReactBridgeNavigation,