@fulgurjs/federation 5.4.0 → 5.4.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 5.4.1
+
+- 修复 URL 同步两端适配器将 replace 误报为 push、子应用 go/back/forward 未委托宿主历史，以及连续导航被丢弃的问题。
+- React 宿主等待真实 blocker 的 reset/proceed 与提交位置；canNavigate 改为可选预判。Vue 初始 ready 和导航执行异常不再吞掉，MFU-033 保留 cause，队列失败后可继续导航。
+- 修复 Vite 5/6 配套 plugin-react 4 的跨框架 dev preamble 标志缺失，避免 Vue 宿主加载 React 远程失败；子目录部署示例的 blocker 按逻辑路径判断。
+- 修复 React 18 + RR6 生产渲染的跨共享键 CJS 双实例：提供闭包只豁免自引用，react-dom → react 走同步协商；入口 init 前的同步副本复用现有 fallback 回写规则登记，避免 renderer 与组件使用不同 React。
+- 通道离页、暂停与卸载会作废在飞和排队请求；自定义宿主 navigate 可接收 AbortSignal；子应用接线可传 ctx.signal 自动清理。Vue history base 不再二次剥离；前缀与目标拒绝编码逃逸。
+
 ## 5.4.0
 
 - **新增：跨框架桥接 URL 同步（`/bridge/router/*`）**——宿主 URL 表达子应用内部位置：首次深链直达（不闪默认页、不发错接口）、刷新/收藏/新窗口恢复、子应用 Link/RouterLink/router.push 与宿主菜单/前进后退全量同步、根重定向以 replace 规范化（不凭空制造历史）。架构：宿主 Router 是浏览器历史唯一写入方，子应用用受控 memory 路由（Vue `connectVueBridgeRouter` / React `createReactBridgeRouter`，Link/useNavigate/RouterLink 全兼容）；独立路由通道承载位置与仲裁（请求编号/代次隔离/外部作废/取消恢复），path/search/hash 三段原样保留（重复键/编码/中文/片段不二次转换），同实例路径变化**不重挂 root、不重建 store、不重载远程**。

package/README.en.md

@@ -53,7 +53,7 @@ pnpm add -D @fulgurjs/federation
 - Vue ≥ 3.2.0 and/or React `>=18.0.0 <20` — all three are **optional peers**; install only the framework you use
 - Chrome 108+ (native top-level await)
 
-> Vite 8 (rolldown): as of 5.3.3, dev, production builds and production page mounting all pass full acceptance (bidirectional bridge 11-step interaction matrix, see the acceptance report). The first page open on a cold dev cache still falls inside the dependency pre-bundling window (DEV-010; it self-recovers via reload). Warm up before acceptance runs or manual judgement, as documented.
+> Vite 8 (rolldown): as of 5.3.3, dev, production builds and production page mounting all pass full acceptance (bidirectional bridge 11-step interaction matrix, see the acceptance report). **5.4.2 boundary note**: in production builds of large apps (e.g. JeecgBoot v3.9.5), the plugin's TLA share facades joining chunk merging can trigger a rolldown codegen bug that merges the app's own async initialization into a sync lazy init and drops the `async` marker (`SyntaxError: Unexpected reserved word`; minify/target/manualChunks variants and a bare-baseline comparison have ruled out other variables) — build such apps for production with Vite 5–7; dev is unaffected. The first page open on a cold dev cache still falls inside the dependency pre-bundling window (DEV-010; it self-recovers via reload). Warm up before acceptance runs or manual judgement, as documented.
 
 `@fulgurjs/federation/runtime` and `@fulgurjs/federation/react` are **ESM-only** browser entries (no `require()`). The build-time main entry supports both ESM and CJS.
 
@@ -343,13 +343,15 @@ The bridge defaults to memory routing: internal navigation does not touch the br
 
 **Architecture**: the host router is the only writer of browser history; the sub-app uses a controlled memory router; both sides communicate over a dedicated routing channel (not appProps/Context); path/search/hash changes within an instance **do not remount the root, do not rebuild stores, do not reload the remote**.
 
-**Host (Vue Router 4, history or hash mode)**: declare a suffix route (`/approval/:pathMatch(.*)*` — without it detail navigation unmounts the sub-app), add real guards (`beforeEach` rejecting → the channel receives `cancelled`, URL/history/sub-app position unchanged), then `createVueBridgeNavigation(router, { routerBase })` and pass `routing={{ basePath: '/approval', navigation }}` to the bridge component.
+**Host (Vue Router 4, history or hash mode)**: declare a suffix route (`/approval/:pathMatch(.*)*` — without it detail navigation unmounts the sub-app), add real guards (`beforeEach` rejecting → the channel receives `cancelled`, URL/history/sub-app position unchanged), then `createVueBridgeNavigation(router)` (Vue Router already removes its history base) and pass `routing={{ basePath: '/approval', navigation }}` to the bridge component.
 
 **Sub-app**: declare the protocol and wire a controlled router —
 Vue: `defineBridgeApp(async (props, ctx) => { const router = createRouter({ history: createMemoryHistory(), routes }); await connectVueBridgeRouter(ctx.routing!, router).ready; ... app.use(router); return app }, { routing: true })` (await ready BEFORE `app.use(router)` — the install-time initial navigation would otherwise override the deep-link location).
 React: `createReactBridgeRouter(ctx.routing!, routes).element` — `createMemoryRouter`-based; `Link`/`useNavigate` work unmodified.
 
-**Host (React Router)**: data routers only (`createBrowserRouter`/`createHashRouter` + `RouterProvider`); `createReactBridgeNavigation(router, { basename, canNavigate })`. Pass the same predicate to `canNavigate` and to an in-tree `useBlocker` — sub-app-originated navigations are cancelled by the port pre-check (zero URL/history side effects), menu/POP sources are blocked by the real blocker. Declarative `BrowserRouter` has no cancellation semantics and is not supported. Requires react-router ≥ 6.11.
+**Host (React Router)**: data routers only (`createBrowserRouter`/`createHashRouter` + `RouterProvider`); `createReactBridgeNavigation(router, { basename, canNavigate })`. `canNavigate` is an optional early rejection policy. The adapter also observes the real blocker: it waits for `reset()` (cancelled) or a committed navigation after `proceed()`. Resolving `router.navigate()` alone does not imply a commit. Declarative `BrowserRouter` has no cancellation semantics and is not supported. Requires react-router ≥ 6.11.
+
+**Lifecycle and navigation**: both child connectors accept an optional third argument `{ signal?: AbortSignal }`; pass `ctx.signal` to dispose on session invalidation, or call `connection.dispose()` yourself. Push and replace retain their history action; numeric navigation delegates to the host history. Concurrent requests are serialized and superseded requests are invalidated. Navigation errors reject with MFU-033 and preserve `cause`; they are not reported as cancellation. Custom host ports receive an optional third argument `{ signal }` and must check it before asynchronous commits.
 
 **Contract highlights**: `basePath` is a static absolute path from the host-router perspective (segment-matched; conflicting/overlapping prefixes rejected, `MFU-030`); location is compared and preserved as three raw strings (duplicate query keys, encoding, fragments survive without re-encoding); cancellation never auto-retries; session switch (`sessionKey→null`) invalidates the old channel — late navigations are rejected and never write the URL; KeepAlive-cached instances pause routing writes; enabling sync against a contract without `{ routing: true }` shows `MFU-031` instead of silently falling back to memory; escaping targets and illegal `go` arguments → `MFU-032`; redirect loops beyond 5 internal replaces → `MFU-033` with the chain attached. Router libraries are optional peers consumed only through the two opt-in entries (`/bridge/router/vue`, `/bridge/router/react`, each gated ≤ 4096B gzip); the default entries never load a router library. Not promised: SSR/RSC, cross-window, nested multi-level bridge routing proxies, TanStack Router and other libraries (extend via the `BridgeHostNavigation`/`BridgeChildRoute` ports).
 
@@ -420,7 +422,7 @@ Lazy-loading measurement layers: ① nothing until first render of a remote comp
 | MFU | `MFU-030` | Bridge URL-sync config invalid / prefix conflict (illegal basePath: empty, root, query/hash/wildcard; overlapping active prefixes) |
 | MFU | `MFU-031` | Bridge routing protocol missing / channel destroyed (sub-app not declared with `{ routing: true }`; disposed channel reused) |
 | MFU | `MFU-032` | Bridge illegal navigation (target escaping its own prefix, illegal `go` argument, request on a dead channel) |
-| MFU | `MFU-033` | Bridge routing sync failed (internal replace chain exceeds the bound of 5, chain attached; no silent fallback to memory) |
+| MFU | `MFU-033` | Bridge routing preparation/sync failed (redirect limit or navigation exception, chain/cause attached; no silent fallback to memory) |
 | CC | `CC-001` | AppContext required key missing (got/expected/example) |
 | | `CC-002` | runtime singleton unavailable (standalone remote page) |
 

package/README.md

@@ -51,7 +51,7 @@ pnpm add -D @fulgurjs/federation
 
 要求：Vite ≥ 5.1（实测至 8.x）、Node ≥ 18、Vue 3 和/或 React 18–19（均为可选 peer——按所用框架安装）、浏览器 Chrome 108+（TLA 原生支持）。
 
-> Vite 8（rolldown）：5.3.3 起 dev 与生产构建、生产页面挂载均已通过完整验收（双向桥接 11 步交互矩阵，见验收报告）。dev 冷启动首开仍受依赖预构建窗口影响（DEV-010，首轮打开自动恢复），验收与人工判断请按文档先预热。
+> Vite 8（rolldown）：5.3.3 起 dev 与生产构建、生产页面挂载均已通过完整验收（双向桥接 11 步交互矩阵，见验收报告）。**5.4.2 补充边界**：大型应用（如 JeecgBoot v3.9.5）生产构建下，插件的 TLA 共享门面参与 chunk 合并时可触发 rolldown 将应用 async 初始化语句合并丢 `async` 标记（`SyntaxError: Unexpected reserved word`，minify/target/manualChunks 变体与裸基线对照已排除其他变量）——此类应用生产构建请用 Vite 5–7，开发态不受影响。dev 冷启动首开仍受依赖预构建窗口影响（DEV-010，首轮打开自动恢复），验收与人工判断请按文档先预热。
 
 ## 快速开始（React 应用）
 
@@ -663,7 +663,7 @@ CLI 解析同一份配置值；dev/prod 的 URL 选择规则与 `federation({ re
 | | `MFU-030` | 桥接路由同步配置/前缀冲突（basePath 非法：空/根/带 query·hash·通配、同页重叠前缀登记） |
 | | `MFU-031` | 桥接路由协议缺失/通道失效（子应用未以 `{ routing: true }` 声明协议、通道销毁后复用） |
 | | `MFU-032` | 桥接非法导航（子应用导航目标越界自身前缀、`go` 参数非法、失效通道的请求被拒绝） |
-| | `MFU-033` | 桥接路由同步失败（重定向链超出上限，附目标链；不静默回退 memory） |
+| | `MFU-033` | 桥接路由准备/同步失败（重定向超限或导航异常，附目标链/cause；不静默回退 memory） |
 | CC 跨应用上下文 | `CC-001` | AppContext 必需字段缺失（三段式：got/expected/example，修法指向宿主桥 `provideAppContext`） |
 | | `CC-002` | 运行时单例不可用（独立直开远程页；修法 = 经宿主联邦加载，时序契约 bridge → 远程 setup → 页面模块） |
 
@@ -903,7 +903,7 @@ router.beforeEach((to) => (to.path.startsWith('/approval/secret') ? false : unde
 <script setup lang="ts">
 import { createVueBridgeApp } from '@fulgurjs/federation/bridge/vue'
 import { createVueBridgeNavigation, type BridgeHostRouting } from '@fulgurjs/federation/bridge/router/vue'
-const navigation = createVueBridgeNavigation(router) // routerBase 用于 createWebHistory(base) 场景
+const navigation = createVueBridgeNavigation(router) // Vue Router fullPath 已是逻辑路径，无需传部署 base
 const routing: BridgeHostRouting = { basePath: '/approval', navigation }
 const RemoteApp = createVueBridgeApp('remote/bridge-routed', { /* 同 8.2 */ })
 </script>
@@ -920,11 +920,12 @@ import { createRouter, createMemoryHistory, RouterView } from 'vue-router'
 import { defineBridgeApp } from '@fulgurjs/federation/runtime'
 import { connectVueBridgeRouter } from '@fulgurjs/federation/bridge/router/vue'
 export default defineBridgeApp(async (props, ctx) => {
+  if (!ctx?.routing) throw new Error('本契约需要宿主启用 URL 同步')
   const router = createRouter({ history: createMemoryHistory(), routes: [
     { path: '/list', component: List },
     { path: '/detail/:id', component: Detail },
   ] })
-  await connectVueBridgeRouter(ctx.routing!, router).ready // 初始 push 落定后再 install（顺序不能反）
+  await connectVueBridgeRouter(ctx.routing!, router, { signal: ctx.signal }).ready // 初始 push 落定后再 install（顺序不能反）
   const app = createApp({ setup: () => () => h(RouterView) }, props)
   app.use(router)
   return app
@@ -934,21 +935,25 @@ export default defineBridgeApp(async (props, ctx) => {
 ```tsx
 // bridge.tsx（React 子应用）：createReactBridgeRouter 返回 RouterProvider 元素
 import { createReactBridgeRouter } from '@fulgurjs/federation/bridge/router/react'
-export default defineBridgeApp((_props, ctx) =>
-  createReactBridgeRouter(ctx.routing!, [
+import { defineBridgeApp } from '@fulgurjs/federation/react'
+export default defineBridgeApp((_props, ctx) => {
+  if (!ctx?.routing) throw new Error('本契约需要宿主启用 URL 同步')
+  return createReactBridgeRouter(ctx.routing, [
     { path: '/list', element: <List /> },
     { path: '/detail/:id', element: <Detail /> },
-  ]).element, { routing: true })
+  ], { signal: ctx.signal }).element
+}, { routing: true })
 ```
 
-宿主端 React Router 仅支持 **data router 模式**（`createBrowserRouter` / `createHashRouter` + `RouterProvider`）：`createReactBridgeNavigation(router, { basename, canNavigate })`。`canNavigate` 与树内 `useBlocker` 传同一谓词——子应用发起的导航被拒绝时由端口预判返回 cancelled（URL/历史零副作用），菜单/POP 等其他来源由 useBlocker 真实拦截。declarative 模式（BrowserRouter）无取消语义，不支持。React Router 要求 ≥ 6.11（createMemoryRouter）。
+宿主端 React Router 仅支持 **data router 模式**（`createBrowserRouter` / `createHashRouter` + `RouterProvider`）：`createReactBridgeNavigation(router, { basename, canNavigate })`。`canNavigate` 可选，仅作提前拒绝；端口观察真实 `useBlocker` 状态，等待 `reset()` 返回 cancelled、`proceed()` 后实际位置提交返回 committed，不能只凭 navigate 的 Promise 落定判成功。declarative 模式（BrowserRouter）无取消语义，不支持。React Router 要求 ≥ 6.11（createMemoryRouter）。
 
 **③ 行为契约与边界**：
 
 - **basePath**：宿主路由视角的静态绝对路径（拒绝空/根/带 query·hash·通配符，`MFU-030`）；按路径段匹配（`/approval` 命中 `/approval/detail/1`，不命中 `/approval-old`）；同页各同步实例前缀不得相同或重叠。`/approval` 对应子应用 `/`；根重定向由子应用路由定义、以 replace 规范化（不凭空多一条历史）。
-- **Vite base 与路由分层**：部署在 `/erp/` 时 Vite base/宿主 Router base 是 `/erp/`，bridge basePath 仍是 `/approval`（Vue 传 `routerBase`、React 传 `basename`）；适配器输出的逻辑路径不含部署前缀，不会拼出 `/erp/erp/...`。子目录部署 + hash 模式内层片段见 e2e fixtures（`fixtures/host-bridge-*/`，可运行参考实现）。
+- **Vite base 与路由分层**：部署在 `/erp/` 时 Vite base/宿主 Router base 是 `/erp/`，bridge basePath 仍是 `/approval`（Vue Router 已自动剥离 history base，React 端口传 `basename`）；适配器输出的逻辑路径不含部署前缀，不会拼出 `/erp/erp/...`。子目录部署 + hash 模式内层片段见 e2e fixtures（`fixtures/host-bridge-*/`，可运行参考实现）。
 - **位置三段全等**：search/hash 原样保留（重复 query 键、编码、中文、片段不二次 decode/encode）；仅参数变化也同步，且不重挂。
-- **取消语义**：Vue Router 4 的 push/replace 落定 `NavigationFailure` 即真实取消；React Router data router 用 canNavigate 预判（与 useBlocker 同谓词）+ 树内 blocker。取消后 URL、历史、子应用位置保持最后确认状态，**绝不自动重试**（`router.push` 的函数返回不冒充提交成功）。
+- **取消语义**：Vue Router 4 的 push/replace 落定 `NavigationFailure` 即真实取消；React Router data router 等待真实 blocker 的取消/放行，`canNavigate` 仅为可选提前拒绝。取消后 URL、历史、子应用位置保持最后确认状态，**绝不自动重试**（`router.push` 的函数返回不冒充提交成功）。
+- **导航与错误**：子应用 push/replace 保留原动作，go/back/forward 委托宿主历史；连续请求串行落定，外部导航作废旧的在飞与排队请求。守卫/加载器/端口执行异常拒绝 Promise（MFU-033，保留 cause），不会伪装 cancelled。两端子路由接线的第三参数 `{ signal?: AbortSignal }` 默认为空；推荐传 `ctx.signal` 自动 dispose，未传时由子应用显式调用连接的 `dispose()`。自定义 `BridgeHostNavigation.navigate(target, action, { signal })` 应在异步提交前复核可选 signal，已 aborted 时禁止迟到写入。
 - **会话与生命周期**：换账号/登出（`sessionKey→null`）作废旧通道——旧通道的导航一律 cancelled、不写 URL、不复活子应用；unmount 后迟到通知失效（通道销毁，再订阅得 `MFU-031`）。KeepAlive 缓存离页的实例暂停路由写入（不抢占 URL、不销毁通道，激活重同步）。同一容器 unmount 抛错的持久封锁（BN09）不因路由绕过。
 - **协议校验**：宿主启用 routing 而子应用未声明 `{ routing: true }`（契约 `routing: { protocol: 1 }`）→ `MFU-031` 占位，**不静默退回 memory 假装深链成功**。
 - **非法导航与循环**：目标越界自身前缀（`../`、跨前缀）、非法 `go` 参数 → `MFU-032`；连续内部 replace 超过 5 次（重定向环）→ `MFU-033`（附目标链，不静默回入口）。

package/dist/bridge-app-react.d.cts

@@ -1,6 +1,6 @@
 import { ReactElement } from 'react';
 import { BridgeApp } from './bridge-core.cjs';
-import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.cjs';
+import { B as BridgeChildRoute } from './bridge-router-core-BRZQYDPm.cjs';
 import './context.cjs';
 
 /**

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

@@ -1,6 +1,6 @@
 import { ReactElement } from 'react';
 import { BridgeApp } from './bridge-core.js';
-import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.js';
+import { B as BridgeChildRoute } from './bridge-router-core-BRZQYDPm.js';
 import './context.js';
 
 /**

package/dist/bridge-app-react.js

@@ -1,6 +1,6 @@
 import {
   bridgeLifecycleError
-} from "./chunk-JQF7KYZF.js";
+} from "./chunk-HZGQOW35.js";
 import "./chunk-OF2JCXTZ.js";
 
 // src/bridge-app-react.ts

package/dist/bridge-app-vue.d.cts

@@ -1,6 +1,6 @@
 import { App } from 'vue';
 import { BridgeApp } from './bridge-core.cjs';
-import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.cjs';
+import { B as BridgeChildRoute } from './bridge-router-core-BRZQYDPm.cjs';
 import './context.cjs';
 
 /**

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

@@ -1,6 +1,6 @@
 import { App } from 'vue';
 import { BridgeApp } from './bridge-core.js';
-import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.js';
+import { B as BridgeChildRoute } from './bridge-router-core-BRZQYDPm.js';
 import './context.js';
 
 /**

package/dist/bridge-app-vue.js

@@ -1,6 +1,6 @@
 import {
   bridgeLifecycleError
-} from "./chunk-JQF7KYZF.js";
+} from "./chunk-HZGQOW35.js";
 import "./chunk-OF2JCXTZ.js";
 
 // src/bridge-app-vue.ts

package/dist/{bridge-core-BOWvVUxO.d.ts → bridge-core-ejlY9ddN.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-core.d.cts

@@ -1,5 +1,5 @@
 import { AppContext } from './context.cjs';
-import { a as BridgeMountOptions, b as BridgeRoutingProtocol } from './bridge-router-core-BxBx-reP.cjs';
+import { a as BridgeMountOptions, b as BridgeRoutingProtocol } from './bridge-router-core-BRZQYDPm.cjs';
 
 /** 子应用桥接契约（远程 ./bridge 模块的默认导出；任务书 §3.2） */
 interface BridgeApp {

package/dist/bridge-core.d.ts

@@ -1,5 +1,5 @@
 import { AppContext } from './context.js';
-import { a as BridgeMountOptions, b as BridgeRoutingProtocol } from './bridge-router-core-BxBx-reP.js';
+import { a as BridgeMountOptions, b as BridgeRoutingProtocol } from './bridge-router-core-BRZQYDPm.js';
 
 /** 子应用桥接契约（远程 ./bridge 模块的默认导出；任务书 §3.2） */
 interface BridgeApp {

package/dist/bridge-core.js

@@ -6,8 +6,8 @@ import {
   releaseBridgeSession,
   resolveBridgeContext,
   withBridgeTimeout
-} from "./chunk-PRUYHYX2.js";
-import "./chunk-JQF7KYZF.js";
+} from "./chunk-RXXBTPAY.js";
+import "./chunk-HZGQOW35.js";
 import "./chunk-TSYLDY6H.js";
 import "./chunk-OF2JCXTZ.js";
 export {

package/dist/bridge-errors.cjs

@@ -143,13 +143,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 }
   );
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/bridge-errors.d.cts

@@ -47,6 +47,6 @@ declare function routingProtocolError(spec: string, reason: string): FgError;
 /** MFU-032：非法导航（越界目标、非法 go 参数、失效通道请求被拒绝） */
 declare function routingNavigationError(spec: string, reason: string): FgError;
 /** MFU-033：路由准备/同步失败（重定向循环等；不伪装成功也不静默回退 memory） */
-declare function routingSyncError(spec: string, reason: string, chain: string[]): FgError;
+declare function routingSyncError(spec: string, reason: string, chain: string[], cause?: unknown): FgError;
 
 export { BridgeErrorCodes, type BridgePhase, bridgeLifecycleError, bridgeSessionMismatchError, invalidBridgeContractError, invalidSessionKeyError, routingConfigError, routingNavigationError, routingProtocolError, routingSyncError };

package/dist/bridge-errors.d.ts

@@ -47,6 +47,6 @@ declare function routingProtocolError(spec: string, reason: string): FgError;
 /** MFU-032：非法导航（越界目标、非法 go 参数、失效通道请求被拒绝） */
 declare function routingNavigationError(spec: string, reason: string): FgError;
 /** MFU-033：路由准备/同步失败（重定向循环等；不伪装成功也不静默回退 memory） */
-declare function routingSyncError(spec: string, reason: string, chain: string[]): FgError;
+declare function routingSyncError(spec: string, reason: string, chain: string[], cause?: unknown): FgError;
 
 export { BridgeErrorCodes, type BridgePhase, bridgeLifecycleError, bridgeSessionMismatchError, invalidBridgeContractError, invalidSessionKeyError, routingConfigError, routingNavigationError, routingProtocolError, routingSyncError };

package/dist/bridge-errors.js

@@ -8,7 +8,7 @@ import {
   routingNavigationError,
   routingProtocolError,
   routingSyncError
-} from "./chunk-JQF7KYZF.js";
+} from "./chunk-HZGQOW35.js";
 import "./chunk-OF2JCXTZ.js";
 export {
   BridgeErrorCodes,

package/dist/{bridge-host-react-CMVd-ym0.d.ts → bridge-host-react-Bua1TCVh.d.ts}

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { A as AppContext } from './bridge-core-BOWvVUxO.js';
+import { A as AppContext } from './bridge-core-ejlY9ddN.js';
 
 /**
  * React 宿主桥接工厂（/bridge、/bridge/react 导出 createReactBridgeApp；任务书 §3.4）。

package/dist/bridge-host-react.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-react.d.cts

@@ -1,6 +1,6 @@
 import { ReactNode, ComponentType } from 'react';
 import { AppContext } from './context.cjs';
-import { c as BridgeHostRouting } from './bridge-router-core-BxBx-reP.cjs';
+import { c as BridgeHostRouting } from './bridge-router-core-BRZQYDPm.cjs';
 
 /**
  * React 宿主桥接工厂（/bridge、/bridge/react 导出 createReactBridgeApp；任务书 §3.4）。

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

@@ -1,6 +1,6 @@
 import { ReactNode, ComponentType } from 'react';
 import { AppContext } from './context.js';
-import { c as BridgeHostRouting } from './bridge-router-core-BxBx-reP.js';
+import { c as BridgeHostRouting } from './bridge-router-core-BRZQYDPm.js';
 
 /**
  * React 宿主桥接工厂（/bridge、/bridge/react 导出 createReactBridgeApp；任务书 §3.4）。

package/dist/bridge-host-react.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-host-vue-BuCGlLdS.d.ts → bridge-host-vue-Dd1kkwDb.d.ts}

@@ -1,5 +1,5 @@
 import { Component } from 'vue';
-import { A as AppContext } from './bridge-core-BOWvVUxO.js';
+import { A as AppContext } from './bridge-core-ejlY9ddN.js';
 
 /**
  * Vue 宿主桥接工厂（/bridge、/bridge/vue 导出 createVueBridgeApp；任务书 §3.4）。