@fulgurjs/federation 6.8.7 → 6.9.1

package/examples/templates/vue-host-react-remote/pnpm-workspace.yaml

@@ -2,7 +2,7 @@ packages:
   - vue-host
   - react-remote
 minimumReleaseAgeExclude:
-  - '@fulgurjs/federation@6.8.5'
+  - '@fulgurjs/federation@6.9.0'
 # pnpm >=12 构建脚本批准（12 起弃用 onlyBuiltDependencies；pnpm 9-11 忽略本键：
 # esbuild >=0.16 二进制经 optionalDependencies 平台包分发，postinstall 仅校验，不阻塞安装）
 allowBuilds:

package/examples/templates/vue-host-react-remote/react-remote/README.md

@@ -1,25 +1,25 @@
-# bridge-react-remote — React 桥接子应用示例
+# react-remote — React 子应用
 
-`@fulgurjs/federation` 跨框架桥接的 **React 18/19 子应用**侧示例：以 `defineBridgeApp`（`@fulgurjs/federation/react`）导出 `mount/unmount` 契约，可被 **Vue 宿主**（配合 `examples/templates/vue-host-react-remote/vue-host-react-remote/vue-host`）整站挂载。
+本模板对应未验收的 6.9.0 源码候选，状态与安装方法见[组合说明](../README.md)。复制整个组合目录，在组合根启动。
 
-## 运行
+## 按顺序读源码
 
-复制整个 `vue-host-react-remote/` 模板，在模板根执行：
+1. `fulgurjs.config.ts`：`./bridge` 直接 expose `src/application.tsx`，公开模块名称不受文件名称约束。
+2. `src/application.tsx`：`defineApplication` 唯一装配；独立模式用浏览器路由，桥接模式用本地 memory 路由，两者显示同一套真实页面、计数与 props。
+3. `src/main.tsx`：只调用 application.start，不再复制初始化或新增转发文件。
+4. `vue-host/`：宿主的挂载、会话与回调，见[组合说明](../README.md)。
 
-```bash
-pnpm install --frozen-lockfile
-pnpm dev                         # 同时启动宿主和子应用
-pnpm build                       # 构建完整组合
-# 单独启动本应用：pnpm --dir react-remote dev
-```
+应用代码只从 `@fulgurjs/federation/react` 导入插件 API；子应用不因跨框架嵌入而安装另一框架。这个基础组合不启用宿主 URL 同步；需要地址双向同步时使用 showcase 模板。
 
-端口、复制范围与部署路径见[组合说明](../README.md)。
+独立启动可以切换首页/关于页，桥接也使用相同页面；卸载与首次挂载由插件管理。Vue 返回未安装的 app/router，React 返回 BrowserRouter/MemoryRouter 内的同一组件树。
 
-## 关键点
+## 运行
 
-- `src/bridge.tsx`：`defineBridgeApp((props) => <MemoryRouter>…</MemoryRouter>)`，作为 `./bridge` expose 的默认导出。
-- `mount` 的 Promise 在**首次根提交完成后**才 resolve（契约内建提交探针）；首次渲染前报错会拒绝挂载并转 MFU-016。
-- `react-dom/client` 在实际 mount 时才按需加载；共享子路径 `react-dom/client` 与 `react/jsx-runtime` 由宿主/子应用 shared 配方协商单实例。
-- 子应用只安装并共享 `react` + `react-dom`（+ `react-router-dom` 为直接依赖），**不安装 Vue**。
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+pnpm build
+pnpm prod
+```
 
-配套阅读：根目录 README §8.2「跨框架桥接 API — /bridge」。
+以上正式安装命令须在 6.9.0 发布后执行；候选验收先按组合根的候选说明使用本轮 tarball。

package/examples/templates/vue-host-react-remote/react-remote/fulgurjs.config.ts

@@ -1,14 +1,14 @@
 import type { FederationOptions } from '@fulgurjs/federation'
 
 /**
- * React 子应用联邦配置：`./bridge` expose = defineBridgeApp 契约模块（任务书 §3.3）。
+ * React 子应用联邦配置：`./bridge` expose = defineApplication 统一应用契约。
  * 子应用只安装并共享自己的框架（react + react-dom），不为桥接安装 Vue。
  */
 export default {
   name: 'bridge-react-remote',
   filename: 'fulgurjs-remoteEntry.js',
   exposes: {
-    './bridge': './src/bridge.tsx',
+    './bridge': './src/application.tsx',
   },
   shared: {
     react: { singleton: true },

package/examples/templates/vue-host-react-remote/react-remote/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "6.8.5",
+    "@fulgurjs/federation": "6.9.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^7.1.0"

package/examples/templates/vue-host-react-remote/react-remote/src/{bridge.tsx → application.tsx}

@@ -1,12 +1,6 @@
-/**
- * React 子应用桥接契约（./bridge expose 的默认导出，任务书 §3.3）。
- *
- * defineBridgeApp 工厂接收 props 快照、返回 ReactElement；
- * createRoot/首次提交探测/unmount 由契约实现负责（react-dom/client 在实际 mount 时按需加载）。
- */
 import { useEffect, useState } from 'react'
-import { MemoryRouter, Route, Routes, useLocation, useNavigate } from 'react-router-dom'
-import { defineBridgeApp } from '@fulgurjs/federation/react'
+import { BrowserRouter, MemoryRouter, Route, Routes, useLocation, useNavigate } from 'react-router-dom'
+import { defineApplication } from '@fulgurjs/federation/react'
 
 /** 挂载即回调（宿主验证函数引用跨 root 传递） */
 function OnReady({ onReady }: { onReady?: () => void }) {
@@ -27,14 +21,16 @@ function Counter() {
   )
 }
 
-function Shell(props: Record<string, unknown>) {
+export interface BridgeReactProps { label?: string; onReady?: () => void }
+
+function Shell(props: BridgeReactProps) {
   const location = useLocation()
   const navigate = useNavigate()
   return (
     <div style={{ border: '1px solid #61dafb', borderRadius: 8, padding: 12, fontFamily: 'sans-serif' }}>
       <p style={{ margin: '0 0 6px', fontWeight: 600, color: '#0b7285' }}>React 子应用</p>
       <p data-testid="demo-react-props" style={{ margin: '0 0 6px' }}>
-        {`appProps.label = ${(props as any).label || '（未传）'}`}
+        {`appProps.label = ${props.label || '（未传）'}`}
       </p>
       <p data-testid="demo-react-route" style={{ margin: '0 0 8px' }}>{`memory 路由：${location.pathname}`}</p>
       <nav style={{ marginBottom: 8 }}>
@@ -50,17 +46,10 @@ function Shell(props: Record<string, unknown>) {
   )
 }
 
-export function App() {
-  return (
-    <MemoryRouter>
-      <Shell />
-    </MemoryRouter>
-  )
-}
-
-export default defineBridgeApp((props) => (
-  <MemoryRouter>
-    <OnReady onReady={(props as any).onReady} />
-    <Shell {...props} />
-  </MemoryRouter>
-))
+// 独立入口与桥接共享同一套页面、状态和 onReady。
+export default defineApplication<BridgeReactProps>((props, { mode }) => {
+  const content = <><OnReady onReady={props.onReady} /><Shell {...props} /></>
+  return mode === 'bridge'
+    ? <MemoryRouter>{content}</MemoryRouter>
+    : <BrowserRouter basename={import.meta.env.BASE_URL}>{content}</BrowserRouter>
+})

package/examples/templates/vue-host-react-remote/react-remote/src/main.tsx

@@ -1,7 +1,2 @@
-import { createElement } from 'react'
-import { createRoot } from 'react-dom/client'
-import { App } from './bridge'
-
-// 独立运行入口：单独开发/调试子应用自身时使用。
-// 被桥接宿主消费时走 fulgurjs-remoteEntry.js 容器入口与 ./bridge 契约，与本文件无关。
-createRoot(document.getElementById('root')!).render(createElement(App))
+import application from './application'
+void application.start('#root', { label: '独立 React 子应用' }).catch(console.error)

package/examples/templates/vue-host-react-remote/scripts/prod.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/** Standalone template production launcher. Uses only Node and the existing dev.config.json. */
+import fs from 'node:fs'
+import path from 'node:path'
+import http from 'node:http'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const { apps } = JSON.parse(fs.readFileSync(path.join(root, 'scripts/dev.config.json'), 'utf8'))
+if (!Array.isArray(apps) || !apps.length) throw new Error('dev.config.json 未登记应用。')
+
+const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.woff': 'font/woff', '.woff2': 'font/woff2', '.map': 'application/json' }
+const inside = (file, directory) => file === directory || file.startsWith(directory + path.sep)
+const mounts = apps.map(app => {
+  const dir = path.resolve(root, app.dir, 'dist')
+  if (!inside(dir, root)) throw new Error(`${app.name}: 构建目录超出模板。`)
+  const index = path.join(dir, 'index.html')
+  if (!fs.existsSync(index)) throw new Error(`${app.name}: 缺少 dist/index.html，请先 pnpm build。`)
+  const html = fs.readFileSync(index, 'utf8')
+  const tags = [...html.matchAll(/<script\b[^>]*>/gi)]
+  const tag = tags.find(item => /\btype=["']module["']/i.test(item[0]))?.[0]
+  const src = tag?.match(/\bsrc=["']([^"']+)["']/i)?.[1]
+  if (!src || /^(?:https?:)?\/\//.test(src)) throw new Error(`${app.name}: 无可本地挂载的模块入口。`)
+  // Resolve the actual emitted file suffix, rather than guessing base from an app name.
+  const pathname = decodeURIComponent(new URL(src, 'http://template.local/').pathname)
+  const parts = pathname.split('/').filter(Boolean)
+  const bases = []
+  for (let i = 0; i < parts.length; i++) {
+    const file = path.resolve(dir, ...parts.slice(i))
+    if (inside(file, dir) && fs.existsSync(file) && fs.statSync(file).isFile()) bases.push('/' + parts.slice(0, i).join('/') + (i ? '/' : ''))
+  }
+  if (bases.length !== 1) throw new Error(`${app.name}: 无法唯一对应构建入口 ${src}；检查 Vite base 和干净构建输出。`)
+  return { ...app, dir, prefix: bases[0] }
+})
+const hosts = mounts.filter(app => app.host)
+if (!hosts.length) throw new Error('dev.config.json 未登记 host:true 的宿主。')
+const ports = new Set()
+const servers = []
+let stopping = false
+function stop(code = 0) {
+  if (stopping) return
+  stopping = true
+  for (const server of servers) server.close()
+  const timer = setTimeout(() => {
+    for (const server of servers) server.closeAllConnections?.()
+    process.exit(code)
+  }, 1000)
+  timer.unref()
+  process.exitCode = code
+}
+process.once('SIGINT', () => stop(0))
+process.once('SIGTERM', () => stop(0))
+process.once('uncaughtException', error => { console.error(error); stop(1) })
+
+for (const host of hosts) {
+  if (!Number.isInteger(host.port) || host.port < 1 || host.port > 65535 || ports.has(host.port)) throw new Error(`无效或重复宿主端口：${host.port}`)
+  ports.add(host.port)
+  const site = [host, ...mounts.filter(app => !app.host)].sort((a, b) => b.prefix.length - a.prefix.length)
+  const prefixes = new Set()
+  for (const app of site) {
+    if (prefixes.has(app.prefix)) throw new Error(`${host.name}: 构建 base ${app.prefix} 冲突；宿主和远程不能部署在同一路径。`)
+    prefixes.add(app.prefix)
+  }
+  const server = http.createServer((req, res) => {
+    try {
+      const url = new URL(req.url, `http://localhost:${host.port}`)
+      if (url.pathname === '/' && host.prefix !== '/') {
+        res.writeHead(302, { location: host.prefix, 'cache-control': 'no-cache' })
+        return res.end()
+      }
+      const app = site.find(item => url.pathname === item.prefix.slice(0, -1) || url.pathname.startsWith(item.prefix))
+      if (!app) { res.writeHead(404); return res.end('未登记此部署路径') }
+      const relative = decodeURIComponent(url.pathname.slice(app.prefix.length)) || 'index.html'
+      let file = path.resolve(app.dir, relative)
+      if (!inside(file, app.dir)) { res.writeHead(403); return res.end() }
+      if (!fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+        if (path.extname(relative)) { res.writeHead(404); return res.end('资源不存在；不会回退成HTML') }
+        file = path.join(app.dir, 'index.html')
+      }
+      const stable = /(?:^|\/)(?:index\.html|fulgurjs-(?:remoteEntry\.js|manifest\.json)|_app\.config\.js)$/.test(file)
+      res.writeHead(200, {
+        'content-type': mime[path.extname(file)] ?? 'application/octet-stream',
+        'cache-control': stable ? 'no-cache' : 'public, max-age=31536000, immutable',
+        'access-control-allow-origin': '*',
+      })
+      res.end(fs.readFileSync(file))
+    } catch (error) {
+      console.error(`生产请求失败：${error.message}`)
+      if (!res.headersSent) res.writeHead(400)
+      res.end('无效请求或资源不可读')
+    }
+  })
+  servers.push(server)
+  server.on('error', error => {
+    console.error(`${host.name}:${host.port} 启动失败：${error.message}；停止本次全部生产服务器，不会按端口杀已有进程。`)
+    stop(1)
+  })
+  server.listen(host.port, '127.0.0.1', () => {
+    if (!stopping) console.log(`生产宿主 ${host.name}: http://localhost:${host.port}${host.prefix}（仅dist，无开发服务器）`)
+  })
+}

package/examples/templates/vue-host-react-remote/vue-host/package.json

@@ -11,7 +11,7 @@
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "6.8.5",
+    "@fulgurjs/federation": "6.9.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "vue": "^3.5.13"

package/examples/templates/vue-host-react-remote/vue-host/src/application.ts

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import { defineApplication } from '@fulgurjs/federation/vue'
+import App from './App.vue'
+
+export default defineApplication(() => createApp(App))

package/examples/templates/vue-host-react-remote/vue-host/src/main.ts

@@ -1,4 +1,2 @@
-import { createApp } from 'vue'
-import App from './App.vue'
-
-createApp(App).mount('#app')
+import application from './application'
+void application.start('#app').catch(console.error)

package/examples/templates/vue-vue/README.md

@@ -1,5 +1,8 @@
 # Vue 联邦示例：宿主 + 远程（可直接复制运行）
 
+> 本目录是 6.9.0 源码候选：已改用 defineApplication，尚未测试和发布。源码依赖已锁定 6.9.0；正式发布前不要拿旧 registry 包运行这份代码。验收先使用本次候选 tarball，发布后再按下列冻结安装命令验证正式包。
+
+
 本目录是一对完整、可独立安装运行的 Vue 3 模块联邦演示：
 
 | 目录 | 角色 | 端口 | 说明 |
@@ -7,7 +10,7 @@
 | [`remote/`](./remote/) | **Vue 远程**（被消费方） | 5213 | 暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页 |
 | [`host/`](./host/) | **Vue 宿主**（消费方） | 5214 | 消费 vue-remote 的组件/模块/页面，提供导航与懒加载 |
 
-- 包管理器为 **pnpm**；复制整个模板目录，包含 workspace 和锁文件。插件使用 registry 正式精确版本。
+- 包管理器为 **pnpm**；复制整个模板目录，包含 workspace 和锁文件。插件精确依赖本轮 6.9.0；正式包是否可用见本页顶部状态。
 
 ## 最快开始（从干净拷贝）
 
@@ -105,3 +108,24 @@ server {
 - 改remote（默认 5213）：① `remote/package.json` 的 `dev` 与 `preview` 两个脚本的 `--port 5213`；② `host/fulgurjs.config.ts` 里 `remotes['vue-remote'].dev` 的 `http://localhost:5213`；③ 根 `scripts/dev.config.json` 里 remote 的 `port`（**必改**：启动器预检/探活都读它）；④ 本 README 顶部端口表。
 - 改host（默认 5214）：① `host/package.json` 的 `dev`/`preview` `--port 5214`；② `scripts/dev.config.json`；③ 本 README 端口表。
 - 生产部署地址（`prod`，如 `/remote`）是站点路径，与 dev 端口无关，改端口不要动它。改名（容器名）不建议：还需同步 spec 前缀与页面表。
+
+## 一键运行生产产物
+
+```bash
+pnpm build
+pnpm prod
+```
+
+`prod` 只服务本次 dist，不启动远程开发服务器。它复用 scripts/dev.config.json 的宿主端口，从实际构建入口推导 base，并把远程静态产物挂在同源子路径。无需为本地复现手写 Nginx；部署真实服务器时仍按部署指南配置。多宿主模板分别启动各宿主地址，不把两个宿主的根资源混在一起。先停止 dev，端口占用会失败并停止本次已起服务；不会关闭已有占用进程。Ctrl+C 关闭本次生产服务。
+
+## 插件代码阅读地图
+
+| 文件 | 职责 |
+|---|---|
+| `host/src/application.ts` | 本应用唯一装配；main 只负责调用 start |
+| `remote/src/application.ts` | 本应用唯一装配；main 只负责调用 start |
+| `host/fulgurjs.config.ts` | 本应用的远程地址、exposes、实际共享依赖 |
+| `remote/fulgurjs.config.ts` | 本应用的远程地址、exposes、实际共享依赖 |
+| `scripts/dev.mjs` / `scripts/prod.mjs` | 统一开发/生产启动器；业务接入不复制它们到应用源码 |
+
+`application` 是新增的插件装配文件，`main` 是已有入口接线；页面组件、业务路由、权限和数据不是每个项目都必写的联邦配置。跨框架基础组合不逐页登记子应用菜单；逐页远程页面模板的页面表仅服务它所展示的逐页场景。`src/fulgurjs/types/` 是插件生成目录，按远程实际版本同步，不维护人工伪造的声明或旧缓存。

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

@@ -11,7 +11,7 @@
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "6.8.5",
+    "@fulgurjs/federation": "6.9.0",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0"
   },

package/examples/templates/vue-vue/host/src/application.ts

@@ -0,0 +1,54 @@
+import { createApp, h } from 'vue'
+import { createRouter, createWebHistory, useRoute } from 'vue-router'
+import { defineApplication, createHostPages } from '@fulgurjs/federation/vue'
+import App from './App.vue'
+import HomePage from './pages/HomePage.vue'
+import UtilsDemo from './pages/UtilsDemo.vue'
+import { pages, remotePrefixes } from '../fulgurjs.config.ts'
+
+// 页面适配器：URL 解析、最长前缀远程归属、异步组件缓存、
+// 加载/错误占位（含「重试加载 / 刷新页面重试」）全部由插件完成。
+const hostPages = createHostPages({
+  pages,
+  remotePrefixes,
+})
+
+// 远程页面 Router 记录从页面表派生（route + spec 唯一来源 = fulgurjs.config.ts 的 pages；
+// 业务自有路由仍归本 Router 管理——业务 Router 与联邦页面映射是两类事实）。
+// 远程名按最长前缀从 remotePrefixes 解析（与运行时归属一致）；params + query 全量透传给
+// 远程页面组件（响应式：路由变化即重渲染）。
+const remoteNameOf = (route: string): string => {
+  const prefix = Object.keys(remotePrefixes)
+    .filter((p) => route === p || route.startsWith(p + '/') || route.startsWith(p))
+    .sort((a, b) => b.length - a.length)[0]
+  const name = prefix ? remotePrefixes[prefix] : undefined
+  if (!name) throw new Error(`页面 ${route} 不匹配任何 remotePrefixes 前缀——请核对 fulgurjs.config.ts`)
+  return name
+}
+const remoteRoutes = pages.map((page) => ({
+  path: page.route,
+  component: {
+    setup() {
+      const route = useRoute()
+      return () =>
+        h(hostPages.component(`${remoteNameOf(page.route)}/${page.spec}`), {
+          ...route.params,
+          ...route.query,
+        })
+    },
+  },
+}))
+
+// 应用装配只写一次；每次 start 创建自己的 router。
+export default defineApplication(() => {
+  const router = createRouter({
+    history: createWebHistory(import.meta.env.BASE_URL),
+    routes: [
+      { path: '/', component: HomePage },
+      { path: '/utils-demo', component: UtilsDemo },
+      ...remoteRoutes,
+    ],
+  })
+
+  return { app: createApp(App), router }
+})

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

@@ -1,51 +1,4 @@
-import { createApp, h } from 'vue'
-import { createRouter, createWebHistory, useRoute } from 'vue-router'
-import { createHostPages } from '@fulgurjs/federation/vue'
-import App from './App.vue'
-import HomePage from './pages/HomePage.vue'
-import UtilsDemo from './pages/UtilsDemo.vue'
-import { pages, remotePrefixes } from '../fulgurjs.config.ts'
+import application from './application'
 
-// 页面适配器：URL 解析、最长前缀远程归属、异步组件缓存、
-// 加载/错误占位（含「重试加载 / 刷新页面重试」）全部由插件完成。
-const hostPages = createHostPages({
-  pages,
-  remotePrefixes,
-})
-
-// 远程页面 Router 记录从页面表派生（route + spec 唯一来源 = fulgurjs.config.ts 的 pages；
-// 业务自有路由仍归本 Router 管理——业务 Router 与联邦页面映射是两类事实）。
-// 远程名按最长前缀从 remotePrefixes 解析（与运行时归属一致）；params + query 全量透传给
-// 远程页面组件（响应式：路由变化即重渲染）。
-const remoteNameOf = (route: string): string => {
-  const prefix = Object.keys(remotePrefixes)
-    .filter((p) => route === p || route.startsWith(p + '/') || route.startsWith(p))
-    .sort((a, b) => b.length - a.length)[0]
-  const name = prefix ? remotePrefixes[prefix] : undefined
-  if (!name) throw new Error(`页面 ${route} 不匹配任何 remotePrefixes 前缀——请核对 fulgurjs.config.ts`)
-  return name
-}
-const remoteRoutes = pages.map((page) => ({
-  path: page.route,
-  component: {
-    setup() {
-      const route = useRoute()
-      return () =>
-        h(hostPages.component(`${remoteNameOf(page.route)}/${page.spec}`), {
-          ...route.params,
-          ...route.query,
-        })
-    },
-  },
-}))
-
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    { path: '/', component: HomePage },
-    { path: '/utils-demo', component: UtilsDemo },
-    ...remoteRoutes,
-  ],
-})
-
-createApp(App).use(router).mount('#app')
+// 独立入口只负责启动；初始化写在 application 中。
+void application.start('#app').catch(console.error)

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

@@ -6,6 +6,7 @@
     "dev:remote": "pnpm --dir remote dev",
     "dev:host": "pnpm --dir host dev",
     "dev": "node scripts/dev.mjs",
-    "build": "pnpm --dir remote build && pnpm --dir host build"
+    "build": "pnpm --dir remote build && pnpm --dir host build",
+    "prod": "node scripts/prod.mjs"
   }
 }