@fulgurjs/federation 5.3.3 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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、不重载远程**。
+- **启用即校验，默认关闭**：`routing` prop（`{ basePath, navigation }`）显式开启；子应用 `defineBridgeApp(工厂, { routing: true })` 声明协议（工厂第二参数 `{ signal, routing }`，Vue 工厂支持 Promise 形态——初始 memory push 落定后必须再 `app.use(router)`，install 初始导航会覆盖深链位置，原型实证）。未声明协议而宿主启用 → `MFU-031`（不静默退回 memory）；basePath 非法/前缀冲突 → `MFU-030`；越界导航/非法 go → `MFU-032`；重定向环 → `MFU-033`（附目标链）。
+- **取消语义（真实框架行为）**：Vue Router 4 push/replace 落定 NavigationFailure 即真实取消（URL/历史/子应用位置保持确认态，不自动重试）；React Router 仅支持 data router（`createBrowserRouter/createHashRouter`），`canNavigate` 与树内 `useBlocker` 同谓词——RR 的 navigate 被 blocker 拦截时静默返回 void（dist 源码核实），故端口预判取消零副作用。RR `location.pathname` 含 basename，端口新增 `basename` 选项剥部署前缀（§2.3 分层，生产子目录部署实测抓出）。
+- **会话与生命周期**：换账号/登出作废旧通道（旧导航 cancelled、不写 URL、不复活子应用）；unmount 后迟到通知失效；KeepAlive 离页暂停写入（不抢占 URL、不销毁共享端口）；卸载失败容器封锁语义不变。前缀按路径段匹配并在页面级登记互斥。
+- **包接线**：新增 `./bridge/router/vue`、`./bridge/router/react` 按需入口（vue-router ≥4.1 / react-router-dom ≥6.11 为可选 peer）；默认 `/bridge`、`/runtime`、`/react` 零路由库导入（导入图门禁覆盖）；两个路由入口各 ≤4096B gzip 门禁；错误码 44 → 48（三方一致）。宿主两入口 gzip：bridge-host-vue 3103B / bridge-host-react 2575B（仍 ≤4096B）。
+- **质量门禁**：原型门禁 27/27（双向 + hash 变体，可控竞态断言）；单测 566 → 589（路由内核/双端适配/宿主 routing 集成 23 例）；e2e 新增 bridge-router 双向 dev 13 例 + 生产 U08（真实 nginx 回退深链刷新 + 资源 404 不被掩盖）；全量 e2e dev 43 + prod 28 + 桥接六项目 33 全绿。**已知开发态边界**：workspace link（pnpm 双虚拟仓库）下宿主/子各持一份 react-router-dom 物理副本会断 Router context——fixtures 以 `resolve.alias` 统一副本（README 8.8/8.3 说明；registry 正式包消费无此问题）。
+
 ## 5.3.3
 
 - **修复：loadShare × pinLoadedShare 并发窗口的单例双实例风险（F9）**——`loadShare` 设置 `entry.loaded` 后等待 `entry.get()` 期间，CJS 垫片的 `pinLoadedShare` 可同步写入本地实例；getter 完成后原实现直接覆盖 `entry.value`，同步 CJS 消费者与异步消费者各持一份实例。现在实行条目实例 first-wins（协商结果让位于先写入的 pin/fallback 实例，loadShare 返回条目当前 value）、条目级 in-flight get（并发 loadShare 共享同一次加载，getter 恰好调用一次）、getter 拒绝后回滚 `entry.loaded`（修复前死条目残留「已加载」标记会永久抢占单例的已加载优先）——失败窗口内已有 pin 时收敛到 pin 实例。8 个确定性回归（可控 Promise 门）覆盖挂起中 pin / pin 先行 / 并发去重 / 拒绝重试与状态恢复 / resolveShare 组合 / 多版本边界；单元 558 → 566。`runtime.js` gzip 9204B ≤ 9216B。

package/DESIGN.md

@@ -207,3 +207,7 @@ remote 样式改动立即生效；host 自身业务 HMR 不受影响。
 - M2（dev 闭环）验收加：副本三 dev server 实测
 - M3（shared 全语义）验收加：element-plus 双版本共存（bpm 2.9.1 vs lowcode 2.10.2）实测
 - M6 验收加：NGINX 测试站点 prod 全量 e2e 绿 + 后台接口经反代连通
+
+## 6.3 桥接 URL 同步（5.4.0）
+
+宿主 Router 是浏览器历史的唯一写入方；子应用运行受控 memory 路由。两者以「路由通道」相连：通道由桥接宿主按挂载代次创建（一个同步实例一条），随 mount 第三参数交给子应用，随 unmount/换代销毁。通道职责：位置三段（path/search/hash）的原样换算（前缀按段匹配、页面级登记互斥）、子应用导航请求的串行化与编号、宿主裁决仲裁（committed/cancelled/superseded）、有界重定向检测。宿主端口（Vue `createVueBridgeNavigation` / React `createReactBridgeNavigation`）只做 Router→端口的语义换算：Vue 直接复用 push/replace 的 NavigationFailure 作为真实取消；React data router 用 canNavigate 预判（与 useBlocker 同谓词）+ 树内 blocker 保护其他来源。KeepAlive 用通道的 active 开关暂停/恢复写入而非销毁。路由能力全部住在按需入口（`/bridge/router/*`），默认入口零路由库导入。

package/README.en.md

@@ -261,7 +261,7 @@ Type generation supports string or array `extends` (later entries override earli
 
 ### 8.7 Cross-framework bridge — `/bridge` (sub-app-level Vue↔React, 5.3.0+)
 
-**Scope**: whole-app mount/unmount embedding both ways — a Vue 3 host mounts a React 18/19 sub-app, and a React host mounts a Vue 3 sub-app. Component-level conversion, host↔sub-app URL sync, Angular, SSR/RSC, JS sandbox, CSS isolation are out of scope (§12).
+**Scope**: whole-app mount/unmount embedding both ways — a Vue 3 host mounts a React 18/19 sub-app, and a React host mounts a Vue 3 sub-app. Component-level conversion, Angular, SSR/RSC, JS sandbox, CSS isolation are out of scope (§12). Sub-app internal route ↔ browser URL sync is available since 5.4.0 (§8.8).
 
 #### Entries & import graph
 
@@ -337,6 +337,22 @@ const RemoteVueApp = createReactBridgeApp('bridge-vue-remote/bridge', { getConte
 - **Controlled `sessionKey`**: accepts `undefined` (no controlled validation) / `null` (logged out: unmount immediately, keep the container empty, stop loading) / non-empty string (login generation). Illegal values → `MFU-017`.
 - **Multi-instance**: several same-spec instances coexist (per-el keying); `AppContext` is a page-level singleton — all controlled instances on a page must share the same session (`MFU-017` otherwise). React StrictMode double-effect is safe. Vue `<KeepAlive>` deactivation is **not** an unmount. Late results from invalidated generations are dropped by generation guards; a remote `onSession` must honor the existing `signal.aborted` contract.
 
+### 8.8 Bridge URL sync — `/bridge/router/*` (sub-app internal routes ↔ browser URL, 5.4.0+)
+
+The bridge defaults to memory routing: internal navigation does not touch the browser URL and refresh cannot restore the sub-app's internal page. URL sync makes the **host URL express the sub-app's internal location** — deep links, refresh, bookmarks, back/forward and host-menu navigation all agree. It is opt-in; **default is off** (5.3.x behavior and legacy contracts unchanged).
+
+**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.
+
+**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.
+
+**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).
+
 ## 9. Artifacts, endpoints & caching
 
 | Artifact | Cache policy |
@@ -355,7 +371,7 @@ Lazy-loading measurement layers: ① nothing until first render of a remote comp
 - `DEBUG=fulgurjs:*` — controlled pipeline diagnostics (off by default)
 - Runtime diagnostics are emitted in Chinese by design (language policy); codes are stable identifiers listed below
 
-## 11. Error codes (44)
+## 11. Error codes (48)
 
 | Segment | Code | Meaning |
 |---|---|---|
@@ -401,13 +417,17 @@ Lazy-loading measurement layers: ① nothing until first render of a remote comp
 | | `MFU-015` | bridge contract invalid (`./bridge` default export missing non-function mount/unmount; fix points to `defineBridgeApp`) |
 | | `MFU-016` | bridge preparation or lifecycle failure (`details.phase` = getContext/mount/unmount; cause keeps the sub-app's original error) |
 | | `MFU-017` | bridge session mismatch (controlled sessionKey vs AppContext / illegal value / page-level single-session conflict) |
+| 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) |
 | CC | `CC-001` | AppContext required key missing (got/expected/example) |
 | | `CC-002` | runtime singleton unavailable (standalone remote page) |
 
 ## 12. Boundaries (explicitly not supported)
 
 - Support covers **browser-client** federation for Vue 3 and React 18–19. Not supported: SSR, React Server Components, Next.js full-stack, React Native, Node-side remote loading. **Cross-framework boundary (5.3.0+)**: sub-app-level embedding is supported (§8.7 `/bridge`); direct component-level Vue↔React rendering in one tree is not (that is the product of framework-conversion libraries). Pure single-framework projects keep zero cross-dependency
-- **Bridge isolation boundary (declared honestly in §8.7)**: bridging isolates only the mount/unmount edge of the two component trees — no browser realm isolation. Remote global CSS, `body`/`html` styles, global variables, and DOM rendered outside the container via React Portal / Vue Teleport still affect the host; `unmount` cannot revoke CSS the browser already loaded. Sub-app internal errors do not bubble into host error boundaries (cross-root). Sub-apps use memory routing — v1 does **not** sync to the host URL (refreshing does not restore the sub-app's internal path)
+- **Bridge isolation boundary (declared honestly in §8.7)**: bridging isolates only the mount/unmount edge of the two component trees — no browser realm isolation. Remote global CSS, `body`/`html` styles, global variables, and DOM rendered outside the container via React Portal / Vue Teleport still affect the host; `unmount` cannot revoke CSS the browser already loaded. Sub-app internal errors do not bubble into host error boundaries (cross-root). Sub-app routing defaults to memory mode; explicit URL sync exists since 5.4.0 (§8.8) — when it is not enabled, refreshing does not restore the sub-app's internal path
 - React side does not promise component keep-alive (`keepAliveNames` is Vue-only); re-opened pages still reuse downloaded modules
 - Cross-origin Fast Refresh: remote React components update via the remote dev server's HMR push; after a cold start the first round often needs a host refresh — component-state retention across the federation boundary is not promised
 - Not compatible with originjs `virtual:__federation__` legacy imports

package/README.md

@@ -614,7 +614,7 @@ CLI 解析同一份配置值；dev/prod 的 URL 选择规则与 `federation({ re
 | `fulgurjs check-pages [--config <path>] [--site <URL>] [--manifest <r>=<路径\|URL>]... [--require-verified]` | 页面契约核对：宿主页面表（`hostPages` 具名导出）↔ 远程 manifest exposes。manifest 来源优先级 **`--manifest`（可多次、文件路径或 URL） > `--site`/消费方 prod 地址推导**（显式来源失败不回退、无本地 dist 兜底），输出每个 remote 的实际命中来源（防止旧本地 dist 冒充线上核对）。报告未知 remote、映射到未消费远程、缺失 expose、路由冲突（R1–R5）；**确定性错误退出码 1**，远程不可达报「无法验证」，`--require-verified` 时无法验证也非零（CI 严格模式，避免 0 条核对显示通过）。`--json` 供 CI |
 | `fulgurjs doctor --base <URL> --apps <a,b,c>` | 部署体检：remoteEntry/manifest/index.html 的 200/no-cache/JS 形态、CORS、chunk 抽样可达、版本 skew 预演。`--dev` 检查 dev 容器入口；`--json` 输出 JSON（CI 断言）；`--chunk-sample N` 控制抽样数（默认 16）。**退出码：有 FAIL 即 1**，可直接做 CI 门禁 |
 
-### 6. 错误码总表（44 个）
+### 6. 错误码总表（48 个）
 
 | 段 | 码 | 含义 |
 |---|---|---|
@@ -660,6 +660,10 @@ CLI 解析同一份配置值；dev/prod 的 URL 选择规则与 `federation({ re
 | | `MFU-015` | 桥接契约非法（`./bridge` 默认导出缺 mount/unmount 或非函数；修法指向 defineBridgeApp） |
 | | `MFU-016` | 桥接准备或生命周期失败（`details.phase` 区分 getContext/mount/unmount；根因含子应用原始错误） |
 | | `MFU-017` | 桥接会话参数与 AppContext 不一致（受控 sessionKey 与全局会话矛盾、非法值（空串/数字）、页面级单会话冲突） |
+| | `MFU-030` | 桥接路由同步配置/前缀冲突（basePath 非法：空/根/带 query·hash·通配、同页重叠前缀登记） |
+| | `MFU-031` | 桥接路由协议缺失/通道失效（子应用未以 `{ routing: true }` 声明协议、通道销毁后复用） |
+| | `MFU-032` | 桥接非法导航（子应用导航目标越界自身前缀、`go` 参数非法、失效通道的请求被拒绝） |
+| | `MFU-033` | 桥接路由同步失败（重定向链超出上限，附目标链；不静默回退 memory） |
 | CC 跨应用上下文 | `CC-001` | AppContext 必需字段缺失（三段式：got/expected/example，修法指向宿主桥 `provideAppContext`） |
 | | `CC-002` | 运行时单例不可用（独立直开远程页；修法 = 经宿主联邦加载，时序契约 bridge → 远程 setup → 页面模块） |
 
@@ -873,6 +877,84 @@ const RemoteVueApp = createReactBridgeApp('bridge-vue-remote/bridge', {
 - **DOM 所有权**：包装组件只创建并保持稳定的空挂载容器；pending/error 占位是它的兄弟节点，宿主重渲染不 patch 子应用 root 内部。React 宿主 StrictMode 双 effect（mount→cleanup→mount）安全。Vue `<KeepAlive>` 的 deactivate 不是卸载——缓存页中的子应用保有 root 与状态；需要离页即销毁就别缓存该页，登出流程应同时移除缓存的私有页面。
 - **旧请求不冒充取消**：已进入 `loadRemote` 的工作不因桥接层作废而被取消——迟到的旧结果按代次丢弃（不 mount、不覆盖、无未处理拒绝）；远程 `onSession` 必须遵守既有 `signal.aborted` 契约（异步等待后、写私有状态前检查信号）。
 
+### 8.3 桥接 URL 同步 — `/bridge/router/*`（子应用内部路由 ↔ 宿主浏览器地址，5.4.0 起）
+
+桥接默认 memory 路由：子应用内部跳转不改浏览器地址、刷新不能恢复子应用内部页面。URL 同步让**宿主 URL 表达子应用内部位置**——刷新直达、收藏分享、前进后退、宿主菜单跳转全部一致。显式开启，**默认关闭**（5.3.x 行为与老契约完全不变）。
+
+**架构约定**：宿主 Router 是浏览器历史唯一写入方；子应用使用受控 memory 路由；两端经独立路由通道（不进 appProps/Context）传递位置；同实例内 path/search/hash 变化**不重挂 root、不重建 store、不重新加载远程**。
+
+**① 宿主（Vue Router 4，history/hash 模式皆可）**：
+
+```ts
+// main.ts：宿主路由声明后缀匹配（缺它详情导航会卸载子应用！）
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL), // hash 模式用 createWebHashHistory
+  routes: [
+    { path: '/', component: Home },
+    { path: '/approval/:pathMatch(.*)*', component: ApprovalBridgePage },
+  ],
+})
+// 真实权限守卫：拒绝 → 通道收到 cancelled，URL/历史/子应用位置全部不变
+router.beforeEach((to) => (to.path.startsWith('/approval/secret') ? false : undefined))
+```
+
+```vue
+<!-- ApprovalBridgePage.vue：路由 prop = 独立控制通道 -->
+<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 routing: BridgeHostRouting = { basePath: '/approval', navigation }
+const RemoteApp = createVueBridgeApp('remote/bridge-routed', { /* 同 8.2 */ })
+</script>
+<template>
+  <RemoteApp :session-key="sess" :routing="routing" :app-props="props" />
+</template>
+```
+
+**② 子应用（声明协议 + 接线受控路由）**：
+
+```ts
+// bridge.ts（Vue 子应用）：defineBridgeApp(工厂, { routing: true })——工厂第二参数 { signal, routing }
+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) => {
+  const router = createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/list', component: List },
+    { path: '/detail/:id', component: Detail },
+  ] })
+  await connectVueBridgeRouter(ctx.routing!, router).ready // 初始 push 落定后再 install（顺序不能反）
+  const app = createApp({ setup: () => () => h(RouterView) }, props)
+  app.use(router)
+  return app
+}, { routing: true })
+```
+
+```tsx
+// bridge.tsx（React 子应用）：createReactBridgeRouter 返回 RouterProvider 元素
+import { createReactBridgeRouter } from '@fulgurjs/federation/bridge/router/react'
+export default defineBridgeApp((_props, ctx) =>
+  createReactBridgeRouter(ctx.routing!, [
+    { path: '/list', element: <List /> },
+    { path: '/detail/:id', element: <Detail /> },
+  ]).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）。
+
+**③ 行为契约与边界**：
+
+- **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-*/`，可运行参考实现）。
+- **位置三段全等**：search/hash 原样保留（重复 query 键、编码、中文、片段不二次 decode/encode）；仅参数变化也同步，且不重挂。
+- **取消语义**：Vue Router 4 的 push/replace 落定 `NavigationFailure` 即真实取消；React Router data router 用 canNavigate 预判（与 useBlocker 同谓词）+ 树内 blocker。取消后 URL、历史、子应用位置保持最后确认状态，**绝不自动重试**（`router.push` 的函数返回不冒充提交成功）。
+- **会话与生命周期**：换账号/登出（`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`（附目标链，不静默回入口）。
+- **按需加载**：`/bridge`、`/runtime`、`/react` 默认入口不引入任何路由库；`/bridge/router/vue`、`/bridge/router/react` 为按需入口（`vue-router` / `react-router-dom` 为可选 peer，消费者自装）。两个入口各 ≤4096B gzip 门禁。
+- **不承诺**：SSR/RSC、跨浏览器窗口、嵌套多级桥接子应用路由代理、TanStack Router 及其他路由库（可经 `BridgeHostNavigation`/`BridgeChildRoute` 端口自定义扩展）。
+
 ### 9. `AppContext` — 跨应用传值与方法引用（`@fulgurjs/federation/runtime`）
 
 宿主向子应用传值、子应用向宿主反向注册方法，一律走这条一等公民通道（对标乾坤 `props`，但带类型与错误契约）——不再各自挂 `window.*` 裸口子。

package/dist/bridge-app-react.cjs

@@ -54,7 +54,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 bridgeLifecycleError(phase, spec, cause, extra) {
   const raw = cause instanceof Error ? cause.message : String(cause ?? "unknown");
@@ -95,18 +103,20 @@ function CommitProbe({ children, onCommit }) {
   }, []);
   return children ?? null;
 }
-function defineBridgeApp(factory) {
+function defineBridgeApp(factory, options = {}) {
   return {
-    mount(el, props) {
+    ...options.routing ? { routing: { protocol: 1 } } : {},
+    mount(el, props, mountOptions) {
       if (entriesByEl.has(el)) {
         throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
           reason: "container-occupied"
         });
       }
       const snapshot = { ...props ?? {} };
+      const ctx = { signal: mountOptions?.signal, routing: mountOptions?.routing };
       let element;
       try {
-        element = factory(snapshot);
+        element = factory(snapshot, ctx);
       } catch (e) {
         throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
       }

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

@@ -1,5 +1,6 @@
 import { ReactElement } from 'react';
 import { BridgeApp } from './bridge-core.cjs';
+import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.cjs';
 import './context.cjs';
 
 /**
@@ -21,8 +22,19 @@ import './context.cjs';
  * 本文件零 Vue：/react 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
  */
 
-/** React 子应用工厂：接收挂载时 props 快照，返回 ReactElement（路由等由调用方自行包裹） */
-type ReactBridgeAppFactory = (props: Record<string, unknown>) => ReactElement;
+/** 工厂第二参数：挂载生命周期与路由通道（URL 同步；不混入业务 props） */
+interface ReactBridgeAppContext {
+    /** 会话代次信号（登出/换代即 aborted；异步写回前必须检查） */
+    signal?: AbortSignal;
+    /** 路由通道（宿主启用 URL 同步时存在）；配 createReactBridgeRouter 使用 */
+    routing?: BridgeChildRoute;
+}
+/** React 子应用工厂：接收挂载时 props 快照与生命周期上下文，返回 ReactElement */
+type ReactBridgeAppFactory = (props: Record<string, unknown>, ctx?: ReactBridgeAppContext) => ReactElement;
+interface DefineReactBridgeAppOptions {
+    /** 声明路由协议（URL 同步）：契约写入 routing: { protocol: 1 }（缺失时宿主启用同步即 MFU-031） */
+    routing?: boolean;
+}
 /**
  * 定义 React 子应用的桥接契约（远程 ./bridge 模块默认导出）。
  *
@@ -32,6 +44,6 @@ type ReactBridgeAppFactory = (props: Record<string, unknown>) => ReactElement;
  * export default defineBridgeApp((props) => <MemoryRouter><App {...props} /></MemoryRouter>)
  * ```
  */
-declare function defineBridgeApp(factory: ReactBridgeAppFactory): BridgeApp;
+declare function defineBridgeApp(factory: ReactBridgeAppFactory, options?: DefineReactBridgeAppOptions): BridgeApp;
 
-export { BridgeApp, type ReactBridgeAppFactory, defineBridgeApp };
+export { BridgeApp, type DefineReactBridgeAppOptions, type ReactBridgeAppContext, type ReactBridgeAppFactory, defineBridgeApp };

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

@@ -1,5 +1,6 @@
 import { ReactElement } from 'react';
 import { BridgeApp } from './bridge-core.js';
+import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.js';
 import './context.js';
 
 /**
@@ -21,8 +22,19 @@ import './context.js';
  * 本文件零 Vue：/react 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
  */
 
-/** React 子应用工厂：接收挂载时 props 快照，返回 ReactElement（路由等由调用方自行包裹） */
-type ReactBridgeAppFactory = (props: Record<string, unknown>) => ReactElement;
+/** 工厂第二参数：挂载生命周期与路由通道（URL 同步；不混入业务 props） */
+interface ReactBridgeAppContext {
+    /** 会话代次信号（登出/换代即 aborted；异步写回前必须检查） */
+    signal?: AbortSignal;
+    /** 路由通道（宿主启用 URL 同步时存在）；配 createReactBridgeRouter 使用 */
+    routing?: BridgeChildRoute;
+}
+/** React 子应用工厂：接收挂载时 props 快照与生命周期上下文，返回 ReactElement */
+type ReactBridgeAppFactory = (props: Record<string, unknown>, ctx?: ReactBridgeAppContext) => ReactElement;
+interface DefineReactBridgeAppOptions {
+    /** 声明路由协议（URL 同步）：契约写入 routing: { protocol: 1 }（缺失时宿主启用同步即 MFU-031） */
+    routing?: boolean;
+}
 /**
  * 定义 React 子应用的桥接契约（远程 ./bridge 模块默认导出）。
  *
@@ -32,6 +44,6 @@ type ReactBridgeAppFactory = (props: Record<string, unknown>) => ReactElement;
  * export default defineBridgeApp((props) => <MemoryRouter><App {...props} /></MemoryRouter>)
  * ```
  */
-declare function defineBridgeApp(factory: ReactBridgeAppFactory): BridgeApp;
+declare function defineBridgeApp(factory: ReactBridgeAppFactory, options?: DefineReactBridgeAppOptions): BridgeApp;
 
-export { BridgeApp, type ReactBridgeAppFactory, defineBridgeApp };
+export { BridgeApp, type DefineReactBridgeAppOptions, type ReactBridgeAppContext, type ReactBridgeAppFactory, defineBridgeApp };

package/dist/bridge-app-react.js

@@ -1,6 +1,6 @@
 import {
   bridgeLifecycleError
-} from "./chunk-DH2QMM4Y.js";
+} from "./chunk-JQF7KYZF.js";
 import "./chunk-OF2JCXTZ.js";
 
 // src/bridge-app-react.ts
@@ -26,18 +26,20 @@ function CommitProbe({ children, onCommit }) {
   }, []);
   return children ?? null;
 }
-function defineBridgeApp(factory) {
+function defineBridgeApp(factory, options = {}) {
   return {
-    mount(el, props) {
+    ...options.routing ? { routing: { protocol: 1 } } : {},
+    mount(el, props, mountOptions) {
       if (entriesByEl.has(el)) {
         throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
           reason: "container-occupied"
         });
       }
       const snapshot = { ...props ?? {} };
+      const ctx = { signal: mountOptions?.signal, routing: mountOptions?.routing };
       let element;
       try {
-        element = factory(snapshot);
+        element = factory(snapshot, ctx);
       } catch (e) {
         throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
       }

package/dist/bridge-app-vue.cjs

@@ -43,7 +43,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 bridgeLifecycleError(phase, spec, cause, extra) {
   const raw = cause instanceof Error ? cause.message : String(cause ?? "unknown");
@@ -64,24 +72,61 @@ function bridgeLifecycleError(phase, spec, cause, extra) {
 
 // src/bridge-app-vue.ts
 var appsByEl = /* @__PURE__ */ new WeakMap();
-function defineBridgeApp(factory) {
+var PENDING_MARKER = { __fulgurjsPending: true };
+function entriesAborted(el) {
+  return appsByEl.get(el) !== PENDING_MARKER;
+}
+function defineBridgeApp(factory, options = {}) {
+  const attach = (el, app, mountOptions) => {
+    if (!app || typeof app.mount !== "function" || typeof app.unmount !== "function") {
+      throw new Error(
+        `defineBridgeApp \u5DE5\u5382\u8FD4\u56DE\u503C\u4E0D\u662F VueApp\uFF08\u5F53\u524D ${app === null ? "null" : typeof app}\uFF09\uFF1B\u5DE5\u5382\u5FC5\u987B\u8FD4\u56DE createApp(...) \u521B\u5EFA\u7684\u5E94\u7528\u5B9E\u4F8B\u3002`
+      );
+    }
+    try {
+      app.mount(el);
+    } catch (e) {
+      try {
+        app.unmount();
+      } catch {
+      }
+      throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
+    }
+    appsByEl.set(el, app);
+    void mountOptions;
+  };
   return {
-    mount(el, props) {
+    ...options.routing ? { routing: { protocol: 1 } } : {},
+    // 同步工厂保持同步语义（容器占用/工厂抛错同步抛，BN03/BN02 口径不变）；
+    // Promise 工厂（URL 同步初始路由准备）走异步续体：挂起期间作废（signal aborted）
+    // 则结果丢弃不落挂（迟到初始化不得复活，BN06 同源语义）。
+    mount(el, props, mountOptions) {
       if (appsByEl.has(el)) {
         throw bridgeLifecycleError("mount", "bridge", "\u540C\u4E00\u5BB9\u5668 el \u5DF2\u6302\u8F7D\u672C\u6865\u63A5\u5E94\u7528\uFF08\u5BB9\u5668\u5DF2\u88AB\u5360\u7528\uFF09\u3002", {
           reason: "container-occupied"
         });
       }
       const snapshot = { ...props ?? {} };
+      const ctx = { signal: mountOptions?.signal, routing: mountOptions?.routing };
       let app;
       try {
-        app = factory(snapshot);
-        if (!app || typeof app.mount !== "function" || typeof app.unmount !== "function") {
-          throw new Error(
-            `defineBridgeApp \u5DE5\u5382\u8FD4\u56DE\u503C\u4E0D\u662F VueApp\uFF08\u5F53\u524D ${app === null ? "null" : typeof app}\uFF09\uFF1B\u5DE5\u5382\u5FC5\u987B\u8FD4\u56DE createApp(...) \u521B\u5EFA\u7684\u5E94\u7528\u5B9E\u4F8B\u3002`
+        const produced = factory(snapshot, ctx);
+        const thenable = produced.then;
+        if (typeof thenable === "function") {
+          appsByEl.set(el, PENDING_MARKER);
+          return produced.then(
+            (resolved) => {
+              if (entriesAborted(el)) return;
+              attach(el, resolved, mountOptions);
+            },
+            (e) => {
+              if (entriesAborted(el)) return;
+              appsByEl.delete(el);
+              throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
+            }
           );
         }
-        app.mount(el);
+        app = produced;
       } catch (e) {
         if (app) {
           try {
@@ -91,12 +136,13 @@ function defineBridgeApp(factory) {
         }
         throw bridgeLifecycleError("mount", "bridge", e instanceof Error ? e : String(e));
       }
-      appsByEl.set(el, app);
+      attach(el, app, mountOptions);
     },
     unmount(el) {
       const app = appsByEl.get(el);
       if (!app) return;
       appsByEl.delete(el);
+      if (app === PENDING_MARKER) return;
       try {
         app.unmount();
       } catch (e) {

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

@@ -1,5 +1,6 @@
 import { App } from 'vue';
 import { BridgeApp } from './bridge-core.cjs';
+import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.cjs';
 import './context.cjs';
 
 /**
@@ -18,8 +19,28 @@ import './context.cjs';
  * 本文件零 React：/runtime 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
  */
 
-/** Vue 子应用工厂：接收挂载时 props 快照，返回装配完成的 VueApp */
-type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
+/** 工厂第二参数：挂载生命周期与路由通道（URL 同步；不混入业务 props） */
+interface VueBridgeAppContext {
+    /** 会话代次信号（登出/换代即 aborted；异步写回前必须检查） */
+    signal?: AbortSignal;
+    /** 路由通道（宿主启用 URL 同步时存在）；配 connectVueBridgeRouter 使用 */
+    routing?: BridgeChildRoute;
+}
+/**
+ * Vue 子应用工厂：接收挂载时 props 快照与生命周期上下文，返回装配完成的 VueApp。
+ * 允许返回 Promise<VueApp>（URL 同步子应用的初始 memory 路由准备是异步的——
+ * 必须等初始 push 落定再 app.use(router)，否则 install 的初始导航会覆盖深链位置；
+ * 见 /bridge/router/vue 的 connectVueBridgeRouter 与任务书 §1 原型结论 1）。
+ * Promise 被作废（signal aborted / 容器已换代）时结果丢弃，不落挂。
+ */
+type VueBridgeAppFactory = (props: Record<string, unknown>, ctx?: VueBridgeAppContext) => App | Promise<App>;
+interface DefineVueBridgeAppOptions {
+    /**
+     * 声明路由协议（URL 同步）：契约写入 routing: { protocol: 1 }，宿主启用 routing 时
+     * 校验；未声明而宿主启用同步 → MFU-031（不静默退回 memory 假装深链成功）。
+     */
+    routing?: boolean;
+}
 /**
  * 定义 Vue 子应用的桥接契约（远程 ./bridge 模块默认导出）。
  *
@@ -29,6 +50,6 @@ type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
  * export default defineBridgeApp((props) => { const app = createApp(App, props); app.use(router); return app })
  * ```
  */
-declare function defineBridgeApp(factory: VueBridgeAppFactory): BridgeApp;
+declare function defineBridgeApp(factory: VueBridgeAppFactory, options?: DefineVueBridgeAppOptions): BridgeApp;
 
-export { BridgeApp, type VueBridgeAppFactory, defineBridgeApp };
+export { BridgeApp, type DefineVueBridgeAppOptions, type VueBridgeAppContext, type VueBridgeAppFactory, defineBridgeApp };

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

@@ -1,5 +1,6 @@
 import { App } from 'vue';
 import { BridgeApp } from './bridge-core.js';
+import { B as BridgeChildRoute } from './bridge-router-core-BxBx-reP.js';
 import './context.js';
 
 /**
@@ -18,8 +19,28 @@ import './context.js';
  * 本文件零 React：/runtime 导入图隔离由 tests/runtime-entry-graph.test.ts 守护。
  */
 
-/** Vue 子应用工厂：接收挂载时 props 快照，返回装配完成的 VueApp */
-type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
+/** 工厂第二参数：挂载生命周期与路由通道（URL 同步；不混入业务 props） */
+interface VueBridgeAppContext {
+    /** 会话代次信号（登出/换代即 aborted；异步写回前必须检查） */
+    signal?: AbortSignal;
+    /** 路由通道（宿主启用 URL 同步时存在）；配 connectVueBridgeRouter 使用 */
+    routing?: BridgeChildRoute;
+}
+/**
+ * Vue 子应用工厂：接收挂载时 props 快照与生命周期上下文，返回装配完成的 VueApp。
+ * 允许返回 Promise<VueApp>（URL 同步子应用的初始 memory 路由准备是异步的——
+ * 必须等初始 push 落定再 app.use(router)，否则 install 的初始导航会覆盖深链位置；
+ * 见 /bridge/router/vue 的 connectVueBridgeRouter 与任务书 §1 原型结论 1）。
+ * Promise 被作废（signal aborted / 容器已换代）时结果丢弃，不落挂。
+ */
+type VueBridgeAppFactory = (props: Record<string, unknown>, ctx?: VueBridgeAppContext) => App | Promise<App>;
+interface DefineVueBridgeAppOptions {
+    /**
+     * 声明路由协议（URL 同步）：契约写入 routing: { protocol: 1 }，宿主启用 routing 时
+     * 校验；未声明而宿主启用同步 → MFU-031（不静默退回 memory 假装深链成功）。
+     */
+    routing?: boolean;
+}
 /**
  * 定义 Vue 子应用的桥接契约（远程 ./bridge 模块默认导出）。
  *
@@ -29,6 +50,6 @@ type VueBridgeAppFactory = (props: Record<string, unknown>) => App;
  * export default defineBridgeApp((props) => { const app = createApp(App, props); app.use(router); return app })
  * ```
  */
-declare function defineBridgeApp(factory: VueBridgeAppFactory): BridgeApp;
+declare function defineBridgeApp(factory: VueBridgeAppFactory, options?: DefineVueBridgeAppOptions): BridgeApp;
 
-export { BridgeApp, type VueBridgeAppFactory, defineBridgeApp };
+export { BridgeApp, type DefineVueBridgeAppOptions, type VueBridgeAppContext, type VueBridgeAppFactory, defineBridgeApp };