@fulgurjs/federation 5.8.0 → 5.9.1

package/examples/templates/showcase/react-remote/src/bridge.tsx

@@ -0,0 +1,62 @@
+/**
+ * examples/templates/showcase/react-remote/src/bridge.tsx — React 子应用桥接契约（exposes './bridge'）。
+ * defineBridgeApp(factory, { routing: true }) 声明路由协议（缺失时宿主启用同步即 MFU-031 占位）。
+ * 受控路由 = createReactBridgeRouter（memory data router）：工厂返回 RouterProvider 元素；
+ * 根路径 / 经 loader redirect 规范化到 /orders，由插件以 replace 同步宿主（无新增历史条目）。
+ */
+import type { ReactElement } from 'react'
+import { redirect } from 'react-router-dom'
+import { defineBridgeApp } from '@fulgurjs/federation/react'
+import { createReactBridgeRouter } from '@fulgurjs/federation/bridge/router/react'
+import ChildLayout from './ChildLayout'
+import OrderList from './pages/OrderList'
+import OrderDetail from './pages/OrderDetail'
+import Settings from './pages/Settings'
+import Locked from './pages/Locked'
+import { bindReporter, reportNav } from './child-bus'
+
+/** 初始位置读取用的最小 data router 结构面（避免耦合 react-router 内部类型路径） */
+interface MemoryRouterProbe {
+  state: { location: { pathname: string; search: string; hash: string } }
+}
+
+const routes = [
+  { path: '/', loader: () => redirect('/orders') },
+  {
+    element: <ChildLayout />,
+    children: [
+      { path: '/orders', element: <OrderList /> },
+      { path: '/orders/:id', element: <OrderDetail /> },
+      { path: '/settings', element: <Settings /> },
+      { path: '/locked', element: <Locked /> },
+    ],
+  },
+]
+
+export default defineBridgeApp((props, ctx) => {
+  if (!ctx?.routing) {
+    throw new Error('本契约需要宿主启用 URL 同步（mount 第三参数 routing）')
+  }
+  bindReporter(props)
+  const init = ctx.routing.getLocation()
+  const conn = createReactBridgeRouter(ctx.routing, routes, { signal: ctx.signal })
+  reportInitRedirect(conn.element as ReactElement<{ router?: MemoryRouterProbe }>, init.pathname + init.search + init.hash)
+  return conn.element
+}, { routing: true })
+
+/** 初始位置上报：createMemoryRouter 同步初始化，'/' 的 loader 重定向在微任务内落定，
+ * 下一个宏任务读取即为最终初始位置（订阅式一次性上报会在首个用户导航时才误触发）。 */
+function reportInitRedirect(element: ReactElement<{ router?: MemoryRouterProbe }>, initPath: string): void {
+  const router = element.props.router
+  if (!router) return
+  setTimeout(() => {
+    const current = router.state.location.pathname + router.state.location.search + router.state.location.hash
+    reportNav(
+      '子应用初始化',
+      'init',
+      current !== initPath
+        ? `根路径规范化 replace → ${current}（无新增历史条目）`
+        : `初始位置 → ${current}（与宿主深链一致）`,
+    )
+  }, 0)
+}

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

@@ -0,0 +1,32 @@
+/**
+ * examples/templates/showcase/react-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/react-remote/src/main.tsx

@@ -0,0 +1,18 @@
+/**
+ * examples/templates/showcase/react-remote/src/main.tsx — 独立运行入口（仅 dev 占位）。
+ * 子应用真实能力经 exposes './bridge' 被宿主加载；直开本页仅作 dev server 健康检查。
+ */
+import { createRoot } from 'react-dom/client'
+import type { ReactElement } from 'react'
+
+function Standalone(): ReactElement {
+  return (
+    <div style={{ fontFamily: "'PingFang SC', 'Microsoft YaHei', sans-serif", padding: 24 }}>
+      <h1>react-remote（联邦子应用，5333）</h1>
+      <p>本应用通过 expose ./bridge（defineBridgeApp + routing 协议）被宿主加载。</p>
+      <p>请打开 Vue 宿主桥接页：<a href="http://localhost:5334/br-react/orders">http://localhost:5334/br-react/orders</a></p>
+    </div>
+  )
+}
+
+createRoot(document.getElementById('root')!).render(<Standalone />)

package/examples/templates/showcase/react-remote/src/pages/Locked.tsx

@@ -0,0 +1,23 @@
+/**
+ * examples/templates/showcase/react-remote/src/pages/Locked.tsx — 锁定页（守卫放行后才可见）。
+ * 前往本页的导航会被宿主守卫（Vue：异步 beforeEach；React：useBlocker）拦截，等待「继续/取消」。
+ */
+import type { ReactElement } from 'react'
+import { Link } from 'react-router-dom'
+import { reportNav } from '../child-bus'
+
+export default function Locked(): ReactElement {
+  const handleBack = (): void => {
+    reportNav('子应用 Link', 'push', '/orders')
+  }
+
+  return (
+    <section style={{ padding: '8px 0' }}>
+      <h3 style={{ margin: '4px 0' }}>锁定页（子应用路由 /locked）</h3>
+      <p style={{ margin: '4px 0' }}>你能看到本页，说明宿主守卫选择了「继续」。</p>
+      <p style={{ margin: '4px 0' }}>
+        <Link to="/orders" onClick={handleBack}>回工单列表</Link>
+      </p>
+    </section>
+  )
+}

package/examples/templates/showcase/react-remote/src/pages/OrderDetail.tsx

@@ -0,0 +1,36 @@
+/**
+ * examples/templates/showcase/react-remote/src/pages/OrderDetail.tsx — 工单详情页（路径参数 /orders/:id）。
+ * 「返回列表」走 go(-1)（委托宿主浏览器历史）；「回列表」走 push（经通道写宿主 URL）。
+ */
+import type { ReactElement } from 'react'
+import { useLocation, useNavigate, useParams } from 'react-router-dom'
+import { reportNav } from '../child-bus'
+
+export default function OrderDetail(): ReactElement {
+  const params = useParams()
+  const location = useLocation()
+  const navigate = useNavigate()
+  const id = params.id ?? ''
+  const queryEcho = location.search === '' ? '（无）' : location.search
+
+  const handleBack = (): void => {
+    reportNav('子应用 go', 'go', '-1')
+    navigate(-1)
+  }
+
+  const handleLinkBack = (): void => {
+    reportNav('子应用 Link', 'push', '/orders')
+    void navigate('/orders')
+  }
+
+  return (
+    <section style={{ padding: '8px 0' }}>
+      <h3 style={{ margin: '4px 0' }}>工单详情（子应用路由 /orders/:id）</h3>
+      <p style={{ margin: '4px 0' }}>工单 ID：<code>{id}</code>；query 回显：<code>{queryEcho}</code></p>
+      <div style={{ display: 'flex', gap: 8, margin: '8px 0', flexWrap: 'wrap' }}>
+        <button onClick={handleBack}>返回列表（go(-1)）</button>
+        <button onClick={handleLinkBack}>回列表（push /orders）</button>
+      </div>
+    </section>
+  )
+}

package/examples/templates/showcase/react-remote/src/pages/OrderList.tsx

@@ -0,0 +1,110 @@
+/**
+ * examples/templates/showcase/react-remote/src/pages/OrderList.tsx — 工单列表页（筛选 + 分页）。
+ * 筛选关键词与页码写入子应用路由 query（q=xxx&page=n，中文可输入），
+ * 经桥接通道同步到宿主 URL；跳详情再返回时组件重建、状态从 query 还原。
+ */
+import { useMemo, useState } from 'react'
+import type { ChangeEvent, ReactElement } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { reportNav } from '../child-bus'
+
+interface OrderItem {
+  id: number
+  title: string
+}
+
+const ORDERS: OrderItem[] = [
+  { id: 1, title: '登录异常排查' },
+  { id: 2, title: '网络抖动投诉' },
+  { id: 3, title: '权限配置变更' },
+  { id: 4, title: '数据导出失败' },
+  { id: 5, title: '消息推送延迟' },
+  { id: 6, title: '账单核对差异' },
+  { id: 7, title: '接口超时告警' },
+  { id: 8, title: '存储扩容申请' },
+]
+const PAGE_SIZE = 3
+
+export default function OrderList(): ReactElement {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const search = new URLSearchParams(location.search)
+  const q = search.get('q') ?? ''
+  const pageRaw = Number.parseInt(search.get('page') ?? '1', 10)
+  const page = Number.isFinite(pageRaw) && pageRaw > 0 ? pageRaw : 1
+  const [qInput, setQInput] = useState(q)
+
+  const filtered = useMemo(
+    () => (q === '' ? ORDERS : ORDERS.filter((item) => item.title.includes(q))),
+    [q],
+  )
+  const totalPages = Math.max(1, Math.ceil(filtered.length / PAGE_SIZE))
+  const pageItems = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)
+
+  const buildTarget = (qValue: string, pageValue: number): string =>
+    `/orders?page=${pageValue}${qValue === '' ? '' : `&q=${encodeURIComponent(qValue)}`}`
+
+  const handleQInputChange = (event: ChangeEvent<HTMLInputElement>): void => {
+    setQInput(event.target.value)
+  }
+
+  const handleSearch = (): void => {
+    const target = buildTarget(qInput.trim(), 1)
+    reportNav('子应用 push/replace', 'push', target)
+    void navigate(target)
+  }
+
+  const handlePageStep = (delta: number): void => {
+    const next = Math.min(totalPages, Math.max(1, page + delta))
+    if (next === page) return
+    const target = buildTarget(q, next)
+    reportNav('子应用 push/replace', 'push', target)
+    void navigate(target)
+  }
+
+  const handleOpenDetail = (item: OrderItem): void => {
+    reportNav('子应用 Link', 'push', `/orders/${item.id}?src=row`)
+    void navigate(`/orders/${item.id}?src=row`)
+  }
+
+  const handleGoSettings = (): void => {
+    reportNav('子应用 Link', 'push', '/settings')
+    void navigate('/settings')
+  }
+
+  const handleGoLocked = (): void => {
+    reportNav('子应用 Link', 'push', '/locked')
+    void navigate('/locked')
+  }
+
+  return (
+    <section style={{ padding: '8px 0' }}>
+      <h3 style={{ margin: '4px 0' }}>工单列表（子应用路由 /orders）</h3>
+      <p style={{ color: '#666', fontSize: 13, margin: '4px 0' }}>
+        当前筛选：q={q === '' ? '（空）' : q}，页码：{page}/{totalPages}（来自子应用路由 query）
+      </p>
+      <div style={{ display: 'flex', gap: 8, margin: '8px 0', flexWrap: 'wrap' }}>
+        <input value={qInput} onChange={handleQInputChange} placeholder="输入筛选关键词（支持中文，如：网络）" aria-label="筛选关键词" />
+        <button onClick={handleSearch}>筛选（push ?q=&amp;page=1）</button>
+      </div>
+      <ul style={{ listStyle: 'none', padding: 0, margin: '8px 0' }}>
+        {pageItems.map((item) => (
+          <li key={item.id} style={{ display: 'flex', gap: 8, alignItems: 'center', padding: '4px 0' }}>
+            <span>#{item.id} {item.title}</span>
+            <button onClick={() => handleOpenDetail(item)}>查看详情</button>
+          </li>
+        ))}
+        {pageItems.length === 0 && <li style={{ color: '#666' }}>无匹配工单</li>}
+      </ul>
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center', margin: '8px 0' }}>
+        <button disabled={page <= 1} onClick={() => handlePageStep(-1)}>上一页</button>
+        <span>第 {page} / {totalPages} 页</span>
+        <button disabled={page >= totalPages} onClick={() => handlePageStep(1)}>下一页</button>
+      </div>
+      <div style={{ display: 'flex', gap: 8, margin: '8px 0', flexWrap: 'wrap' }}>
+        <button onClick={handleGoSettings}>前往设置页</button>
+        <button onClick={handleGoLocked}>锁定页（触发宿主守卫）</button>
+      </div>
+    </section>
+  )
+}

package/examples/templates/showcase/react-remote/src/pages/Settings.tsx

@@ -0,0 +1,50 @@
+/**
+ * examples/templates/showcase/react-remote/src/pages/Settings.tsx — 设置页（本地状态表单，状态刻意不进 URL）。
+ * 修改直写模块级 settings-store（write-through）：路由往返后仍保留 → 佐证子应用 store 未重建。
+ */
+import { useState } from 'react'
+import type { ChangeEvent, ReactElement } from 'react'
+import { settingsState } from '../settings-store'
+
+export default function Settings(): ReactElement {
+  const [nickname, setNickname] = useState(settingsState.nickname)
+  const [notifyEnabled, setNotifyEnabled] = useState(settingsState.notifyEnabled)
+  const [theme, setTheme] = useState(settingsState.theme)
+
+  const handleNicknameChange = (event: ChangeEvent<HTMLInputElement>): void => {
+    setNickname(event.target.value)
+    settingsState.nickname = event.target.value
+  }
+
+  const handleNotifyChange = (event: ChangeEvent<HTMLInputElement>): void => {
+    setNotifyEnabled(event.target.checked)
+    settingsState.notifyEnabled = event.target.checked
+  }
+
+  const handleThemeChange = (event: ChangeEvent<HTMLSelectElement>): void => {
+    setTheme(event.target.value as 'light' | 'dark')
+    settingsState.theme = event.target.value as 'light' | 'dark'
+  }
+
+  return (
+    <section style={{ padding: '8px 0' }}>
+      <h3 style={{ margin: '4px 0' }}>设置（子应用路由 /settings，本地状态）</h3>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, margin: '8px 0', maxWidth: 320 }}>
+        <label>昵称：<input value={nickname} onChange={handleNicknameChange} /></label>
+        <label>
+          <input type="checkbox" checked={notifyEnabled} onChange={handleNotifyChange} /> 接收通知
+        </label>
+        <label>
+          主题：
+          <select value={theme} onChange={handleThemeChange}>
+            <option value="light">浅色</option>
+            <option value="dark">深色</option>
+          </select>
+        </label>
+      </div>
+      <p style={{ color: '#666', fontSize: 13, margin: '4px 0' }}>
+        本表单为子应用本地状态（不在 URL 中）。路由往返后设置仍在 → 子应用未重挂、store 未重建。
+      </p>
+    </section>
+  )
+}

package/examples/templates/showcase/react-remote/src/settings-store.ts

@@ -0,0 +1,11 @@
+/**
+ * examples/templates/showcase/react-remote/src/settings-store.ts — 设置页本地状态（模块级对象，刻意不写入 URL）。
+ * 子应用 root 不重挂 → 模块不重建：路由往返后设置仍保留，佐证「内部状态跨路由保留」。
+ */
+export interface SettingsState {
+  nickname: string
+  notifyEnabled: boolean
+  theme: 'light' | 'dark'
+}
+
+export const settingsState: SettingsState = { nickname: '张三', notifyEnabled: true, theme: 'light' }

package/examples/templates/showcase/react-remote/tsconfig.json

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

package/examples/templates/showcase/react-remote/vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { federation } from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config.ts'
+
+export default defineConfig(({ command }) => ({
+  base: command === 'build' ? '/react-remote/' : undefined,
+  // react-router-dom 必须正常进预构建（同 e2e 实测的 fixtures/remote-react：不 exclude、不 alias）：
+  // 1) 其传递依赖 cookie 是 CJS-only 包，exclude 后走源码会在浏览器报
+  //    "does not provide an export named 'parse'"；
+  // 2) 预构建内的 react 导入不会双实例——插件 dev 会向预构建注入 shared 键外部化
+  //    resolver（fulgurjs:optimize-shared-external），react 运行时仍协商到 shared singleton 门面。
+  plugins: [react(), federation(fulgurjsConfig)],
+}))

package/examples/templates/showcase/scripts/dev.config.json

@@ -0,0 +1,8 @@
+{
+  "apps": [
+    { "name": "vue-remote", "dir": "vue-remote", "port": 5335 },
+    { "name": "react-remote", "dir": "react-remote", "port": 5333 },
+    { "name": "vue-host", "dir": "vue-host", "port": 5334 },
+    { "name": "react-host", "dir": "react-host", "port": 5336 }
+  ]
+}

package/examples/templates/showcase/scripts/dev.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * 模板统一 dev 启动器（规范源）。
+ *
+ * 本文件经 examples/scripts/sync-template-scripts.mjs 同步到五个模板的 scripts/dev.mjs；
+ * 模板内副本必须与规范源逐字节一致（check-catalog.mjs 校验哈希），模板复制出仓库后独立可用——
+ * 只依赖同目录 dev.config.json 与 Node 内置模块，不依赖仓库其他文件。
+ *
+ * 行为契约（与模板 README 一致）：
+ * - 启动前预检全部端口：任何端口被占用则拒绝启动并指认处理方法（绝不按端口杀别人的进程）；
+ * - 按 dev.config.json 顺序（远程在前宿主在后）启动各应用，逐个探活；
+ * - 任一应用启动失败/超时/中途退出：整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ * - Ctrl+C / SIGTERM：清理本次启动的全部子进程后退出；不依赖 PID 文件；
+ * - 全部就绪后打印访问入口；探活 = 端口可连接（dev server 已监听），页面可用以浏览器验收为准。
+ *
+ * 平台：macOS/Linux 实测；Windows 走 taskkill 兜底路径，未经验证（见模板 README）。
+ */
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import net from 'node:net'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const { apps, readyTimeoutMs = 120000 } = JSON.parse(
+  fs.readFileSync(path.join(templateRoot, 'scripts', 'dev.config.json'), 'utf8'),
+)
+const isTTY = process.stdout.isTTY
+const color = (code, text) => (isTTY ? `\x1b[${code}m${text}\x1b[0m` : text)
+const EXIT = { ok: 0, startupFailed: 1, portConflict: 2, signal: 130 }
+
+/** 双栈端口探测（vite 可能只绑 IPv4 或 IPv6 回环） */
+function isPortUp(port) {
+  const probe = (host) =>
+    new Promise((resolve, reject) => {
+      const s = net.connect({ port, host, timeout: 800 })
+      s.on('connect', () => { s.destroy(); resolve(true) })
+      s.on('error', reject)
+      s.on('timeout', () => { s.destroy(); reject(new Error('timeout')) })
+    })
+  return Promise.any([probe('127.0.0.1'), probe('::1')]).catch(() => false)
+}
+
+const tailOf = new Map()
+const children = new Map()
+let shuttingDown = false
+
+function recordOutput(name, chunk) {
+  const lines = (tailOf.get(name) ?? [])
+  for (const line of String(chunk).split('\n')) {
+    if (line === '') continue
+    lines.push(line)
+  }
+  while (lines.length > 60) lines.shift()
+  tailOf.set(name, lines)
+}
+
+function printAppLine(name, text) {
+  process.stdout.write(`${color('2', `[${name}]`)} ${text}\n`)
+}
+
+async function preflight() {
+  const conflicts = []
+  for (const app of apps) {
+    if (await isPortUp(app.port)) conflicts.push(app)
+  }
+  if (conflicts.length === 0) return
+  console.error(color('31', '[dev] 启动前检查失败：以下端口已被占用（不区分占用者，一律不启动）：'))
+  for (const app of conflicts) {
+    const posix = `lsof -nP -iTCP:${app.port} -sTCP:LISTEN`
+    const win = `netstat -ano | findstr :${app.port}`
+    console.error(
+      `  ${app.name} → 端口 ${app.port} 已监听。查看占用：${process.platform === 'win32' ? win : posix}；` +
+        `结束占用进程，或同步修改 ${app.dir}/package.json 的 dev/preview 端口与宿主 fulgurjs.config.ts 的 remotes dev 地址后重试`,
+    )
+  }
+  console.error('[dev] 本启动器只清理自己启动的进程，不会替你结束端口上的既有服务。')
+  process.exit(EXIT.portConflict)
+}
+
+function spawnApp(app) {
+  const child = spawn('pnpm', ['--dir', app.dir, 'run', 'dev'], {
+    cwd: templateRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // POSIX：独立进程组，便于整组终止；Windows：shell 解析 pnpm.cmd，树杀交给 taskkill
+    detached: true,
+    shell: process.platform === 'win32',
+  })
+  children.set(app.name, child)
+  child.stdout.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  child.stderr.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  return child
+}
+
+const exitedOnce = (child) =>
+  new Promise((resolve) => {
+    child.once('exit', (code, signal) => resolve({ code, signal }))
+    child.once('error', (e) => resolve({ code: -1, signal: null, error: e }))
+  })
+
+async function waitReady(app, child) {
+  const exited = exitedOnce(child)
+  const deadline = Date.now() + readyTimeoutMs
+  while (Date.now() < deadline) {
+    if (await isPortUp(app.port)) return { ok: true }
+    const done = await Promise.race([exited.then(() => 'exit'), new Promise((r) => setTimeout(() => r('tick'), 400))])
+    if (done === 'exit') return { ok: false, reason: `进程提前退出（启动命令失败——看下方日志尾部）` }
+  }
+  return { ok: false, reason: `${Math.round(readyTimeoutMs / 1000)}s 内端口 ${app.port} 未就绪（dev server 未监听）` }
+}
+
+function killTree(appName) {
+  const child = children.get(appName)
+  if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise((resolve) => {
+    const force = setTimeout(() => {
+      try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, 'SIGKILL') } catch { /* 已退出 */ }
+    }, 3000).unref()
+    child.once('exit', () => { clearTimeout(force); resolve() })
+    try {
+      if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+      else process.kill(-child.pid, 'SIGTERM')
+    } catch { clearTimeout(force); resolve() }
+  })
+}
+
+async function shutdown(exitCode, reason) {
+  if (shuttingDown) return
+  shuttingDown = true
+  if (reason) console.log(`[dev] ${reason}`)
+  console.log(`[dev] 正在停止本次启动的 ${children.size} 个应用…`)
+  await Promise.all([...children.keys()].map(killTree))
+  console.log('[dev] 已全部停止。')
+  process.exit(exitCode)
+}
+
+process.on('SIGINT', () => void shutdown(EXIT.signal, '[dev] 收到 Ctrl+C'))
+process.on('SIGTERM', () => void shutdown(143, '[dev] 收到 SIGTERM'))
+
+await preflight()
+
+console.log(`[dev] 模板 ${path.basename(templateRoot)}：按顺序启动 ${apps.map((a) => a.name).join(' → ')}`)
+for (const app of apps) {
+  printAppLine(app.name, `启动（pnpm --dir ${app.dir} run dev），等待端口 ${app.port} 就绪…`)
+  const child = spawnApp(app)
+  const ready = await waitReady(app, child)
+  if (!ready.ok) {
+    console.error(color('31', `\n[dev] 启动失败：${app.name} —— ${ready.reason}`))
+    const tail = tailOf.get(app.name) ?? []
+    if (tail.length) {
+      console.error(color('31', `[dev] ${app.name} 日志尾部（最后 ${tail.length} 行）：`))
+      for (const line of tail) console.error(`  [${app.name}] ${line}`)
+    }
+    await Promise.all([...children.keys()].map(killTree))
+    console.error(`[dev] 已停止本次启动的全部进程（${children.size} 个）。修复上面的问题后重新运行 pnpm dev。`)
+    process.exit(EXIT.startupFailed)
+  }
+  printAppLine(app.name, `就绪 → http://localhost:${app.port}/`)
+}
+
+console.log(color('32', '\n[dev] 全部应用已就绪：'))
+for (const app of [...apps].reverse()) {
+  console.log(`  http://localhost:${app.port}/    ${app.name}`)
+}
+console.log('[dev] Ctrl+C 停止全部应用（只清理本次启动的进程）。dev server 已监听 ≠ 页面必然可用，验收请以浏览器实际加载为准。\n')
+
+// 运行期任何子应用退出（崩溃/被外部杀掉）→ 整组停止，不让半残组合冒充正常运行
+for (const [name, child] of children) {
+  child.once('exit', (code) => {
+    if (!shuttingDown) void shutdown(EXIT.startupFailed, `[dev] ${name} 意外退出（退出码 ${code}）——停止其余应用`)
+  })
+}
+await new Promise(() => {})

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

@@ -0,0 +1,21 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * Vue 宿主联邦配置（examples/templates/showcase/vue-host，端口 5334）。
+ * 桥接宿主双框架安装合同：vue + react + react-dom 三键全部 singleton——
+ * React 子应用的 shared 实例经此协商单例，缺失会表现为 Invalid hook call / 双实例（MFU-010）。
+ */
+export default {
+  name: 'vue-host',
+  remotes: {
+    'react-remote': {
+      dev: 'http://localhost:5333',
+      prod: '/react-remote',
+    },
+  },
+  shared: {
+    vue: { singleton: true },
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/templates/showcase/vue-host/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-host（桥接 URL 同步宿主 × React 子应用，5334）</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

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

@@ -0,0 +1,25 @@
+{
+  "name": "fulgurjs-demo-bridge-vue-host",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5334 --strictPort",
+    "build": "vite build",
+    "preview": "vite preview --port 5334 --strictPort",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@fulgurjs/federation": "5.9.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.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"
+  }
+}