@fulgurjs/federation 5.7.1 → 5.9.0

package/examples/templates/showcase/vue-host/src/App.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/App.vue — 宿主根布局：顶部导航 + 守卫横幅 + RouterView。
+ * 「工单列表 / 设置」是直接跳子应用深链的菜单项：宿主 router.push 到 basePath 下的路径。
+ */
+import { RouterView, useRouter } from 'vue-router'
+import GuardBanner from './GuardBanner.vue'
+import { logNav } from './demo-log'
+
+interface MenuItem {
+  label: string
+  path: string
+}
+
+const router = useRouter()
+
+const menus: MenuItem[] = [
+  { label: '首页', path: '/' },
+  { label: '关于', path: '/about' },
+  { label: '桥接演示页', path: '/br-react' },
+  { label: '工单列表', path: '/br-react/orders' },
+  { label: '设置', path: '/br-react/settings' },
+]
+
+const handleMenu = (item: MenuItem): void => {
+  logNav('宿主菜单', `push ${item.path}`)
+  void router.push(item.path)
+}
+</script>
+
+<template>
+  <div class="demo-shell">
+    <GuardBanner />
+    <nav class="demo-nav" aria-label="宿主导航">
+      <button v-for="item in menus" :key="item.path" @click="handleMenu(item)">{{ item.label }}</button>
+    </nav>
+    <RouterView />
+  </div>
+</template>
+
+<style>
+/* 演示全局基础样式（非 scoped）：宿主与子应用同页渲染，统一观感 */
+body { font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; margin: 0; }
+.demo-shell { padding: 12px; max-width: 960px; margin: 0 auto; }
+.demo-nav { display: flex; gap: 8px; padding: 8px 0; border-bottom: 1px solid #ddd; margin-bottom: 12px; flex-wrap: wrap; }
+.demo-nav button { cursor: pointer; }
+.demo-row { display: flex; gap: 8px; align-items: center; margin: 8px 0; flex-wrap: wrap; }
+.demo-muted { color: #666; font-size: 13px; }
+code { background: #f4f4f5; padding: 1px 4px; border-radius: 3px; }
+</style>

package/examples/templates/showcase/vue-host/src/GuardBanner.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/GuardBanner.vue — 宿主守卫确认横幅（异步 beforeEach 等待用户选择）。
+ * 「取消」= Vue Router 导航失败 → 通道收到 cancelled，URL/子应用位置保持不变。
+ */
+import { guardPending, resolveGuard } from './guard'
+</script>
+
+<template>
+  <div v-if="guardPending" class="demo-guard" role="alertdialog" aria-label="宿主守卫确认">
+    <span>宿主守卫：是否允许前往 <code>{{ guardPending.to }}</code>？</span>
+    <button @click="resolveGuard(true)">继续</button>
+    <button @click="resolveGuard(false)">取消</button>
+  </div>
+</template>
+
+<style scoped>
+.demo-guard {
+  display: flex; gap: 12px; align-items: center;
+  background: #fff7e6; border: 1px solid #f0c36d;
+  padding: 8px 12px; margin-bottom: 12px; border-radius: 4px;
+}
+.demo-guard button { cursor: pointer; }
+</style>

package/examples/templates/showcase/vue-host/src/ObsPanel.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/ObsPanel.vue — URL 同步观测台（实时更新）。
+ * 展示：宿主当前 URL（location.href）、子应用逻辑位置、history.length、
+ * 子应用挂载计数、最近 10 条导航事件（带来源标注）。
+ */
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+import { navLog, mountCount } from './demo-log'
+import { BRIDGE_BASE_PATH } from './routing'
+
+const route = useRoute()
+
+const hostHref = ref(window.location.href)
+const historyLength = ref(window.history.length)
+
+const childLocation = computed(() => {
+  const inPrefix = route.path === BRIDGE_BASE_PATH || route.path.startsWith(`${BRIDGE_BASE_PATH}/`)
+  if (!inPrefix) return route.fullPath
+  return route.fullPath.slice(BRIDGE_BASE_PATH.length) || '/'
+})
+
+const refresh = (): void => {
+  hostHref.value = window.location.href
+  historyLength.value = window.history.length
+}
+
+watch(() => route.fullPath, refresh)
+
+const handlePop = (): void => { refresh() }
+onMounted(() => window.addEventListener('popstate', handlePop))
+onUnmounted(() => window.removeEventListener('popstate', handlePop))
+</script>
+
+<template>
+  <section class="demo-obs">
+    <h3 class="demo-obs-title">URL 同步观测台</h3>
+    <p>宿主当前 URL：<code data-demo-host-url>{{ hostHref }}</code></p>
+    <p>子应用逻辑位置：<code data-demo-child-location>{{ childLocation }}</code></p>
+    <p>
+      history.length：<code data-demo-history-length>{{ historyLength }}</code>
+      ｜子应用 mount 次数：<code data-demo-mount-count>{{ mountCount }}</code>（路由切换应恒为 1）
+    </p>
+    <h4>最近导航事件（≤10 条，新在下）</h4>
+    <ol class="demo-obs-log">
+      <li v-for="entry in navLog" :key="entry.id">
+        [{{ entry.time }}] {{ entry.source }} — {{ entry.detail }}
+      </li>
+      <li v-if="navLog.length === 0" class="demo-muted">（暂无事件）</li>
+    </ol>
+  </section>
+</template>
+
+<style scoped>
+.demo-obs { border: 1px solid #d0e7ff; background: #f5faff; padding: 8px 12px; margin: 12px 0; border-radius: 4px; }
+.demo-obs-title { margin: 6px 0; }
+.demo-obs p { margin: 4px 0; }
+h4 { margin: 6px 0 2px; }
+.demo-obs-log { margin: 4px 0; padding-left: 20px; font-size: 13px; }
+</style>

package/examples/templates/showcase/vue-host/src/demo-log.ts

@@ -0,0 +1,49 @@
+/**
+ * examples/templates/showcase/vue-host/src/demo-log.ts — URL 同步观测台数据源（模块级单例，跨宿主页面存活）。
+ * 事件来源标注：宿主菜单 / 深链粘贴 / 子应用 Link / 子应用 push·replace / 子应用 go /
+ * 子应用初始化 / 浏览器前进后退 / 宿主守卫。最多保留 10 条。
+ */
+import { ref } from 'vue'
+
+export interface NavLogEntry {
+  id: number
+  time: string
+  source: string
+  detail: string
+}
+
+export type DemoChildEvent =
+  | { type: 'mounted'; mountCount: number }
+  | { type: 'nav'; source: string; action: string; detail: string }
+
+export const navLog = ref<NavLogEntry[]>([])
+export const mountCount = ref(0)
+
+let nextId = 1
+
+export function logNav(source: string, detail: string): void {
+  const entry: NavLogEntry = { id: nextId, time: new Date().toLocaleTimeString('zh-CN', { hour12: false }), source, detail }
+  nextId += 1
+  navLog.value = [...navLog.value, entry].slice(-10)
+}
+
+/** appProps 稳定回调：子应用经它上报挂载计数与导航事件 */
+export function handleChildEvent(event: DemoChildEvent): void {
+  if (event.type === 'mounted') {
+    mountCount.value = event.mountCount
+    logNav('子应用', `mount #${event.mountCount}`)
+    return
+  }
+  logNav(event.source, `${event.action} ${event.detail}`)
+}
+
+let popInstalled = false
+
+/** 浏览器前进后退（POP）在 main.ts 安装一次；push/replace 由各自来源显式标注 */
+export function installPopStateLogger(): void {
+  if (popInstalled) return
+  popInstalled = true
+  window.addEventListener('popstate', () => {
+    logNav('浏览器前进后退', window.location.pathname + window.location.search)
+  })
+}

package/examples/templates/showcase/vue-host/src/fulgurjs/types/react-remote.d/_paths.d.ts

@@ -0,0 +1,4 @@
+// 精确轨启用方法（把下面片段合入宿主 tsconfig 的 compilerOptions；baseUrl 指向本 tsconfig 所在目录）：
+//   "paths": { "react-remote/*": ["src/fulgurjs/types/react-remote.d/*"] }
+// 说明：零配置轨（react-remote.d.ts 的 ambient 声明）可解析但导出为宽松类型；
+// 配置 paths 后同形态导入解析到本目录的转发模块，获得远程源码级类型精度。

package/examples/templates/showcase/vue-host/src/fulgurjs/types/react-remote.d/bridge.ts

@@ -0,0 +1,3 @@
+// 自动生成（精确轨）：经 tsconfig paths 解析到本文件后获得源码级类型
+export * from "../../../../../react-remote/src/bridge"
+export { default } from "../../../../../react-remote/src/bridge"

package/examples/templates/showcase/vue-host/src/fulgurjs/types/react-remote.d.ts

@@ -0,0 +1,7 @@
+// 自动生成：fulgurjs-federation dev 类型直连（remote: react-remote，mode: source）
+// 重新生成：重启 host dev server
+
+declare module "react-remote/bridge" {
+  const __fg_default: any
+  export default __fg_default
+}

package/examples/templates/showcase/vue-host/src/guard.ts

@@ -0,0 +1,47 @@
+/**
+ * examples/templates/showcase/vue-host/src/guard.ts — 宿主真实权限守卫（Vue Router 4）。
+ * /br-react/locked 需人工确认：异步 beforeEach 返回 Promise → Vue Router 等待用户选择；
+ * 返回 false = 真实取消（NavigationFailure）→ 桥接通道收到 cancelled，URL/历史/子应用位置
+ * 全部保持最后确认状态，插件绝不自动重试。
+ */
+import { ref } from 'vue'
+import type { Router } from 'vue-router'
+import { logNav } from './demo-log'
+import { BRIDGE_BASE_PATH } from './routing'
+
+export interface GuardPending {
+  to: string
+}
+
+export const guardPending = ref<GuardPending | null>(null)
+let resolver: ((allow: boolean) => void) | undefined
+
+/** 守卫横幅按钮回调：放行（true）或取消（false） */
+export function resolveGuard(allow: boolean): void {
+  const current = resolver
+  resolver = undefined
+  current?.(allow)
+}
+
+/** 作废当前待确认导航（新导航开始时旧导航已被 vue-router 取消，确认横幅必须随之撤下） */
+function invalidatePending(): void {
+  const current = resolver
+  if (!current) return
+  resolver = undefined
+  guardPending.value = null
+  current(false)
+}
+
+export function installGuard(router: Router): void {
+  router.beforeEach(async (to) => {
+    // 任何新导航开始都作废旧待确认（含非 locked 目标，如守卫等待期间的 go(1)）
+    invalidatePending()
+    if (!to.path.startsWith(`${BRIDGE_BASE_PATH}/locked`)) return true
+    guardPending.value = { to: to.fullPath }
+    logNav('宿主守卫', `拦截 → ${to.fullPath}（等待确认）`)
+    const allow = await new Promise<boolean>((resolve) => { resolver = resolve })
+    guardPending.value = null
+    logNav('宿主守卫', allow ? `继续 → ${to.fullPath}` : `取消 → ${to.fullPath}（URL/历史/子应用位置保持不变）`)
+    return allow
+  })
+}

package/examples/templates/showcase/vue-host/src/main.ts

@@ -0,0 +1,30 @@
+/**
+ * examples/templates/showcase/vue-host/src/main.ts — 宿主入口。
+ * 宿主 Router 是浏览器历史唯一写入方；catch-all 路由（/br-react/* 单条记录渲染同一组件）
+ * 保证子应用内部导航不重挂宿主组件。守卫与 POP 日志在此一次性安装。
+ */
+import { createApp } from 'vue'
+import { createRouter, createWebHistory } from 'vue-router'
+import App from './App.vue'
+import HomePage from './pages/HomePage.vue'
+import AboutPage from './pages/AboutPage.vue'
+import BridgeReactPage from './pages/BridgeReactPage.vue'
+import { initBridgeRouting } from './routing'
+import { installGuard } from './guard'
+import { installPopStateLogger } from './demo-log'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: HomePage },
+    { path: '/about', component: AboutPage },
+    // catch-all：子应用挂载在 /br-react 前缀下，内部导航全部命中同一条路由记录
+    { path: '/br-react/:pathMatch(.*)*', component: BridgeReactPage },
+  ],
+})
+
+initBridgeRouting(router)
+installGuard(router)
+installPopStateLogger()
+
+createApp(App).use(router).mount('#app')

package/examples/templates/showcase/vue-host/src/pages/AboutPage.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/pages/AboutPage.vue — 关于页：场景与工程说明。
+ */
+</script>
+
+<template>
+  <section>
+    <h2>关于</h2>
+    <p>examples/templates/showcase：一个 pnpm 模板中的 4 个应用 —— react-remote(5333)、vue-host(5334)、vue-remote(5335)、react-host(5336)。</p>
+    <ul>
+      <li>vue-host（:5334）套 react-remote（:5333），桥接前缀 basePath=/br-react</li>
+      <li>react-host（:5336）套 vue-remote（:5335），桥接前缀 basePath=/br-vue</li>
+    </ul>
+    <p>API 与源码对照、演示操作清单见 examples/templates/showcase/README.md。</p>
+  </section>
+</template>

package/examples/templates/showcase/vue-host/src/pages/BridgeReactPage.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/pages/BridgeReactPage.vue — 桥接演示页（Vue 宿主 × React 子应用）。
+ * createVueBridgeApp + routing prop（basePath=/br-react + createVueBridgeNavigation 端口）；
+ * catch-all 路由保证子应用内部导航不重挂本组件；appProps 携带稳定回调供子应用上报事件。
+ */
+import { ref } from 'vue'
+import { useRouter } from 'vue-router'
+import { createVueBridgeApp } from '@fulgurjs/federation/bridge/vue'
+import { BRIDGE_BASE_PATH, getBridgeRouting } from '../routing'
+import { handleChildEvent, logNav } from '../demo-log'
+import ObsPanel from '../ObsPanel.vue'
+
+const RemoteReactBridge = createVueBridgeApp('react-remote/bridge', { retries: 1 })
+const routing = getBridgeRouting()
+const appProps = { onChildEvent: handleChildEvent }
+
+const router = useRouter()
+const deepLink = ref(`${window.location.origin}${BRIDGE_BASE_PATH}/orders?q=网络&page=2`)
+const deepLinkError = ref('')
+
+const handleDeepLink = (): void => {
+  const raw = deepLink.value.trim()
+  let path = raw
+  if (/^https?:\/\//i.test(raw)) {
+    try {
+      const parsed = new URL(raw)
+      path = parsed.pathname + parsed.search
+    } catch {
+      deepLinkError.value = 'URL 无法解析'
+      return
+    }
+  }
+  if (path !== BRIDGE_BASE_PATH && !path.startsWith(`${BRIDGE_BASE_PATH}/`)) {
+    deepLinkError.value = `路径必须位于 ${BRIDGE_BASE_PATH} 前缀下`
+    return
+  }
+  deepLinkError.value = ''
+  logNav('深链粘贴', `push ${path}`)
+  void router.push(path)
+}
+</script>
+
+<template>
+  <section>
+    <h2>桥接演示：Vue 宿主 × React 子应用（URL 同步）</h2>
+    <p class="demo-muted">
+      子应用挂载在宿主 <code>{{ BRIDGE_BASE_PATH }}</code> 前缀下；观测台实时展示宿主 URL、
+      子应用逻辑位置、history.length 与导航事件来源。
+    </p>
+    <ObsPanel />
+    <section class="demo-deeplink">
+      <h3>深链粘贴框（push 侧「刷新直达」复现）</h3>
+      <div class="demo-row">
+        <input v-model="deepLink" class="demo-deeplink-input" aria-label="深链粘贴框" />
+        <button @click="handleDeepLink">push 复现直达</button>
+      </div>
+      <p v-if="deepLinkError !== ''" class="demo-deeplink-error">{{ deepLinkError }}</p>
+      <p class="demo-muted">粘贴带中文 query 的完整 URL 后点击按钮 = 复制地址栏在新窗口打开前的 push 侧动作。</p>
+    </section>
+    <section class="demo-bridge-area" data-demo-bridge-area>
+      <RemoteReactBridge :routing="routing" :app-props="appProps" />
+    </section>
+  </section>
+</template>
+
+<style scoped>
+.demo-deeplink { border: 1px dashed #bbb; padding: 8px 12px; margin: 12px 0; border-radius: 4px; }
+.demo-deeplink h3 { margin: 6px 0; }
+.demo-deeplink-input { flex: 1 1 320px; }
+.demo-deeplink button { cursor: pointer; }
+.demo-deeplink-error { color: #c0392b; margin: 4px 0; }
+.demo-bridge-area { border: 2px solid #61dafb; padding: 8px 12px; margin: 12px 0; border-radius: 4px; }
+</style>

package/examples/templates/showcase/vue-host/src/pages/HomePage.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-host/src/pages/HomePage.vue — 宿主首页。
+ */
+</script>
+
+<template>
+  <section>
+    <h2>首页</h2>
+    <p>双向桥接 URL 同步演示：宿主页级路由（首页 / 关于 / 桥接演示页）+ 子应用受控 memory 路由。</p>
+    <p>顶部菜单「桥接演示页 / 工单列表 / 设置」经宿主 router.push 直达子应用深链。</p>
+  </section>
+</template>

package/examples/templates/showcase/vue-host/src/routing.ts

@@ -0,0 +1,31 @@
+/**
+ * examples/templates/showcase/vue-host/src/routing.ts — 桥接宿主导航端口（模块级单例）。
+ * main.ts 组装宿主 router 后初始化一次：createVueBridgeNavigation(router)——
+ * Vue Router fullPath 已剥离 history base，逻辑路径无需再处理部署前缀；
+ * 端口引用保持稳定 → routing 键不变，宿主不重挂、不重复订阅。
+ */
+import type { Router } from 'vue-router'
+import { createVueBridgeNavigation } from '@fulgurjs/federation/bridge/router/vue'
+
+export const BRIDGE_BASE_PATH = '/br-react'
+
+/**
+ * 宿主 routing prop 结构（BridgeHostRouting）。
+ * 注：5.4.1 发布包未从 /bridge/router/vue 导出 BridgeHostRouting 类型（README §8.3 示例
+ * 与发布包类型面不一致，已知问题），这里用端口函数返回值结构化等价替代。
+ */
+interface BridgeHostRoutingLike {
+  basePath: string
+  navigation: ReturnType<typeof createVueBridgeNavigation>
+}
+
+let routing: BridgeHostRoutingLike | undefined
+
+export function initBridgeRouting(router: Router): void {
+  routing = { basePath: BRIDGE_BASE_PATH, navigation: createVueBridgeNavigation(router) }
+}
+
+export function getBridgeRouting(): BridgeHostRoutingLike {
+  if (!routing) throw new Error('桥接路由端口未初始化：请先在 main.ts 调用 initBridgeRouting(router)')
+  return routing
+}

package/examples/templates/showcase/vue-host/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "fulgurjs.config.ts", "vite.config.ts"]
+}

package/examples/templates/showcase/vue-remote/fulgurjs.config.ts

@@ -0,0 +1,17 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * Vue 子应用联邦配置（examples/templates/showcase/vue-remote，端口 5335）。
+ * 只暴露 ./bridge 桥接契约；宿主（react-host）启用 URL 同步后经它加载。
+ * vue-router 是子应用自己的受控路由库（不进 shared），由消费方自装。
+ */
+export default {
+  name: 'vue-remote',
+  filename: 'fulgurjs-remoteEntry.js',
+  exposes: {
+    './bridge': './src/bridge.ts',
+  },
+  shared: {
+    vue: { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/templates/showcase/vue-remote/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:," />
+    <title>vue-remote（桥接 URL 同步子应用，5335）</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/examples/templates/showcase/vue-remote/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "fulgurjs-demo-bridge-vue-remote",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5335 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5335 --strictPort",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "5.8.0",
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.5",
+    "vue-tsc": "^2.2.0"
+  }
+}

package/examples/templates/showcase/vue-remote/src/ChildLayout.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+/**
+ * examples/templates/showcase/vue-remote/src/ChildLayout.vue — 子应用根布局：导航演示按钮 + RouterView。
+ * push/replace 走被 connectVueBridgeRouter 接管的 router.push/replace（经通道同步宿主 URL）；
+ * go 委托宿主浏览器历史，不创建第二条独立历史。
+ */
+import { RouterView, useRouter } from 'vue-router'
+import { getMountCount, reportNav } from './child-bus'
+
+const router = useRouter()
+
+const handlePushDemo = (): void => {
+  const target = router.resolve('/orders?q=演示&page=2').fullPath
+  reportNav('子应用 push/replace', 'push', target)
+  void router.push(target)
+}
+
+const handleReplaceDemo = (): void => {
+  reportNav('子应用 push/replace', 'replace', '/settings')
+  void router.replace('/settings')
+}
+
+const handleGoBack = (): void => {
+  reportNav('子应用 go', 'go', '-1')
+  router.go(-1)
+}
+
+const handleGoForward = (): void => {
+  reportNav('子应用 go', 'go', '1')
+  router.go(1)
+}
+</script>
+
+<template>
+  <section class="demo-child">
+    <p class="demo-child-title">
+      <strong>Vue 子应用</strong>（受控 memory 路由）· 本会话挂载次数：{{ getMountCount() }}
+    </p>
+    <div class="demo-row">
+      <button @click="handlePushDemo">子应用 push /orders?q=演示&amp;page=2</button>
+      <button @click="handleReplaceDemo">子应用 replace /settings</button>
+      <button @click="handleGoBack">子应用 go(-1)</button>
+      <button @click="handleGoForward">子应用 go(1)</button>
+    </div>
+    <RouterView />
+  </section>
+</template>
+
+<style scoped>
+.demo-child { border-top: 1px dashed #ccc; margin-top: 8px; padding-top: 8px; }
+.demo-child-title { margin: 4px 0; }
+.demo-row { display: flex; gap: 8px; align-items: center; margin: 8px 0; flex-wrap: wrap; }
+.demo-row button { cursor: pointer; }
+</style>

package/examples/templates/showcase/vue-remote/src/bridge.ts

@@ -0,0 +1,48 @@
+/**
+ * examples/templates/showcase/vue-remote/src/bridge.ts — Vue 子应用桥接契约（exposes './bridge'）。
+ * defineBridgeApp(factory, { routing: true }) 声明路由协议（缺失时宿主启用同步即 MFU-031 占位）。
+ * 受控路由 = createMemoryHistory + connectVueBridgeRouter；工厂为异步形态——
+ * 必须 await conn.ready 后再 app.use(router)（初始 push 落定后再 install）。
+ */
+import { createApp } from 'vue'
+import { createMemoryHistory, createRouter, type RouteRecordRaw } from 'vue-router'
+import { defineBridgeApp } from '@fulgurjs/federation/runtime'
+import { connectVueBridgeRouter } from '@fulgurjs/federation/bridge/router/vue'
+import ChildLayout from './ChildLayout.vue'
+import OrderList from './pages/OrderList.vue'
+import OrderDetail from './pages/OrderDetail.vue'
+import Settings from './pages/Settings.vue'
+import Locked from './pages/Locked.vue'
+import { bindReporter, reportNav } from './child-bus'
+
+const routes: RouteRecordRaw[] = [
+  // 根路径以 replace 规范化到 /orders（不产生额外历史条目）
+  { path: '/', redirect: '/orders' },
+  { path: '/orders', component: OrderList },
+  { path: '/orders/:id', component: OrderDetail },
+  { path: '/settings', component: Settings },
+  { path: '/locked', component: Locked },
+]
+
+export default defineBridgeApp(async (props, ctx) => {
+  if (!ctx?.routing) {
+    throw new Error('本契约需要宿主启用 URL 同步（mount 第三参数 routing）')
+  }
+  bindReporter(props)
+  const init = ctx.routing.getLocation()
+  const initPath = init.pathname + init.search + init.hash
+  const router = createRouter({ history: createMemoryHistory(), routes })
+  const conn = connectVueBridgeRouter(ctx.routing, router, { signal: ctx.signal })
+  await conn.ready
+  const currentPath = router.currentRoute.value.fullPath
+  reportNav(
+    '子应用初始化',
+    'init',
+    currentPath !== initPath
+      ? `根路径规范化 replace → ${currentPath}（无新增历史条目）`
+      : `初始位置 → ${currentPath}（与宿主深链一致）`,
+  )
+  const app = createApp(ChildLayout, props)
+  app.use(router)
+  return app
+}, { routing: true })

package/examples/templates/showcase/vue-remote/src/child-bus.ts

@@ -0,0 +1,32 @@
+/**
+ * examples/templates/showcase/vue-remote/src/child-bus.ts — 子应用 → 宿主观测台上报总线。
+ * 宿主经 appProps 传入稳定回调 onChildEvent；本模块持有该引用并维护挂载计数。
+ * 单页单实例假设：同一宿主页同时只挂一个本子应用实例（路由同步前缀互斥的常规形态）。
+ */
+export type DemoChildNavAction = 'push' | 'replace' | 'go' | 'init'
+
+export type DemoChildEvent =
+  | { type: 'mounted'; mountCount: number }
+  | { type: 'nav'; source: string; action: DemoChildNavAction; detail: string }
+
+export type DemoChildReporter = (event: DemoChildEvent) => void
+
+const bus: { report: DemoChildReporter | undefined } = { report: undefined }
+let mountCount = 0
+
+/** 桥接工厂内调用：从 props 快照中取出宿主回调，并上报本次挂载计数 */
+export function bindReporter(props: Record<string, unknown> | undefined): void {
+  const candidate = (props as { onChildEvent?: DemoChildReporter } | undefined)?.onChildEvent
+  bus.report = typeof candidate === 'function' ? candidate : undefined
+  mountCount += 1
+  bus.report?.({ type: 'mounted', mountCount })
+}
+
+/** 导航来源上报（子应用 Link / 子应用 push·replace / 子应用 go / 子应用初始化） */
+export function reportNav(source: string, action: DemoChildNavAction, detail: string): void {
+  bus.report?.({ type: 'nav', source, action, detail })
+}
+
+export function getMountCount(): number {
+  return mountCount
+}

package/examples/templates/showcase/vue-remote/src/main.ts

@@ -0,0 +1,16 @@
+/**
+ * examples/templates/showcase/vue-remote/src/main.ts — 独立运行入口（仅 dev 占位）。
+ * 子应用真实能力经 exposes './bridge' 被宿主加载；直开本页仅作 dev server 健康检查。
+ */
+import { createApp, h } from 'vue'
+
+createApp({
+  render: () =>
+    h('div', { style: "font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; padding: 24px" }, [
+      h('h1', null, 'vue-remote（联邦子应用，5335）'),
+      h('p', null, '本应用通过 expose ./bridge（defineBridgeApp + routing 协议）被宿主加载。'),
+      h('p', null, [
+        h('a', { href: 'http://localhost:5336/br-vue/orders' }, '打开 React 宿主桥接页（5336）'),
+      ]),
+    ]),
+}).mount('#app')