@fulgurjs/federation 5.2.4 → 5.3.0

package/examples/bridge/README.md

@@ -0,0 +1,36 @@
+# 跨框架桥接示例（/bridge）
+
+双向「子应用级跨框架嵌入」的最小可运行组合（README §8.2）：
+
+| 组合 | 宿主 | 子应用 | 端口 |
+|---|---|---|---|
+| Vue 宿主 × React 子应用 | [vue-host](./vue-host)（5314） | [react-remote](./react-remote)（5303） | 先起 5303 |
+| React 宿主 × Vue 子应用 | [react-host](./react-host)（5304） | [vue-remote](./vue-remote)（5313） | 先起 5313 |
+
+四个工程互相独立：`npm install` 即用 registry 正式包；宿主同时安装两套框架并全部 singleton（桥接使用合同），子应用只装自己的框架。
+
+## 快速开始（Vue 宿主 × React 子应用）
+
+```bash
+cd react-remote && npm install && npm run dev    # 终端 1：http://localhost:5303
+cd ../vue-host  && npm install && npm run dev    # 终端 2：http://localhost:5314
+```
+
+打开 5314：点击「切换到 Bob / 登出」体验受控会话（卸载→清 context→新代次重挂）；子应用内部按钮操作其 memory 路由与本地状态。
+
+## 快速开始（React 宿主 × Vue 子应用）
+
+```bash
+cd vue-remote  && npm install && npm run dev     # 终端 1：http://localhost:5313
+cd ../react-host && npm install && npm run dev   # 终端 2：http://localhost:5304
+```
+
+## 生产构建与部署
+
+每个示例 `npm run build` 产出各自子路径（`/bridge-vue-host/` 等）。部署时保持「子应用子路径 + 宿主子路径」并列，宿主 fulgurjs 配置的 `prod` 指向子应用子路径（已是根相对写法）。NGINX 需对各 `fulgurjs-remoteEntry.js`/`fulgurjs-manifest.json`/`index.html` 设置 no-cache，其余静态资源可长缓存。
+
+## 范围声明（v1）
+
+- 只做子应用级挂载/卸载；组件级混渲染（Vue 里直接渲染 React 组件）不支持。
+- 子应用用 memory 路由，不与宿主 URL 同步。
+- 无 JS 沙箱与 CSS 隔离：远程全局样式/body 级副作用会影响宿主，需自行命名空间治理。

package/examples/bridge/react-host/README.md

@@ -0,0 +1,23 @@
+# bridge-react-host — React 宿主 × Vue 桥接子应用示例
+
+`@fulgurjs/federation` 跨框架桥接的 **React 18/19 宿主**侧示例：用 `createReactBridgeApp`（`@fulgurjs/federation/bridge/react`）把 `bridge-vue-remote/bridge` 作为受控组件挂载（入口跑在 StrictMode 下，双 effect 安全由契约保证）。
+
+## 运行
+
+```bash
+# 1) 先启动 Vue 子应用（5313）
+cd ../vue-remote && npm install && npm run dev
+
+# 2) 再启动本宿主（5304）
+npm install
+npm run dev        # http://localhost:5304
+npm run build      # 产出 /bridge-react-host/ 子路径产物
+```
+
+## 关键点（对应 README §8.2）
+
+- **双框架安装合同**：本宿主同时安装 `react` + `react-dom` + `vue`，shared 三键全部 `singleton: true`。
+- **入口选择**：`@fulgurjs/federation/bridge/react` 只携带 React 宿主适配器（零 Vue）。
+- **工厂选项**：`fallback`（加载中占位）、`error`（节点或 `(error, retry) => ReactNode`）、`retries`、`timeout`、`getContext`（同步纯 getter）。
+- **换账号/登出**：受控 `sessionKey` 置 `null` → 等卸载 → `clearAppContext()` → 登录新账号 → 更新受控 prop。
+- 子应用首次根提交前发生错误 → MFU-016（phase: mount）占位；首次提交后子应用内部错误由子应用自己的错误边界负责（跨 root 不冒泡）。

package/examples/bridge/react-host/fulgurjs.config.ts

@@ -0,0 +1,20 @@
+import type { FederationOptions } from '@fulgurjs/federation'
+
+/**
+ * React 桥接宿主联邦配置（双框架安装合同 + 全 singleton，见 vue-host 同款说明）。
+ * 推荐入口：/bridge/react（只携带 React 宿主适配器）。
+ */
+export default {
+  name: 'bridge-react-host',
+  remotes: {
+    'bridge-vue-remote': {
+      dev: 'http://localhost:5313',
+      prod: '/bridge-vue-remote',
+    },
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+    vue: { singleton: true },
+  },
+} satisfies FederationOptions

package/examples/bridge/react-host/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <title>bridge-react-host（React 宿主 × Vue 桥接子应用）</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>